--- id: DOM-COM-FUL-001 title: Obligation realises: CON-COM-FUL-001 product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-FUL-fulfillment readable_by: - SVC-COM-FUL-shipping - SVC-COM-FUL-inventory - SVC-COM-FUL-operations - SVC-COM-FUL-data-operations lifecycle: STATE-COM-FUL-001 custom_fields: none identity: >- A workspace-local record is unique by subject, operation and unit index. Current authorizations have workspace-unique identities used by the delivering application for repeated work. attributes: - name: order and order line kind: reference required: true computed: false notes: References the Orders-owned sale and line that owe this work. - name: unit index kind: number required: true computed: false notes: Uses zero for line-level work or the zero-based index of a physical unit. - name: subject kind: reference required: true computed: false notes: >- Identifies the order, cancellation, amendment or enforcement subject owing the operation. - name: operation kind: enum required: true computed: false notes: >- Selects the declared fulfil, enforce, cancel, modify, replace, terminate or allocation-release operation. - name: kind and delivering application kind: text required: true computed: false notes: >- Identifies the declared delivery kind and the application registered to perform it. - name: quantity and quantity completed kind: number required: true computed: false notes: >- Retains owed and completed quantities, with partial delivery still in progress. - name: gate kind: collection required: true computed: false notes: >- Retains selected policy, version and selection source together with added preparation safeguards. - name: gate verdict kind: computed required: false computed: true notes: >- Retains the last closed, blocked or open result, evaluation time, facts and staff-attention reason. - name: 'approval, override and hold' kind: collection required: false computed: false notes: >- Retains approvals, overrides and delivery holds with their actor, time and reason. - name: application readiness kind: date required: false computed: false notes: Records when the application reports its prerequisite satisfied. - name: same-order prerequisite line kind: reference required: false computed: false notes: >- Names the membership line whose successful delivery releases same-order member-priced work. - name: state kind: enum required: true computed: false notes: >- Retains the declared waiting, in-flight, terminal or superseded delivery state. - name: current authorization kind: reference required: false computed: false notes: >- Names the active authorization, sequence and acknowledgement timing required during delivery. - name: authorizations kind: collection required: false computed: false notes: >- Retains issued authorization history, replacement linkage, dispatch counts and outcomes. - name: attempts kind: collection required: false computed: false notes: >- Retains ordered immutable delivery attempts, callback outcomes and failure diagnosis. - name: outcome kind: collection required: false computed: false notes: >- Retains completion records or staff evidence, plus failure classification when work stops. - name: links kind: reference required: false computed: false notes: Connects supersession and post-sale subjects and identifies migrated work. - name: enforcements kind: collection required: false computed: false notes: >- Retains reversal cause, response, instruction, restoration and staff-review closure. - name: interventions kind: collection required: false computed: false notes: >- Retains immutable staff actions, reasons, subjects and accepted or refused outcomes. - name: financial event receipts kind: collection required: false computed: false notes: >- Deduplicates processed Accounting events and retains resolved line identities and results. relationships: - to: DOM-COM-FUL-002 cardinality: Many obligations freeze one policy version each. ownership: The obligation owns its frozen copy; the policy owns its configuration. cross_service: false - to: DOM-COM-FUL-003 cardinality: 'One obligation has zero to many exceptions, at most one open per kind.' ownership: The exception owns the link. cross_service: false - to: DOM-COM-FUL-004 cardinality: >- A shipment line can match multiple unit obligations; the handoff implementation does not prove that every departing unit has a match. ownership: The shipment owns the link; the obligation records the outcome. cross_service: true - to: DOM-COM-FUL-005 cardinality: One unit-grain obligation is stamped on one stock allocation unit. ownership: The allocation owns the link. cross_service: true invariants: - id: INV-DOM-COM-FUL-001-01 statement: >- The database permits one obligation for a subject, operation and unit within a workspace. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/db/obligations.table.ts:obligations_subject_uq - id: INV-DOM-COM-FUL-001-02 statement: >- The database and persistence service restrict obligation changes to the declared lifecycle. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:OBLIGATION_TRANSITIONS; db/migrations/20261018004016_obligation_register.sql:refuse_obligation_regression - id: INV-DOM-COM-FUL-001-03 statement: Delivery in flight requires a current authorization reference. enforced_at: - database provenance: observed source: >- services-commerce:modules/fulfillment/db/obligations.table.ts:obligations_authorization_state_check - id: INV-DOM-COM-FUL-001-04 statement: Completed quantity cannot exceed the quantity owed. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/db/obligations.table.ts:obligations_quantity_check - id: INV-DOM-COM-FUL-001-05 statement: >- Gate opening commits authorization and dispatch together and conditionally permits one winner. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:openGate - id: INV-DOM-COM-FUL-001-06 statement: >- Only an in-flight obligation’s current authorization can apply an application outcome; other answers become stale attempts. enforced_at: - service provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:recordObligationOutcome - id: INV-DOM-COM-FUL-001-07 statement: >- Application writers can append attempts and interventions but cannot update, delete or truncate them. enforced_at: - database provenance: observed source: >- services-commerce:modules/fulfillment/db/obligation-attempts.table.ts; modules/fulfillment/db/intervention-logs.table.ts (UPDATE, DELETE and TRUNCATE revoked) - id: INV-DOM-COM-FUL-001-08 statement: >- A staff change records its reason and intervention within the same transaction as the change. enforced_at: - api - service provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-interventions.ts - id: INV-DOM-COM-FUL-001-09 statement: >- Concurrent approval accepts one approval and refuses the others without recording another act. enforced_at: - service provenance: test source: >- services-commerce:docs/migrations/obligation-register/README.md#D-P4-16 (obligation-register.e2e five simultaneous approvals) - id: INV-DOM-COM-FUL-001-10 statement: An obligation and financial event identify at most one enforcement. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/db/enforcements.table.ts:enforcements_cause_uq - id: INV-DOM-COM-FUL-001-11 statement: >- Successful financial processing stores the event receipt last; an existing receipt suppresses repeat processing. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/fulfillment/services/facts/financial-facts-handler.ts - id: INV-DOM-COM-FUL-001-12 statement: >- Composite foreign keys retain workspace-local order, line and prerequisite references. enforced_at: - database provenance: observed source: >- services-commerce:modules/fulfillment/db/obligations.table.ts (composite RESTRICT keys) physical: - obligations - obligation_authorizations - obligation_attempts - obligation_dispatches - enforcements - intervention_logs - financial_fact_receipts evidence: - >- services-commerce at c8b66a98: modules/fulfillment/db/*.table.ts; services/persistence/obligations.ts, obligation-authorizations.ts, obligation-attempts.ts, enforcements.ts, intervention-logs.ts; services/register/*.ts; services/facts/financial-facts-handler.ts; export/fulfillment.dataset.ts; docs/migrations/obligation-register/README.md. --- # Obligation ## What It Models Delivery work belongs to a sale, but the application delivering it owns the resulting membership, access or goods. An obligation coordinates that work by retaining the conditions for release, the application responsible, its answers and staff interventions. Physical delivery uses one obligation for each unit. ## Identity and Attributes Identity combines the workspace with a subject, an operation and a unit index. The selected delivery policy is copied onto the obligation with its version and selection source. Authorization history separates a new staff authorization from a retry of an existing instruction; attempt history records both current and stale answers. ## Relationships Policies supply the frozen conditions. Exceptions identify problems without owning the obligation. Allocation units and shipment lines connect physical delivery to the register, while reversal enforcements retain their own instructions beside the original delivery. ## Invariants The structured invariants distinguish database constraints from service checks. Gate opening retains authorization and dispatch together. Outcome application checks the current authorization, while later history and enforcement updates can fail separately. ## How It Is Stored and Shared Fulfillment owns the register and its companion records. Shipping completes physical-unit obligations through the register; Inventory and Operations read the records for their own checks and actions. Migrated final outcomes enter through data operations. Applications receive instructions and use callbacks rather than reading these tables. ## Open Design Questions Product must settle warehouse acknowledgement timing and the ownership and permitted writers of the shared intervention ledger.