Domain Model

Explore Zeta's core entities — products, stock units, orders, allocations, delivery attempts, evidence, audit events, and command records.

Domain model

Zeta's persistent data model consists of entities for synthetic products, encrypted inventory, marketplace orders, fulfillment decisions, delivery effects, evidence, auditing, idempotency, and durable batch operations. This page documents the entities, enumerations, and relationships that connect those records.

The model is defined primarily in src/Zeta.Core/Model.cs, with persistence constraints configured in src/Zeta.Infrastructure/CommerceDb.cs.

Constants and synthetic scope

All persisted records belong to the synthetic demonstration scope unless a field explicitly records another entity relationship.

demo-business

DEMO-SHOP

synthetic

synthetic-manual

Schema versioninteger

2

Zeta enforces the synthetic boundary across products, identifiers, recipients, imported codes, orders, and fixture evidence. The model does not represent live marketplace or delivery data.

Enumerations

StockState

StockState records the lifecycle state of an individual inventory unit.

AVAILABLE: Eligible for reservation.
RESERVED: Assigned to an order but not yet delivered.
QUARANTINED: Removed from normal availability pending review or because exposure makes reuse unsafe.
DELIVERED: Confirmed as delivered or covered by accepted seller evidence.
INVALID: Not eligible for reservation, including expired units.

OrderState

OrderState records Zeta's internal processing state for an order.

PENDING: Order is available for eligibility checks and reservation.
BLOCKED: A visible hold prevents normal processing.
RESERVED: All required inventory units are allocated.
QUEUED: The order is approved for simulated delivery.
DELIVERING: A durable delivery attempt has started.
FAILED: A definite delivery rejection occurred without exposure.
REVIEW_REQUIRED: The delivery result or inventory state requires manual investigation.
FULFILLED: All assigned units have accepted delivery evidence.
CANCELLED: The order was cancelled before exposure and its safe allocations were released.
CLOSED_EXTERNAL: The order was reviewed as handled externally before any allocation existed.
CLOSED_EXCEPTION: A reviewed exception was explicitly closed.

Outcome

Outcome records the result returned by the synthetic delivery adapter.

Confirmed
Rejected
Pending
Partial
Unknown
CrashAfterEffect

Pending, Unknown, Partial, and CrashAfterEffect represent outcomes that cannot be treated as a definite rejection. Recovery retains the possible effect and moves the order toward review.

EvidenceKind

EvidenceKind identifies the source represented by a delivery evidence record.

SIMULATED_CHANNEL_ACCEPTED: Synthetic channel evidence for a confirmed delivery result.
SIMULATED_SELLER_ATTESTED: Manual seller attestation for exposed or delivered units.

Entities

Product

A Product represents a synthetic inventory product and provides the parent record for its stock units and exact listing mappings.

Idstring

Unique product identifier.

BusinessIdstring

Business scope containing the product. Synthetic products use demo-business.

Namestring

Display name for the product.

Thresholdinteger

Low-stock threshold. Zeta reports low stock when available quantity is less than or equal to this value.

Versioninteger

Optimistic concurrency version for the product.

The prototype caps the product catalog at 200 products.

ListingMapping

A ListingMapping connects one exact marketplace item and model identity to a Product. Zeta captures the mapping version when it creates an allocation so later mapping changes cannot silently alter an existing reservation.

Marketplacestring

Marketplace identifier for the listing.

Environmentstring

Environment containing the listing, such as synthetic.

Shop IDstring

Shop containing the listing.

Item IDstring

Marketplace item identifier.

Model IDstring

Marketplace model or variation identifier.

Product IDstring

Product assigned to the exact listing identity.

Mapping versioninteger

Version used to detect mapping changes after reservation.

Mappings use exact Marketplace, Environment, Shop ID, Item ID, and Model ID matching. Zeta does not perform name, SKU, or fuzzy matching.

StockUnit

A StockUnit represents one encrypted digital inventory code. The unit remains identifiable for allocation, expiry, state transitions, and evidence without storing its plaintext value.

Product associationrelationship

Reference to the product that owns the inventory unit.

AES-GCM ciphertextstring

Encrypted representation of the synthetic code.

HMAC fingerprintstring

Keyed fingerprint used for duplicate detection without decrypting the code.

Import IDstring

Identifier for the import operation that created the unit.

Import timestamptimestamp

Time at which the unit was imported.

Optional expirationtimestamp

Optional expiration time. Expired available units become INVALID.

Stock stateStockState

Current inventory lifecycle state.

Exposure flagboolean

Indicates whether the code was exposed during reveal or an uncertain effect.

Versioninteger

Optimistic concurrency version for the unit.

The plaintext code is not stored in the database. Zeta stores AES-GCM ciphertext and a separate HMAC fingerprint for encryption and duplicate detection.

CustomerOrder

A CustomerOrder represents a synthetic marketplace order observed by Zeta. It stores both the source observation and the internal state used by reservation, approval, delivery, cancellation, and recovery workflows.

Order IDstring

Synthetic marketplace order identifier.

Business/shop/environment scopescope

Business, shop, and environment identifiers that establish the order's synthetic scope.

Raw source statusstring

Status reported by the synthetic marketplace source, such as READY_TO_SHIP.

Paid flagboolean

Indicates whether the source reports the order as paid.

Supported flagboolean

Indicates whether Zeta supports processing the observed order.

Synthetic recipientstring

Recipient used by the synthetic delivery boundary.

Source observation timetimestamp

Time at which Zeta observed the source order.

Source observation versionstring

Source version captured with the order observation.

Internal processing stateOrderState

Zeta's current order state.

Hold reasonstring

Reason the order is blocked or requires review.

Versioninteger

Optimistic concurrency version for the order.

OrderLine collectioncollection

Line items that specify the exact marketplace item, model, and quantity required by the order.

An order must pass source freshness, payment, support, recipient, mapping, and line-stability checks before reservation or delivery approval.

OrderLine

An OrderLine describes the quantity of one exact marketplace item and model required by a CustomerOrder.

Order IDstring

Order containing the line.

Item IDstring

Marketplace item identifier used for exact mapping.

Model IDstring

Marketplace model identifier used for exact mapping.

Quantityinteger

Positive number of units required for the line.

Allocation

An Allocation assigns a specific StockUnit to an OrderLine. Reservation creates allocations only after it has resolved every line and confirmed sufficient inventory for the entire order.

Orderrelationship

Order receiving the assigned stock unit.

Linerelationship

Order line that requires the assigned unit.

Unitrelationship

Stock unit assigned to the line.

Mappingrelationship

Exact listing mapping used to resolve the line.

Mapping version usedinteger

Mapping version captured when the allocation was created.

Ordinalinteger

Position of the allocation within its order line.

Active flagboolean

Indicates whether the allocation currently participates in the order's assignment.

Active allocations and line ordinals are protected by unique filtered indexes. This prevents one stock unit from being actively assigned more than once and prevents duplicate allocation positions within a line.

DeliveryAttempt

A DeliveryAttempt is the durable marker for a simulated delivery effect. Zeta commits the marker before invoking the synthetic delivery provider so restart recovery can distinguish an effect that may have started from one that never began.

Orderrelationship

Order associated with the delivery attempt.

Delivery IDstring

Identifier for the synthetic delivery operation.

Recipientstring

Synthetic recipient targeted by the attempt.

Allocation fingerprintstring

Fingerprint of the assigned allocation set used to bind the attempt to a specific reservation.

Start timestamptimestamp

Time at which the attempt marker was created.

End timestamptimestamp

Time at which the attempt reached a recorded end state.

ResultOutcome

Synthetic provider result, when committed.

Reveal flagboolean

Indicates whether the assigned codes were revealed during the attempt or its handling.

Only one unfinished delivery attempt may exist for an order. Interrupted attempts are treated conservatively and move the order toward REVIEW_REQUIRED rather than triggering an automatic resend.

DeliveryEvidence

A DeliveryEvidence record links an assigned unit to evidence that supports delivery or seller attestation.

Orderrelationship

Order for which the evidence applies.

Unitrelationship

Assigned stock unit covered by the evidence.

Attemptrelationship

Delivery attempt associated with the evidence.

Evidence kindEvidenceKind

Source classification of the evidence.

Referencestring

Synthetic reference supplied by the channel or seller attestation.

Actorstring

Actor associated with the evidence record.

Timestamptimestamp

Time at which the evidence was recorded.

Each order and unit pair has unique evidence. Seller attestation must cover assigned units and uses a DEMO- reference.

AuditEvent

An AuditEvent is an append-only record of a business action or state-changing operation.

Business IDstring

Business scope of the audited action.

Entity IDstring

Identifier of the entity affected by the action.

Actionstring

Action name recorded in the audit history.

Factsstructured data

Redacted or structured facts associated with the action.

Actorstring

Actor that initiated or performed the action.

Correlation IDstring

Identifier used to correlate related operations.

Timestamptimestamp

Time at which the action was recorded.

Database triggers protect audit history from unsafe updates and deletes.

CommandRecord

A CommandRecord provides durable idempotency for mutating commands.

Command keystring

Client-supplied key identifying the command invocation.

Payload fingerprintstring

Fingerprint of the command payload used to detect conflicting reuse of a key.

Serialized command resultstring

Serialized result returned when the command first committed.

Replaying a command with the same key and payload returns the stored result. Reusing the key with a different payload produces an idempotency conflict.

ReservationBatch

A ReservationBatch represents a durable explicit batch reservation operation.

Batch IDstring

Identifier for the reservation batch.

Creation timetimestamp

Time at which the batch was created.

BatchTarget collectioncollection

Per-order targets that store expected versions and individual results.

A batch freezes the selected order IDs and expected versions. It reserves each target independently, stores each result, survives restart, and does not perform approval or delivery.

BatchTarget

A BatchTarget stores the per-order state of a ReservationBatch.

Batchrelationship

Reservation batch containing the target.

Orderrelationship

Order selected for reservation processing.

Expected versioninteger

Order version expected when the target is processed.

Result statestring

Result recorded for this target, including success or a processing failure.

The batch target prevents a restarted batch from repeating targets that have already committed and allows each order to report an independent result.

Entity relationships

The core fulfillment relationship flows from a product listing to an order, then from the order to encrypted inventory and delivery evidence.

A CustomerOrder contains one or more OrderLine records. Each line resolves through an exact ListingMapping, and reservation creates Allocation records that pair the line with individual StockUnit records. A DeliveryAttempt records the possible external effect, while DeliveryEvidence records the unit-level support required for fulfillment.

Was this page helpful?