--- id: DOM-COM-FUL-003 title: Operational Exception realises: CON-COM-FUL-003 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-operations lifecycle: STATE-COM-FUL-004 custom_fields: none identity: >- A workspace-local exception has one standing record per kind and subject. Financial adjustments instead use the originating document kind and identity for deduplication. attributes: - name: kind kind: enum required: true computed: false notes: >- Classifies the declared financial, delivery, dependency and drift problem, including kinds without current producers. - name: subject kind: reference required: true computed: false notes: >- Names the affected sale, delivery, money, shipment, return or promotion record without owning it. - name: order kind: reference required: false computed: false notes: Connects the finding to an order when one applies. - name: detection kind: collection required: true computed: false notes: 'Retains the detector, time and count of repeated diagnosis.' - name: details kind: collection required: false computed: false notes: 'Retains the current diagnostic payload, refreshed on recurrence.' - name: state kind: enum required: true computed: false notes: 'Distinguishes open attention, acknowledged awareness and resolved closure.' - name: acknowledgement and resolution kind: collection required: false computed: false notes: >- Retains staff identity, time and closure result for acknowledgement and resolution. - name: financial adjustment kind: collection required: false computed: false notes: >- Retains the originating post-sale document, financial step plan, stable keys, Accounting results and failures. - name: summary counts kind: computed required: false computed: true notes: Provides grouped kind and state totals for Operations. relationships: - to: DOM-COM-FUL-001 cardinality: >- An obligation, enforcement or adjustment has zero to many exceptions over time. ownership: The exception owns the link. cross_service: false invariants: - id: INV-DOM-COM-FUL-003-01 statement: >- A standing exception is unique by kind and subject; repeated detection refreshes that record. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/db/operational-exceptions.table.ts:operational_exceptions_open_uidx - id: INV-DOM-COM-FUL-003-02 statement: An informational event finding remains deduplicated after resolution. enforced_at: - service provenance: documented source: 'services-commerce:docs/migrations/operations/README.md#D-P5-08' - id: INV-DOM-COM-FUL-003-03 statement: >- Staff acknowledgement needs a reason; resolution also needs a closure result, and resolved exceptions refuse both. enforced_at: - api - service provenance: observed source: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts - id: INV-DOM-COM-FUL-003-04 statement: >- Cross-workspace detection switches into the subject’s workspace before storing a finding. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/operations/services/persistence/reconciler-candidates.ts - id: INV-DOM-COM-FUL-003-05 statement: >- A document identifies one financial adjustment, returned again on a repeated request. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:requestFinancialAdjustment - id: INV-DOM-COM-FUL-003-06 statement: >- Adjustment planning fixes keyed steps at request time; resuming execution keeps that plan. enforced_at: - service provenance: observed source: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts:planAdjustmentSteps - id: INV-DOM-COM-FUL-003-07 statement: >- The persistence service permits only declared adjustment transitions and retains completion and resolution as terminal. enforced_at: - service provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:ADJUSTMENT_TRANSITIONS - id: INV-DOM-COM-FUL-003-08 statement: >- Execution records submission before sending a command and retains its Accounting result before advancing. enforced_at: - service provenance: documented source: 'services-commerce:docs/migrations/operations/README.md#D-P5-06' physical: - operational_exceptions - financial_adjustments evidence: - >- services-commerce at c8b66a98: modules/fulfillment/db/operational-exceptions.table.ts, financial-adjustments.table.ts; services/persistence/operational-exceptions.ts, financial-adjustments.ts; services/adjustments/adjustment-worker.ts; modules/operations/services/interventions/operations-interventions.ts, services/reconciler/reconciler.ts; docs/migrations/operations/README.md. --- # Operational Exception ## What It Models An operational exception gives staff a retained diagnosis of an order problem. Delivery workers, scheduled checks and financial execution raise these records so staff can acknowledge awareness and document closure. Financial adjustments keep the separate sequence of Accounting work that often explains a finding. ## Identity and Attributes A standing exception is unique for its kind and subject within a workspace. Recurrences increase its count and refresh diagnostic details. A financial adjustment belongs to one originating document and retains each planned step, its key, result and Accounting reference. ## Relationships An exception points to the affected record and does not own it. Operations serves exceptions, adjustments and enforcements through staff routes; Fulfillment declares their storage. Warehouse findings use a separate inventory list. ## Invariants Lifecycle checks and unique keys govern closure and repeated requests. Financial steps are recorded before sending and use stable keys on recovery. These guarantees do not make every downstream history or enforcement update atomic with delivery. ## How It Is Stored and Shared Fulfillment supplies persistence, Operations supplies investigation and intervention, and Orders requests money work when its document is ready. Accounting executes the financial commands and owns their results. ## Open Design Questions The shared records need an explicit writer contract. Product must also decide how warehouse findings join the attention workflow.