EPU Canonical Object and Service Model

1. Purpose

This document converts the EPU architectural principles into an implementable canonical object and service model.

The model keeps the EPU identity deliberately thin while allowing the connected EPU Product Graph to become arbitrarily rich. Product state, composition, supplier data, calculations, evidence, assurance and disclosures are separate governed objects connected to the EPU through typed, provenance-bearing relationships.

The implementation must preserve the following separation:

EPU identity
    │
    ├── aliases and identity-resolution records
    ├── product-definition versions
    ├── composition / BOM versions
    ├── production contexts and instances
    ├── supplier contributions
    ├── lifecycle events
    ├── evidence and claims
    ├── computation results
    ├── assurance decisions
    └── disclosure projections

The EPU component family is provisionally aligned to the Shared Intelligence Stack (SIS) because SIS owns cross-platform identity, governance, trust and interoperability. Domain-specific ingestion, computation and disclosure remain owned by their respective modules.

2. Architectural boundaries

EPU is a component family, not a replacement for existing ZAYAZ modules.

Responsibility	Primary owner	EPU role
Canonical product identity	SIS / EPU	Owns EPU identity and identity-resolution state
Source ingestion	Input Hub	Creates source-product candidates and source observations
Product graph governance	SIS / EPU	Owns typed relationships, effective dating and graph policy
Sustainability calculations	Computation Hub / MICE	Produces immutable, lineage-complete result artifacts linked to EPU context
Evidence trust and assurance	SIS / TrustGate / verifier services	Scores, validates and governs evidence and claims
Disclosure packaging	Reports & Insights Hub	Produces authorized disclosure projections, including DPP views
Regulatory requirement lineage	Pergamum Pulse	Supplies governed regulatory and standards context

No module should duplicate the canonical EPU identity record.

3. Canonical object classes

3.1 EPUIdentity

The canonical identity anchor.

EPUIdentity
├── epu_id
├── lifecycle_state
├── created_at
├── created_by
├── tenant_scope
├── identity_policy_version
└── governance_metadata

Required invariants:

• epu_id is immutable and non-semantic;
• business attributes are not encoded into the identifier;
• mutable product properties are not stored as identity facts;
• identity deletion is prohibited after governed activation; retirement is represented by lifecycle state;
• tenant isolation and white-label namespace rules apply without changing canonical EPU semantics.

3.2 ExternalAlias

Maps source and public identifiers to an EPU.

ExternalAlias
├── alias_id
├── epu_id
├── identifier_type
├── identifier_value
├── issuing_party
├── source_system
├── valid_from
├── valid_to
├── authority
├── resolution_status
├── provenance_ref
└── confidence

Examples include GTIN, SKU, ERP material ID, PLM/PIM ID, manufacturer part number, supplier product ID and interoperable DPP identifiers.

Uniqueness must be evaluated in the correct authority namespace rather than globally assuming that every external identifier is unique.

3.3 SourceProductCandidate

A source-system product that has not yet been resolved to a canonical EPU.

SourceProductCandidate
├── candidate_id
├── tenant_id
├── source_system
├── source_record_key
├── normalized_identifiers[]
├── characteristic_fingerprint
├── source_snapshot_ref
├── observed_at
├── resolver_status
└── provenance_ref

Candidates are created by ingestion adapters and remain distinct from EPU identities until a governed resolution decision occurs.

3.4 IdentityResolutionDecision

Immutable decision record explaining how a candidate was resolved.

IdentityResolutionDecision
├── decision_id
├── candidate_id
├── outcome
├── target_epu_id?
├── proposed_epu_id?
├── confidence
├── policy_version
├── rule_results[]
├── model_version?
├── evidence_refs[]
├── reviewer?
├── rationale
└── decided_at

Allowed outcomes should include:

MATCH_EXISTING
CREATE_NEW
AMBIGUOUS_REVIEW
REJECT_SOURCE_RECORD
DEFER_INSUFFICIENT_DATA

Automated decisions must remain replayable from preserved inputs, policy versions and resolver versions.

3.5 ProductDefinitionVersion

Versioned mutable product state attached to an EPU.

ProductDefinitionVersion
├── product_definition_version_id
├── epu_id
├── version
├── effective_from
├── effective_to
├── status
├── specification_ref
├── classification_refs[]
├── attribute_set_ref
├── provenance_ref
└── supersedes?

A new product-definition version does not automatically create a new EPU. Identity policy determines whether a material change remains a version change or requires a successor/new EPU.

3.6 ProductRelationship

Canonical typed graph edge.

ProductRelationship
├── relationship_id
├── subject_ref
├── predicate
├── object_ref
├── valid_from
├── valid_to
├── asserted_by
├── source_ref
├── evidence_refs[]
├── confidence
├── access_policy_ref
└── provenance_ref

Relationships may connect EPU to EPU, EPU to ECO/EBU/EBP, product definitions to components/materials, instances to batches, or product objects to governed evidence and results.

Relationship predicates must come from a governed vocabulary or registry. Free-text relationship types are not authoritative.

3.7 CompositionVersion

Versioned composition or BOM snapshot.

CompositionVersion
├── composition_version_id
├── epu_id
├── product_definition_version_id
├── composition_type
├── effective_from
├── effective_to
├── nodes[]
├── edges[]
├── source_system
├── source_snapshot_ref
├── provenance_ref
└── status

Each component node should be capable of resolving to another EPU where that component itself has a governed product identity, while also supporting material/substance nodes that are not EPUs.

3.8 ProductionContext

Provides the actual or modeled production context used by product intelligence and calculations.

ProductionContext
├── production_context_id
├── epu_id
├── site_ref
├── ebu_ref?
├── production_run_ref?
├── batch_lot_ref?
├── time_window
├── applicable_composition_version
├── process_refs[]
├── activity_data_refs[]
└── provenance_ref

Production context is deliberately separate from identity so the same EPU can represent production across locations, suppliers, periods and scenarios.

3.9 ProductInstance

Lightweight physical-instance identity when batch, lot or serialized granularity is required.

ProductInstance
├── instance_id
├── epu_id
├── instance_type
├── batch_lot_ref?
├── serial_identifier?
├── production_context_id?
├── created_at
├── lifecycle_state
└── provenance_ref

instance_type may include BATCH, LOT, SERIALIZED_ITEM and future governed types.

Instance storage must avoid copying the full EPU dossier per physical unit.

3.10 SupplierContribution

Permission-scoped supplier submission linked to the exact scope requested.

SupplierContribution
├── contribution_id
├── epu_id
├── scope_ref
├── contributor_eco_id
├── requested_fields[]
├── submitted_values_ref
├── evidence_refs[]
├── confidentiality_policy_ref
├── verification_state
├── trust_state
├── valid_from
├── valid_to
└── provenance_ref

Supplier contributions remain source assertions until they have passed the required validation, evidence and governance gates.

3.11 SustainabilityResultRef

EPU stores references to governed computation artifacts rather than embedding mutable calculation results into the identity.

SustainabilityResultRef
├── result_ref_id
├── epu_id
├── result_artifact_id
├── result_type
├── scope_ref
├── production_context_id?
├── functional_unit_ref
├── method_version
├── calculation_version
├── generated_at
├── trustgate_state
└── provenance_ref

The authoritative calculation artifact remains owned by Computation Hub/MICE and must preserve complete engine, dataset, factor, method, evidence and uncertainty lineage.

3.12 DisclosureProjectionRef

Links an EPU to a governed disclosure projection.

DisclosureProjectionRef
├── disclosure_ref_id
├── epu_id
├── disclosure_profile_id
├── disclosure_artifact_id
├── audience
├── jurisdiction
├── effective_period
├── publication_state
├── access_policy_ref
└── provenance_ref

The disclosure is a projection over governed product intelligence, never the canonical EPU record itself.

4. Graph edge contract

Every authoritative EPU graph edge must carry enough information to answer four questions:

1. What relationship is asserted?
2. During what period is it valid?
3. Who or what asserted it?
4. What evidence and provenance support it?

Minimum edge envelope:

{
  "relationship_id": "REL-...",
  "subject_ref": "EPU-...",
  "predicate": "manufactured_by",
  "object_ref": "ECO-...",
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_to": null,
  "asserted_by": "source-or-governed-actor-ref",
  "source_ref": "source-artifact-ref",
  "evidence_refs": [],
  "confidence": 0.98,
  "access_policy_ref": "POLICY-...",
  "provenance_ref": "PROV-..."
}

The concrete JSON schema is to be governed separately; this example defines the semantic contract, not the final wire format.

5. Service decomposition

The EPU component family should expose narrowly scoped services rather than one monolithic product service.

5.1 Product Identity Service

Responsibilities:

• create and retrieve EPU identities;
• enforce immutable identifier semantics;
• manage lifecycle state;
• expose canonical product identity references;
• enforce tenant and white-label boundaries.

5.2 Alias Registry Service

Responsibilities:

• normalize and register external identifiers;
• resolve aliases to EPU identities;
• maintain issuer/source namespaces;
• detect collisions and conflicting mappings;
• preserve alias validity periods and provenance.

5.3 Product Identity Resolver

Responsibilities:

• consume SourceProductCandidate objects;
• perform deterministic alias and characteristic matching;
• invoke probabilistic/AI-assisted comparison only where governed;
• produce confidence and explainability artifacts;
• auto-resolve above policy thresholds;
• route ambiguous cases to human review;
• preserve complete decision lineage.

5.4 Product Graph Service

Responsibilities:

• create and query governed product relationships;
• validate predicates and object classes;
• enforce effective dating;
• apply access/discovery policy to graph traversals;
• provide provenance-aware traversal paths;
• expose point-in-time graph reconstruction.

5.5 Product Definition Service

Responsibilities:

• version product technical state;
• retain specification and classification references;
• coordinate Product Identity Change Events;
• preserve historical product-definition snapshots.

5.6 Composition Service

Responsibilities:

• ingest and version BOM/composition structures;
• normalize quantities and units through canonical services;
• resolve component candidates to EPUs where applicable;
• support material and substance nodes;
• preserve source-system snapshots and effective periods.

5.7 Product Instance Service

Responsibilities:

• create lightweight batch/lot/serialized instance records;
• connect instances to production context and lifecycle events;
• support high-volume storage patterns;
• avoid dossier duplication.

5.8 Supplier Contribution Orchestrator

Responsibilities:

• derive missing-data requests from EPU graph requirements;
• scope supplier permissions;
• route requests by ECO identity;
• ingest contributions and evidence;
• trigger validation/TrustGate workflows;
• notify dependent calculations and disclosures when authoritative data changes.

5.9 Product Intelligence Query Gateway

Responsibilities:

• translate authorized product questions into graph traversals and governed computations;
• coordinate EPU, Computation Hub, evidence and disclosure services;
• return answer provenance, confidence and policy context;
• never convert unsupported generative output into authoritative product facts.

6. Product identity lifecycle

Recommended lifecycle:

CANDIDATE
   ↓
RESOLVING
   ├──> AMBIGUOUS_REVIEW
   │         ↓
   └──────> ACTIVE
              ↓
           SUPERSEDED
              ↓
            RETIRED

SUPERSEDED means a successor identity exists. RETIRED means the product identity remains historically resolvable but is no longer active for current business use.

No lifecycle transition may erase historical relationships, calculations, evidence or disclosures.

7. Product Identity Change Event

Material product changes should be evaluated through a durable event and policy decision rather than scattered application logic.

Product change observed
        ↓
ProductIdentityChangeEvent
        ↓
Identity Policy Resolver
        ├── NO_IDENTITY_IMPACT
        ├── NEW_PRODUCT_VERSION
        ├── HUMAN_REVIEW
        └── NEW_EPU_REQUIRED

The decision artifact should preserve:

• prior EPU;
• proposed changed state;
• triggering source event;
• policy/rule version;
• evidence;
• automated scoring if used;
• reviewer and rationale where applicable;
• successor EPU when created.

8. Persistence model

The semantic graph should not force one physical database technology.

A scalable implementation may combine:

• relational persistence for canonical identity, lifecycle, policy and transactional integrity;
• graph-optimized indexes or stores for high-depth traversal;
• object storage for immutable source snapshots, evidence and large artifacts;
• event streams for change propagation and dependent recalculation;
• search indexes for discovery and human-facing lookup;
• analytical stores for portfolio-scale product intelligence.

The canonical contract is the governed object model and event semantics, not a particular database engine.

9. Event model

Important domain events should include:

EPU_CREATED
EPU_STATE_CHANGED
EXTERNAL_ALIAS_REGISTERED
EXTERNAL_ALIAS_CONFLICT_DETECTED
SOURCE_PRODUCT_CANDIDATE_OBSERVED
IDENTITY_RESOLUTION_DECIDED
PRODUCT_DEFINITION_VERSION_CREATED
PRODUCT_IDENTITY_CHANGE_REVIEW_REQUIRED
PRODUCT_RELATIONSHIP_ASSERTED
PRODUCT_RELATIONSHIP_ENDED
COMPOSITION_VERSION_CREATED
PRODUCTION_CONTEXT_CREATED
PRODUCT_INSTANCE_CREATED
SUPPLIER_CONTRIBUTION_REQUESTED
SUPPLIER_CONTRIBUTION_ACCEPTED
EVIDENCE_STATE_CHANGED
SUSTAINABILITY_RESULT_PUBLISHED
DISCLOSURE_READINESS_CHANGED
DISCLOSURE_PROJECTION_PUBLISHED

Events must carry correlation, causation, tenant, actor/service identity and provenance references so downstream recalculation and audit can reconstruct why a change occurred.

10. Concurrency and idempotency

Identity creation and alias registration are high-risk concurrency points.

The implementation must support:

• idempotency keys on source ingestion and identity creation;
• optimistic or serializable conflict handling for alias assignment;
• deterministic normalization before uniqueness evaluation;
• replay-safe event consumers;
• exactly-once business effect even where infrastructure uses at-least-once delivery;
• explicit conflict states rather than silent last-write-wins behavior.

A source-system retry must never create a duplicate EPU simply because the previous acknowledgement was lost.

11. Access and graph-discovery policy

Authorization must apply to both data values and graph topology.

A caller may be permitted to know a product has a supplier contribution without being permitted to discover the identity of a confidential sub-tier supplier. Likewise, a public DPP resolver may expose a disclosure projection without allowing traversal into internal BOM, cost or supplier-risk data.

Policy evaluation therefore needs to control:

READ_OBJECT
READ_ATTRIBUTE
DISCOVER_EDGE
TRAVERSE_EDGE
CREATE_ASSERTION
UPDATE_STATE
CONTRIBUTE_DATA
VIEW_EVIDENCE
VIEW_SOURCE
PUBLISH_DISCLOSURE

All authorization decisions that materially affect disclosure or assurance should be auditable.

12. Temporal and bitemporal requirements

For audit-grade reconstruction, many EPU objects require both:

• valid time — when the fact was true in the product/business domain;
• system time — when ZAYAZ learned, stored or changed the assertion.

This permits questions such as:

• What did ZAYAZ believe about this product on 2026-06-30?
• Which BOM was actually valid for the production batch made on 2026-04-12?
• Which supplier evidence was available when PCF v3 was approved?

Bitemporal support should be implemented for identity mappings, relationships, product-definition versions, compositions and other materially auditable state.

13. Provenance contract

Every material object or relationship should resolve to provenance sufficient to identify:

originating party
originating system
source artifact or source record
observation/ingestion timestamp
normalization/transformation steps
rules or models applied
human interventions
verification/assurance state
supersession chain

Provenance should reference canonical ledger/evidence services rather than being duplicated as free-form text throughout the EPU domain.

14. Integration contract with MICE and Computation Hub

EPU supplies context to computation; it does not own the calculation engine.

A computation request should be able to reference:

epu_id
product_definition_version
composition_version
production_context
batch/lot/instance context if required
functional unit
method profile
scenario profile
required effective date

The returned result artifact must preserve the exact context references so historical results remain reproducible even after the EPU graph evolves.

15. Integration contract with Reports & Insights Hub

Disclosure generation should request an authorized projection for a governed disclosure profile.

DisclosureProfile
      +
EPU context
      +
Effective date
      +
Audience / jurisdiction
      ↓
EPU graph traversal
      ↓
Requirement resolution
      ↓
Evidence + TrustGate checks
      ↓
Disclosure artifact

The disclosure artifact must retain the source EPU context and the versions of requirements, evidence, calculations and policies that were used.

16. Scale targets and partitioning principles

The architecture should remain viable from a small tenant with hundreds of products to industrial customers with millions of product definitions and potentially billions of physical instances/events.

Key principles:

• partition by tenant and stable identity keys without embedding tenant semantics into EPU identifiers;
• keep physical-instance records lightweight;
• use immutable/versioned artifacts for large historical states;
• separate transactional identity paths from analytical graph traversal;
• precompute only derived views that can be invalidated and reproduced;
• design event consumers for horizontal scaling;
• use bounded graph traversal and policy-aware indexes for interactive queries;
• preserve stable references across archival tiers.

17. White-label requirements

White-label deployments may change branding, domain names, UX and external presentation, but must not fork the semantic EPU model.

The platform should separate:

Canonical EPU semantics
        ↓
Tenant policy / configuration
        ↓
White-label presentation and external endpoints

Cross-tenant federation or data exchange must use explicit contracts and never infer equivalence solely from customer-facing identifiers.

18. Non-negotiable implementation invariants

1. EPU identity is immutable and non-semantic.
2. Product state is versioned outside the identity record.
3. Source records are candidates until resolved.
4. Resolution decisions are durable and explainable.
5. Aliases retain authority, namespace and provenance.
6. Graph relationships are typed, effective-dated and provenance-bearing.
7. Historical graph state can be reconstructed.
8. Supplier contribution permissions restrict both data access and graph discovery.
9. Computation results remain owned by Computation Hub/MICE and are referenced by EPU context.
10. DPP and other disclosures are governed projections, not identity records.
11. High-volume physical instances do not duplicate the full EPU dossier.
12. Every material answer can expose supporting graph path, evidence and computation lineage.
13. Identity creation and alias assignment are idempotent and conflict-safe.
14. No product-domain event silently destroys prior evidence, result or disclosure history.
15. White-label customization does not fork canonical semantics.
16. AI may assist matching and interpretation but cannot silently create authoritative product facts.

19. Recommended first implementation slice

The first production slice should stay deliberately small:

1. EPUIdentity
2. ExternalAlias
3. SourceProductCandidate
4. IdentityResolutionDecision
5. ProductDefinitionVersion
6. ProductRelationship
7. Product Identity Service
8. Alias Registry Service
9. Product Identity Resolver
10. Product Graph Service

This slice provides the stable identity backbone required before adding richer composition, supplier contribution, instance, calculation and disclosure orchestration.

A useful acceptance test is:

Given two ERP/PIM source records containing overlapping identifiers and characteristics, ZAYAZ can deterministically resolve them to the same EPU or route the ambiguity for governed review, preserve the full decision lineage, and later reconstruct exactly why the resolution occurred.

That capability should exist before EPU is treated as production-grade infrastructure.