--- id: SVC-COM-FUL-fulfillment title: Fulfillment Service Module product_area: commerce module: fulfillment repository: services-commerce source_module: modules/fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-FUL-001 - DOM-COM-FUL-002 - DOM-COM-FUL-003 does_not_own: - >- Orders owns sale records, placement, billing and post-sale documents, and hosts register recovery in its checkout sweep. - >- Accounting owns financial documents, transactions, receivable events and the position view. - >- Platform owns shared authorization, service identities and external audit storage. - >- Operations exposes staff reads and interventions over the shared findings and money-work records. operations: - operation_id: getFulfillmentHealth intent: >- Return API reachability and deployment identity without reading business records. access: public permission: none realises: [] published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: listObligations intent: >- Return the permitted obligations records with the route’s supported filters. access: console permission: commerce.obligations.read realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getObligation intent: Read the requested obligation record within the current workspace. access: console permission: commerce.obligations.read realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: completeObligation intent: Record completion of obligation under its state and request checks. access: system permission: commerce.obligations.callback realises: - CAP-COM-FUL-004 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: failObligation intent: Record a failed obligation outcome under the current authorization. access: system permission: commerce.obligations.callback realises: - CAP-COM-FUL-004 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: reportObligationPrerequisite intent: Record application readiness for the requested obligation. access: system permission: commerce.obligations.callback realises: - CAP-COM-FUL-004 - CAP-COM-FUL-002 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: approveObligation intent: Retain staff approval and evaluate the waiting obligation. access: console permission: commerce.obligations.approve realises: - CAP-COM-FUL-005 - CAP-COM-FUL-002 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: overrideObligationGate intent: Open a waiting obligation through a separately authorized staff override. access: console permission: commerce.obligations.override realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: reauthorizeObligation intent: >- Issue a fresh authorization for a failed obligation and retain the staff reason. access: console permission: commerce.obligations.reauthorize realises: - CAP-COM-FUL-005 - CAP-COM-FUL-004 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: resolveObligation intent: Retain staff closure of obligation with the required result. access: console permission: commerce.obligations.resolve realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: holdObligation intent: Block waiting delivery under a retained staff hold. access: console permission: commerce.obligations.hold realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: releaseObligationHold intent: Remove a staff delivery hold and immediately evaluate the gate. access: console permission: commerce.obligations.hold realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: completeObligationManually intent: >- Attest in-flight delivery with a reason and evidence, closing its authorization. access: console permission: commerce.obligations.complete-manually realises: - CAP-COM-FUL-005 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: createFulfillmentPolicy intent: >- Create fulfillment policy using the supplied configuration or eligible order work. access: console permission: commerce.fulfillment-policies.create realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listFulfillmentPolicies intent: >- Return the permitted fulfillment policies records with the route’s supported filters. access: console permission: commerce.fulfillment-policies.read realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getEffectiveFulfillmentPolicy intent: >- Read the requested effective fulfillment policy record within the current workspace. access: console permission: commerce.fulfillment-policies.read realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getFulfillmentPolicy intent: Read the requested fulfillment policy record within the current workspace. access: console permission: commerce.fulfillment-policies.read realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: updateFulfillmentPolicy intent: >- Replace fulfillment policy using its current version and allowed writable properties. access: console permission: commerce.fulfillment-policies.update realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: deleteFulfillmentPolicy intent: >- Remove fulfillment policy only when locking and reference constraints permit. access: console permission: commerce.fulfillment-policies.delete realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: applyFulfillmentPolicy intent: Inspect pending obligations in scope and replace differing frozen gates. access: console permission: commerce.fulfillment-policies.apply realises: - CAP-COM-FUL-001 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. events: - name: Accounting receivable change events direction: consumed when: Accounting invokes Commerce with a receivable-event batch. payload_summary: >- Event identity, type and financial subject references select affected lines; eligibility reads current positions. - name: order history events of the register direction: produced when: >- Financial processing, gate changes, delivery outcomes, staff interventions, enforcement and adjustment progression. payload_summary: >- Internal append-only order history records the actor and relevant delivery or financial work. - name: commerce intervention audit event direction: produced when: A local staff intervention commits. payload_summary: >- The external audit attempt identifies actor, action, subject and local ledger row; the selected provider currently logs it. - name: 'delivery envelopes (fulfil, enforce, cancel, modify, replace)' direction: produced when: The queue worker finds a current supported authorization. payload_summary: >- The shared participant envelope carries authorization, delivery subject, purchase facts, claims and operation-specific context. jobs: - name: commerce_obligation_dispatcher schedule: 'Every minute and on post-commit nudges, with reserved concurrency one.' does: >- Publishes retained authorization pointers and removes accepted dispatch entries. - name: commerce_obligation_worker schedule: >- Consumes the obligations queue with 90-second visibility, five receives and 14-day dead-letter retention. does: >- Loads current authorized work, invokes its application and conditionally retains the answer. - name: commerce_financial_facts schedule: Invoked by Accounting’s receivable change-event dispatcher. does: >- Resumes adjustments, evaluates current gates and handles reversals before retaining success receipts. - name: register sweep (a pass of Orders' commerce_checkout_sweeper) schedule: Runs within the Orders minute checkout sweep. does: >- Revisits bounded inactive pending obligations and overdue acknowledgement records. integrations: - system: Accounting position view direction: inbound contract: >- Financial eligibility reads Accounting’s line-position view through the facts port. Deployed functions select position_view; omitted selection uses the test fixture. Approved-terms facts are not supplied. - system: Accounting commands direction: outbound contract: >- Adjustment steps issue keyed credit-memo, fee-invoice, credit, application and refund commands through Accounting service functions. Accounting is the default command provider; tests can select the fixture. Missing service-function configuration refuses commands. - system: Delivering applications direction: outbound contract: >- Delivery instructions use the shared participant registry for fulfillment, enforcement, cancellation, modification and replacement, with in-process or Lambda transport. - system: Platform audit store direction: outbound contract: >- Interventions send a Commerce audit event through the configured audit port. Deployed functions select Platform, whose adapter logs the event; omitted selection uses the fixture. - system: Workspace data export direction: outbound contract: Workspace export includes the fulfillment dataset. consistency: - rule: Authorization and dispatch entry commit in the gate-opening transaction. kind: transactional compensation: >- A lost nudge leaves retained dispatch for the minute schedule; no maximum delay is guaranteed. - rule: >- Current in-flight authorization checks retain the application outcome with its attempt. kind: transactional compensation: Stale answers append diagnosis without applying another current outcome. - rule: Waiting gates use current financial positions after event delivery. kind: eventual compensation: >- The bounded sweep can revisit pending records after inactivity and excludes blocked records. - rule: The local staff change retains its intervention in the same transaction. kind: transactional compensation: External audit failure is logged after the local act stands. - rule: Dependent settlement normally follows retained prerequisite outcomes. kind: eventual compensation: Logged continuation failure can require a later outcome or staff action. - rule: >- Financial steps run under stable keys without undoing successful earlier steps. kind: eventual compensation: Staff and scheduled recovery resume retained unfinished work. evidence: - >- services-commerce at c8b66a98: modules/fulfillment/aws/api/fulfillment.routes.ts; aws/fulfillment.module.ts; aws/logic/*.ts; aws/resources/obligations-queue.sqs.ts; services/**; contracts/financial-facts.ts; aws/commerce.service.ts (obligations, fulfillment-policies keys); aws/cdk/commerce.function-environment.ts. - 'services-commerce:modules/fulfillment/aws/api/fulfillment.routes.ts' - >- services-commerce:package-lock.json:@rhythmsoftware/macroservice-http; node_modules/@rhythmsoftware/macroservice-http/dist/health-route.js:healthRoute 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-CRY-001, TC-CRY-002, TC-CRY-003, 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-002, TC-AVL-003, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Fulfillment Service Module ## What This Service Is For Coordinate delivery conditions, authorizations and application outcomes so staff can see outstanding sale obligations. ## Boundary This service owns the register, policies, enforcements, exceptions and adjustments. Operations exposes some staff routes over those records; delivering applications own their resulting records. ## Operations in Words Staff read obligations, administer policies and use separately authorized interventions. Applications use system callbacks to report outcomes and readiness. ## Events and Jobs Receivable events trigger evaluation and reversal work. A scheduled dispatcher publishes authorization pointers, the queue worker invokes applications, and the Orders sweep revisits bounded pending and overdue records. Register history and audit attempts are internal records or calls, not published change events. ## Consistency Guarantees Gate opening and outcome application each have local transaction guarantees. Event processing and subsequent history, enforcement, dependency and document work can span commits. Known retries use stable authorization or step keys, while recorded gaps require explicit recovery design.