---
title: Orders Design Examination
examined_at: '2026-10-23'
examiner: codex
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
branch: agent/commerce-orders-desi-exam-1
examination_status: complete
evidence:
  - >-
    rhythm-v2-docs:specs/CONVENTIONS.md (§6, §9); specs/templates;
    briefs/design/commerce-orders.brief.md; specs/commerce/orders planning
    corpus and FINDINGS.md
  - >-
    services-commerce:modules/{checkout,orders,participants,entitlements,purchasing}/**;
    aws/commerce.metadata.ts; db/migrations/20261018130023_entitlements.sql;
    docs/milestones/plans/COMM-M2-plan.md
  - 'macroservice-libraries:packages/commerce-contracts/**'
  - >-
    react-console: named screen component and route sources in the eight Screen
    Contracts
verified_metadata_changes:
  - artifact: DOM-COM-ORD-001
    field: invariants.4.source
    before: >-
      services-commerce:modules/checkout/tests/e2e/placement.e2e.spec.js#leaves
      the checkout placed, naming the order, its items frozen with what prepare
      attested, and its trail telling the story
    after: >-
      services-commerce:modules/checkout/tests/e2e/placement.e2e.spec.js#leaves
      the checkout placed, naming the order, its items frozen with what prepare
      attested, and its trail telling the story;
      services-commerce:modules/checkout/services/persistence/checkouts.ts:updateCheckout,
      appendCheckoutEvent
  - artifact: DOM-COM-ORD-005
    field: invariants.0.source
    before: >-
      services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#holds
      staff’s request for approval (participant_requires_approval) and refuses a
      second request on the line 409 line_already_cancelling (B38)
    after: >-
      services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#holds
      staff’s request for approval (participant_requires_approval) and refuses a
      second request on the line 409 line_already_cancelling (B38);
      services-commerce:modules/orders/db/cancellation-lines.table.ts:cancellation_lines_active_uidx;
      services-commerce:modules/orders/db/amendment-lines.table.ts:amendment_lines_active_uidx;
      services-commerce:modules/orders/db/return-lines.table.ts:return_lines_active_uidx
  - artifact: DOM-COM-ORD-005
    field: invariants.2.provenance
    before: test
    after: observed
  - artifact: DOM-COM-ORD-005
    field: invariants.2.source
    before: >-
      services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#refuses
      a placed order 409 order_not_cancellable, another member 403
      not_your_party, a reader 403 permission_missing, another tenant 404
    after: >-
      services-commerce:modules/orders/services/cancellations/cancellation-workflow.ts:requestCancellation;
      services-commerce:modules/orders/services/amendments/amendment-workflow.ts:requestAmendment;
      services-commerce:modules/orders/services/returns/return-workflow.ts:requestReturn;
      services-commerce:modules/orders/services/amendments/promotion-amendment.ts
  - artifact: DOM-COM-ORD-005
    field: invariants.7.source
    before: 'services-commerce:modules/orders/db/return-policies.table.ts'
    after: >-
      services-commerce:modules/orders/services/returns/return-workflow.ts;
      services-commerce:modules/orders/services/persistence/returns.ts:recordReturnEvaluation
  - artifact: DOM-COM-ORD-002
    field: invariants.1.source
    before: >-
      services-commerce:modules/checkout/tests/e2e/idempotency.e2e.spec.js#answers
      the stored status and body, marked Idempotent-Replayed, and runs the
      placement once: one order row
    after: >-
      services-commerce:modules/checkout/tests/e2e/idempotency.e2e.spec.js#answers
      the stored status and body, marked Idempotent-Replayed, and runs the
      placement once: one order row;
      services-commerce:modules/orders/db/orders.table.ts:orders_checkout_uq
  - artifact: DOM-COM-ORD-004
    field: invariants.3.source
    before: >-
      services-commerce:modules/entitlements/services/register/entitlement-sweeper.ts
    after: >-
      services-commerce:db/migrations/20261018130023_entitlements.sql:consume_entitlement
  - artifact: SVC-COM-ORD-checkout
    field: operations.5.permission
    before: commerce.checkouts.update (evaluates commerce.orders.create)
    after: commerce.checkouts.update
  - artifact: SVC-COM-ORD-checkout
    field: operations.9.permission
    before: commerce.checkouts.update (evaluates commerce.orders.create)
    after: commerce.checkouts.update
  - artifact: SVC-COM-ORD-checkout
    field: operations.11.permission
    before: commerce.checkouts.update (evaluates commerce.orders.create)
    after: commerce.checkouts.update
responsibility_pin_added:
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
---
# Orders Design Examination

## Examination and Authority

The examination opened the pinned route declarations, database definitions, persistence and service implementations, workflow entry points, registrations, console components and cited tests. All sixty-four design artifacts received an independent OpenAI verification and final-text pass. The Orders responsibility row and prose were reconciled with the contracts and objects; other modules' responsibility text was preserved.

Planning rules, journeys, questions and decisions were used as consistency constraints. The supplied planning files retain draft status and a mixture of confirmed and proposed intent, so examination does not grant approval. Existing findings retain the unresolved authority and integration disagreements.

## Coverage

| Area | Examined coverage | Limit |
|---|---|---|
| Design artifacts | 6 objects, 13 state models, 16 workflows, 5 service contracts, 8 screen contracts and 16 decisions | Every artifact rewritten; identifiers and product authority retained. |
| Operations | 78 unique declared business HTTP operation identifiers, 4 shared health routes, 1 registration function and 1 database consumption function; all 84 have contract rows | Registration and consumption are not HTTP route declarations. |
| Data | All 32 table definitions in the five source modules, plus the active-rights view, map to 6 objects | Objects group supporting records rather than introduce a concept for every table. |
| State | 13 lifecycle/projection models, 86 structured transition rows and 57 invariants | Transition rows and diagrams are descriptive evidence, not new transition guards. |
| Execution | 16 workflows and 94 hops; the one owned minute schedule and synchronous registration function are covered | No queue or Step Functions state machine is owned by these five modules; fulfilment execution and its workers remain delegated. |
| Screens | All 8 named components, their page or dialog entry routes, actions and permission gates | The amendment component exists while the live option source remains disabled. |
| Anchors | All 362 structured source and anchor occurrences checked for path and cited symbol or test-title existence | Example tests were read as evidence; their assertions were not rerun against deployed services. |
| Inference | Every service, workflow and screen declares an empty inference list; no model task call found in the scoped source | No inference artifact is required by the examined implementation. |

### Physical Record Ownership

| Object | Physical records |
|---|---|
| `DOM-COM-ORD-001` | `checkouts`, `checkout_items`, `checkout_events` |
| `DOM-COM-ORD-002` | `orders`, `order_lines`, `order_line_purchases`, `order_tenders`, `order_invoices`, `order_events`, `reservations` |
| `DOM-COM-ORD-003` | `participants`, `participant_product_types`, `participant_payload_schemas` |
| `DOM-COM-ORD-004` | `entitlements`, `entitlement_uses`, `entitlements_held_v` |
| `DOM-COM-ORD-005` | `cancellations`, `cancellation_lines`, `amendments`, `amendment_lines`, `returns`, `return_lines`, `return_authorizations`, `return_policies` |
| `DOM-COM-ORD-006` | `vendors`, `purchase_orders`, `purchase_order_lines`, `inventory_receipts`, `inventory_receipt_lines`, `inventory_cost_layers`, `cost_relief`, `inventory_postings`, `business_unit_settings` |

### Changes by Artifact

Every row below includes a final rewrite of its prose and descriptive fields. Verification corrections were committed before the affected final-text rewrites, and each artifact's rewrite has its own commit.

| Artifact | Examination and final-text focus |
|---|---|
| `SVC-COM-ORD-checkout` | Exact checkout permissions, placement, local trails and shared recovery schedule. |
| `SVC-COM-ORD-entitlements` | Purchased-right administration, consumption migration and validity. |
| `SVC-COM-ORD-orders` | Sale and after-sale routes, financial integrations and owned/delegated boundaries. |
| `SVC-COM-ORD-participants` | Registration-only service and strict bounded seller contracts. |
| `SVC-COM-ORD-purchasing` | Vendor, acquisition, receipt, cost and posting operations. |
| `ADR-COM-ORD-001` | Module grouping across four HTTP facets and one registration boundary. |
| `ADR-COM-ORD-002` | Accounting ownership of money and Commerce financial projection. |
| `ADR-COM-ORD-003` | Resource claims within placement commit. |
| `ADR-COM-ORD-004` | Recomputed price binding and comparison with any saved assessment. |
| `ADR-COM-ORD-005` | Domain commit before remote invoice work. |
| `ADR-COM-ORD-006` | Purchase policy snapshots with migrated-sale fallback. |
| `ADR-COM-ORD-007` | Shared adjustment execution rather than independent reversal paths. |
| `ADR-COM-ORD-008` | Sequential scheduled recovery and its failure boundary. |
| `ADR-COM-ORD-009` | Synchronous seller participant calls and transactional claims. |
| `ADR-COM-ORD-010` | No declared configurable fields on the order metadata object. |
| `ADR-COM-ORD-011` | No submission-stage publication or invented intake contract. |
| `ADR-COM-ORD-012` | Consumer-transaction benefit consumption. |
| `ADR-COM-ORD-013` | Local retained trails and numbered voids. |
| `ADR-COM-ORD-014` | Durable local intervention records with the current audit stand-in. |
| `ADR-COM-ORD-015` | Replacement semantics proposed for Commerce, without extending CRM approval. |
| `ADR-COM-ORD-016` | Shared purchasing operations across staff and portal callers. |
| `DOM-COM-ORD-001` | Cart versioning, policy selection, ownership and transaction limits; persistence evidence added. |
| `DOM-COM-ORD-002` | Sale identity, snapshot exceptions, uniqueness, Accounting projection and resource ownership; database uniqueness evidence added. |
| `DOM-COM-ORD-003` | Complete participant declarations, product-type ownership and bounded seller calls. |
| `DOM-COM-ORD-004` | Purchased rights, consumer transaction coupling, validity and root consumption migration location. |
| `DOM-COM-ORD-005` | Distinct cancellation, amendment and return eligibility; authorization update limits; all three occupancy indexes cited. |
| `DOM-COM-ORD-006` | Acquisition quantities, stock and cost coupling, valuation and external posting boundary. |
| `SCR-COM-ORD-001` | Sale search, filters, paging and navigation. |
| `SCR-COM-ORD-002` | Sale detail cards, separate approval operations and Accounting navigation. |
| `SCR-COM-ORD-003` | Cart composer requests, party replacement and collection choices. |
| `SCR-COM-ORD-004` | Card and offline collection with actual permission gates. |
| `SCR-COM-ORD-005` | Void confirmation and required explanation. |
| `SCR-COM-ORD-006` | Cancellation calculation, authority override and stale-proposal withdrawal. |
| `SCR-COM-ORD-007` | Return quantities, explanation and receiving authorization. |
| `SCR-COM-ORD-008` | Amendment component with live options deliberately unavailable. |
| `STATE-COM-ORD-001` | Actual cart transitions and attribution. |
| `STATE-COM-ORD-002` | Preparation outcomes and authoritative revalidation of stored problems. |
| `STATE-COM-ORD-003` | Reservation lifecycle, fencing and confirmation outcomes. |
| `STATE-COM-ORD-004` | Sale lifecycle separated from financial and delivery projections. |
| `STATE-COM-ORD-005` | Invoice processing states and deferred recovery. |
| `STATE-COM-ORD-006` | Collection outcomes, replay and uncertain-payment resolution. |
| `STATE-COM-ORD-007` | Installment arrangement states and current Accounting ownership. |
| `STATE-COM-ORD-008` | Purchased-right lifecycle and direct validity enforcement. |
| `STATE-COM-ORD-009` | Cancellation authority, execution and terminal occupancy release. |
| `STATE-COM-ORD-010` | Amendment lifecycle, change-sale collection and missing deferred execution. |
| `STATE-COM-ORD-011` | Returns on accepted or closed sales and receiving progression. |
| `STATE-COM-ORD-012` | Authorization quantities and states without an invented categorical transition guard. |
| `STATE-COM-ORD-013` | Purchase-order issue, receipt, cancellation and closure. |
| `WF-COM-ORD-001` | Cart creation, editing, assessment and expiry. |
| `WF-COM-ORD-002` | Authoritative placement with optional saved preview, transactional claims and post-commit work. |
| `WF-COM-ORD-003` | Keyed invoice creation, blocked configuration and recovery. |
| `WF-COM-ORD-004` | Collection sequencing, uncertainty and eventual recovery. |
| `WF-COM-ORD-005` | Void transaction, resource release and asynchronous financial reversal. |
| `WF-COM-ORD-006` | Shared sequential sweep, single concurrency setting and starvation limits. |
| `WF-COM-ORD-007` | Installment quotes, arrangement creation and delegated billing. |
| `WF-COM-ORD-008` | Projection derivation with last-writer updates and no freshness fence. |
| `WF-COM-ORD-009` | Delivery-triggered grants, transactional use and restoration. |
| `WF-COM-ORD-010` | Cancellation advice, approval, delivery reversal and settlement. |
| `WF-COM-ORD-011` | Amendment change sales, post-acceptance failure and missing deferred executor. |
| `WF-COM-ORD-012` | Later promotion eligibility and adjustment processing. |
| `WF-COM-ORD-013` | Return eligibility, authorization, receiving and the skipped deadline check. |
| `WF-COM-ORD-014` | Synchronous registration, full declarations and caller-visible refusal. |
| `WF-COM-ORD-015` | Receipt, acquisition cost and posting facts; external intake availability is not asserted. |
| `WF-COM-ORD-016` | Cost relief, returns, transfers, correction and valuation. |

## Evidence Corrections

Checkout removal, abandonment and hold extension no longer claim an undeclared create permission. Participant registration is identified as a function rather than a fifth HTTP API. Entitlement consumption now cites the root database migration, and broad cart-version, placement-uniqueness and change-occupancy assertions also cite their persistence or database enforcement.

After-sale eligibility now distinguishes the accepted-or-closed return path and placed-or-accepted promotion path from ordinary accepted-sale changes. Return authorization no longer claims a forbidden reopening guard that its persistence function does not enforce. Concurrent monetary refresh is described as a last-writer update without a freshness check.

Stored assessment problems no longer imply irrevocable placement refusal; fresh authoritative preparation controls that outcome. Placement compares against a saved preview when one exists and can bind current calculations when none exists. The policy snapshot description now distinguishes newly placed purchases from migrated records that use the fallback policy.

The responsibility record now pins the shared-contract repository and distinguishes HTTP exposure from registration. Metadata approval, intent, provenance and identifiers remain unchanged except for the documented after-sale invariant evidence correction and additional enforcement sources. The module registry records examination status without approving the design.

## Findings and Open Disagreements

Four findings were allocated during examination: stale projection overwrites, unguarded receiving authorization transitions, inconsistent after-sale eligibility and the limited proof supplied by example-based invariant tests. They remain open; corrections describe observed code rather than approve its behavior.

Existing findings remain open concerning shared recovery starvation, the skipped return deadline check, deferred amendment execution, post-acceptance amendment recovery, unconfigured financial adapters, incomplete live amendment choices, the audit stand-in, submission-stage purchase contracts and installment ownership. The examination did not alter planning rules to resolve them. Product decisions already recorded by the planning layer remain cited as origins rather than reopened as new approvals.

No source-service or console implementation was changed. This was a static examination with repository conformance and checker tests, so it does not establish deployed recovery, external provider availability or end-to-end operational readiness.

## Validation

The required clean dependency installation and corpus check completed successfully with zero errors. All four repository test cases passed. No implementation integration suite was run because the change concerns the specification corpus.

## Verdict for Andrew

The examined design is a faithful static account of the pinned module after correcting its overclaims and retaining explicit findings for incomplete behavior. Its weakest area is recovery across financial, receiving and seller boundaries, where configuration, skipped work and missing executors limit the guarantees. Before implementation preparation, decide the unresolved recovery responsibilities, return closure behavior, installment ownership and submission-stage purchase boundary, and confirm the planning authority.

## Continuation (pass 2)

The previous testing report is the checkpoint for this continuation; no separate first-pass back-fill report exists. Its eighteen capability specifications already carry all ten coverage categories and scenario categories, its seven feature suites exist, and its executable register contains 163 files. All 188 testing artifacts were examined against their structured references and pinned sources; the first pass already identifies itself as Codex, so its verified OpenAI wording is retained where no correction is needed.

This pass rewrites all seven feature-suite bodies and corrects four scenario descriptions. The replay-safe benefit scenario now follows the single-copy fixture rather than combining it with the three-copy fixture. The competing draw requests two uses followed by a waiting one-use request. Closing a purchase claims preservation of received quantity rather than an unasserted receipt-fact inspection, and the two-receipt scenario inspects cost layers rather than an unrelated valuation fixture.

Eight feature bindings become active, with reciprocal executable entries and case mappings in the billing, entitlement API, entitlement persistence and purchasing-flow registers. The checkout and participant-outage registers lose their deferred feature candidates. Three proposed candidates remain unbound with a new finding: cart editing and preview use separate fixtures, the outage test does not count order rows, and the grant-revocation test calls a helper without executing the cancellation workflow. The current checker accepts feature scenario references and the requested back-fill report filename; the previous tooling block is resolved without changing tooling.

The identifier registry and findings record receive final OpenAI text for the continuation additions. No capability rule, concept, journey, non-test design artifact, generated traceability index or reader file changes. Feature acceptance fields already name the seven suites and need no change. Existing identifiers, source pins and approval values remain intact.

## Testing Continuation Limits

This continuation examines the testing projection of the design. It preserves the earlier design examination and makes no additional operation, table, screen or workflow completeness claim. The missing architecture record, unresolved combined test chains and executable-register retrofit remain findings.

## Continuation Verdict for Andrew

Andrew can review the completed testing continuation with every deferred item completed or recorded as a finding. The pinned testing layer describes its local evidence faithfully after correcting the fixture and binding overclaims, but combined recovery and after-sale chains remain its weakest proof. Before implementation preparation, decide the open ownership and recovery questions and schedule the executable-register retrofit and missing feature-chain assertions; this examination grants no product approval or delivery qualification.

## Continuation Validation

The clean dependency installation and corpus check pass with zero errors, and all eighteen repository tests pass. The testing continuation makes no deployed execution claim.