--- id: SVC-COM-FUL-operations title: Operations Service Module product_area: commerce module: fulfillment repository: services-commerce source_module: modules/operations revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: [] does_not_own: - >- Fulfillment declares the exceptions, adjustments, enforcements and intervention records served here. - >- Fulfillment owns obligation intervention logic; Orders owns void and post-sale documents. - >- Orders owns the billing, tender, void, mirror and register recovery passes in its checkout sweep. - The declared shared idempotency ledger follows Platform’s library contract. operations: - operation_id: getOperationsHealth 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: listOperationalExceptions intent: >- Return the permitted operational exceptions records with the route’s supported filters. access: console permission: commerce.exceptions.read realises: - CAP-COM-FUL-008 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: summarizeOperationalExceptions intent: Count operational findings by kind and state. access: console permission: commerce.exceptions.read realises: - CAP-COM-FUL-008 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: getOperationalException intent: >- Read the requested operational exception record within the current workspace. access: console permission: commerce.exceptions.read realises: - CAP-COM-FUL-008 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: acknowledgeOperationalException intent: Record staff awareness of the open operational exception finding. access: console permission: commerce.exceptions.acknowledge realises: - CAP-COM-FUL-008 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: resolveOperationalException intent: Retain staff closure of operational exception with the required result. access: console permission: commerce.exceptions.resolve realises: - CAP-COM-FUL-008 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listFinancialAdjustments intent: >- Return the permitted financial adjustments records with the route’s supported filters. access: console permission: commerce.adjustments.read realises: - CAP-COM-FUL-007 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getFinancialAdjustment intent: >- Read the requested financial adjustment record within the current workspace. access: console permission: commerce.adjustments.read realises: - CAP-COM-FUL-007 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: retryFinancialAdjustment intent: Resume unfinished financial adjustment steps under their existing keys. access: console permission: commerce.adjustments.retry realises: - CAP-COM-FUL-007 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: resolveFinancialAdjustment intent: Retain staff closure of financial adjustment with the required result. access: console permission: commerce.adjustments.resolve realises: - CAP-COM-FUL-007 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listEnforcements intent: >- Return the permitted enforcements records with the route’s supported filters. access: console permission: commerce.enforcements.read realises: - CAP-COM-FUL-006 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getEnforcement intent: Read the requested enforcement record within the current workspace. access: console permission: commerce.enforcements.read realises: - CAP-COM-FUL-006 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: resolveEnforcement intent: Retain staff closure of enforcement with the required result. access: console permission: commerce.enforcements.resolve realises: - CAP-COM-FUL-006 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. events: - 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. jobs: - name: commerce_reconciler schedule: >- Every minute, with per-check minute, five-minute, hourly and daily cadences; concurrency one and a 60-second timeout. does: >- Diagnoses order work, delegates stale adjustment execution and measures dead-letter depth. integrations: - system: Obligations dead-letter queue direction: inbound contract: >- The reconciler reads approximate obligation dead-letter depth and emits its hourly metric. - system: Accounting commands direction: outbound contract: >- Staff retry and reconciliation resume adjustment steps through Fulfillment’s financial worker and its Accounting command port. consistency: - rule: Staff intervention and subject change commit together locally. kind: transactional compensation: Audit failure is logged without reversing the committed act. - rule: 'Each due check supplies eventual, potentially partial diagnosis.' kind: eventual compensation: >- Later due execution can try again without a guaranteed continuation cursor. evidence: - >- services-commerce at c8b66a98: modules/operations/aws/api/operations.routes.ts; aws/operations.module.ts; aws/logic/reconciler.lambda.ts; services/**; db/idempotency-keys.table.ts; aws/commerce.service.ts (exceptions, adjustments, enforcements keys). - 'services-commerce:modules/operations/aws/api/operations.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-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-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Operations Service Module ## What This Service Is For Give staff a retained attention queue for order, delivery and money problems. ## Boundary Operations serves shared Fulfillment records without owning their tables. Its scheduled checks read candidates across workspaces and retain findings in each affected workspace. ## Operations in Words Staff list, count, acknowledge and resolve exceptions, inspect enforcements, and retry or resolve financial adjustments. Each act uses its particular authority and reason contract. ## Events and Jobs The minute reconciler runs checks at their due cadence, delegates adjustment execution and measures queue depth. Some declared checks remain placeholders, and audit calls use the provider that currently logs instead of storing Platform events. ## Consistency Guarantees Staff actions retain their local intervention with the change. Detection is eventual and partial: a thrown check is logged and later scheduled work can try again, without an established continuation guarantee.