--- id: CAP-COM-FUL-004 title: Carry authorized work to its delivering application feature: FEAT-COM-FUL-01 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-REG-003 - CAP-COM-REG-016 - CAP-COM-REG-017 - CAP-COM-REG-048 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: [] purpose: Delivery work reaches the application responsible for fulfilling the sale. outcomes: - Applications fulfill their own sold outcomes without staff copying the sale. - Failed or unanswered delivery remains available for investigation. concepts: - CON-COM-FUL-001 actors: - ACT-COM-011 - ACT-COM-013 surfaces: - job - api preconditions: [] postconditions: [] permissions: - key: commerce.obligations.callback where_checked: api scope: global rules: - id: BR-CAP-COM-FUL-004-01 proved_by: [ATS-COM-FUL-004-01, TST-COM-FUL-044, TST-COM-FUL-055] statement: >- The dispatcher runs every minute and is nudged when work is queued, publishes workspace, obligation and authorization pointers, and removes only entries accepted by the queue. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-dispatcher.integration.spec.js#claims the three rows of both tenants, publishes a pointer for each, and reports the refused one origin: none - id: BR-CAP-COM-FUL-004-02 proved_by: [ATS-COM-FUL-004-01, TST-COM-FUL-044, TST-COM-FUL-055] statement: >- A failed or rejected publication leaves the dispatch entries available for a later run. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-dispatcher.integration.spec.js#leaves every row for the next run origin: none - id: BR-CAP-COM-FUL-004-03 proved_by: [ATS-COM-FUL-002-14, ATS-COM-FUL-004-02, ATS-COM-FUL-004-09, TST-COM-FUL-022, TST-COM-FUL-040, TST-COM-FUL-045] statement: >- The worker invokes the owning application with the operation envelope only for the current authorization, acknowledges obsolete or repeated pointers and records the stale attempt without changing delivery state. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js#acknowledges a redelivery of the same item as stale, writing one stale attempt and nothing else (A17) origin: none - id: BR-CAP-COM-FUL-004-04 proved_by: [ATS-COM-FUL-002-13, ATS-COM-FUL-003-06, ATS-COM-FUL-004-03, ATS-COM-FUL-004-08, ATS-COM-FUL-004-11, ATS-COM-FUL-004-12, ATS-COM-FUL-006-06, ATS-COM-FUL-008-08, ATS-COM-FUL-014-06, ATS-COM-FUL-018-08, TST-COM-FUL-018, TST-COM-FUL-023, TST-COM-FUL-024, TST-COM-FUL-040, TST-COM-FUL-078] statement: >- A completed response stores the delivered record; a partial response retains progress and completed units until the remainder arrives, rejecting completion beyond the owed quantity. kind: calculation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/persistence/obligation-register.integration.spec.js#records partial completion as in progress with the units, then completes when the rest arrive origin: >- D-P4-12 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-12 - id: BR-CAP-COM-FUL-004-05 proved_by: [ATS-COM-FUL-004-04, TST-COM-FUL-045] statement: >- Permanent refusal fails delivery and raises an exception, while retryable refusal or an unreachable application leaves delivery in flight for another attempt. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js#fails the obligation with the participant’s code, raises obligation_failed, and acknowledges the item origin: none - id: BR-CAP-COM-FUL-004-06 proved_by: [ATS-COM-FUL-004-04, TST-COM-FUL-045] statement: >- The fifth queue delivery fails the obligation for exhausted attempts and raises its exception before the message is dead-lettered. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js#fails it attempts_exhausted on the fifth receive, raises the exception, and still reports the item failed so the queue dead-letters it origin: >- D-P4-07 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-07 - id: BR-CAP-COM-FUL-004-07 proved_by: [ATS-COM-FUL-004-05, ATS-COM-FUL-004-10, ATS-COM-FUL-005-10, TST-COM-FUL-021, TST-COM-FUL-022, TST-COM-FUL-045] statement: >- An application can report delivery in progress and later complete, fail or report readiness through callbacks using its current authorization; repetition returns the stored result and obsolete authorization is rejected. kind: lifecycle enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#refuses a callback under an authorization that is not the current one, 409 authorization_not_current origin: >- D-P4-09 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-09 - id: BR-CAP-COM-FUL-004-08 proved_by: [ATS-COM-FUL-004-05, TST-COM-FUL-022, TST-COM-FUL-045] statement: >- Callback access is restricted to application service identities, rejects console and portal callers, and validates the request contract. kind: permission enforced_at: - api must_prove: true provenance: observed source: 'services-commerce:modules/fulfillment/aws/api/fulfillment.routes.ts' origin: none - id: BR-CAP-COM-FUL-004-09 proved_by: [ATS-COM-FUL-004-06, TST-COM-FUL-040, TST-COM-FUL-047] statement: >- An expired acknowledgement deadline causes one redispatch with an extended deadline, followed by acknowledgement-lost failure and an exception at the next expiry; the default deadline is one hour. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/register-sweeper.integration.spec.js#fails it ack_lost on the next deadline, with the exception raised and the history line written origin: >- D-P4-08 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-08 - id: BR-CAP-COM-FUL-004-10 proved_by: [ATS-COM-FUL-002-15, ATS-COM-FUL-004-07, ATS-COM-FUL-004-13, ATS-COM-FUL-020-11, TST-COM-FUL-024, TST-COM-FUL-025, TST-COM-FUL-041] statement: >- Database lifecycle guards reject invalid transitions, permit completed obligations only to be superseded, retain cancellation and resolution as terminal states, and require authorization for delivery in flight. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/db/register-tables.table.integration.spec.js#refuses pending to authorized, authorized to pending, failed to completed and completed to anything but superseded (RHC02) origin: none - id: BR-CAP-COM-FUL-004-11 proved_by: [ATS-COM-FUL-004-07, TST-COM-FUL-024, TST-COM-FUL-025, TST-COM-FUL-041] statement: >- A sold line can have only one obligation for each operation and unit, preventing duplicate obligations on retried placement. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/db/obligations.table.integration.spec.js#refuses a second obligation for the same subject, operation and unit, by obligations_subject_uq origin: none - id: BR-CAP-COM-FUL-004-12 proved_by: [] statement: >- The application role can append delivery attempts but cannot alter or remove the attempt history. kind: invariant enforced_at: - database must_prove: false provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/db/register-tables.table.integration.spec.js#names a real authorization (…_authorization_fk), counts from one (…_attempt_check) and is never changed or removed by the application (42501) origin: none - id: BR-CAP-COM-FUL-004-13 proved_by: [] statement: >- The worker logs a warning and acknowledges terminate and allocation-release operations without delivering them while no document produces them. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts origin: none scenarios: - id: SC-CAP-COM-FUL-004-01 given: >- Three applications respectively complete, defer and refuse authorized work. when: Deliver the queued instructions. then: >- The register records completed, in-progress and failed outcomes and acknowledges each message. provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#completes the plain one, leaves the long one in progress and fails the failing one, acknowledging all three edge_cases: - id: SC-CAP-COM-FUL-004-02 given: An application repeatedly returns a retryable failure. when: Deliver the message for the fifth time. then: >- The obligation reaches exhausted-attempt failure and an exception is recorded. provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js#fails it attempts_exhausted on the fifth receive, raises the exception, and still reports the item failed so the queue dead-letters it constraints: [] depends_on: - CAP-COM-FUL-002 related: - CAP-COM-FUL-005 - CAP-COM-FUL-006 - CAP-COM-FUL-014 journeys: - JNY-COM-FUL-001 - JNY-COM-FUL-002 open_questions: [] evidence: - repository: services-commerce paths: - >- modules/fulfillment/tests/integration/services/register/obligation-dispatcher.integration.spec.js - >- modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js - >- modules/fulfillment/tests/integration/services/persistence/obligation-register.integration.spec.js - modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js - modules/fulfillment/aws/api/fulfillment.routes.ts - >- modules/fulfillment/tests/integration/services/register/register-sweeper.integration.spec.js - >- modules/fulfillment/tests/integration/db/register-tables.table.integration.spec.js - >- modules/fulfillment/tests/integration/db/obligations.table.integration.spec.js - modules/fulfillment/services/register/obligation-worker.ts controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-FUL-01-01, FAS-COM-FUL-01-02, FAS-COM-FUL-01-03, FAS-COM-FUL-01-04] suites: [TST-COM-FUL-018, TST-COM-FUL-021, TST-COM-FUL-022, TST-COM-FUL-023, TST-COM-FUL-024, TST-COM-FUL-025, TST-COM-FUL-040, TST-COM-FUL-041, TST-COM-FUL-044, TST-COM-FUL-045, TST-COM-FUL-047, TST-COM-FUL-055, TST-COM-FUL-078] --- # Carry authorized work to its delivering application ## Purpose Delivery work reaches the application responsible for fulfilling the sale. ## How It Works Commerce dispatches authorized work through a queue. The worker supplies the owning application with the instruction and authorization needed to act. Immediate answers update the register, while longer work returns through callbacks. Recorded attempts help staff distinguish application refusal from transport failure. Scheduled acknowledgement handling provides another route to recovery when an answer disappears. Work that exhausts its retries remains visible for staff intervention. The product should provide a usable dead-letter inspection and redrive process. ## Relationships - Authorize delivery from current order facts supplies or consumes related delivery records. - Understand and intervene in an order's delivery supplies or consumes related delivery records. - Handle financial reversals after delivery supplies or consumes related delivery records. - Record goods leaving with a carrier or collector supplies or consumes related delivery records.