Rhythm 2.0 Specifications

Appearance

CAP-COM-FUL-004Carry authorized work to its delivering application

Markdown

CAP-COM-FUL-004

Carry authorized work to its delivering application

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-COM-FUL-01
Exercised by
FAS-COM-FUL-01-01, FAS-COM-FUL-01-02, FAS-COM-FUL-01-03, FAS-COM-FUL-01-04, JNY-COM-FUL-005
Key concepts
CON-COM-FUL-001
Actors
ACT-COM-011, ACT-COM-013
Journeys
JNY-COM-FUL-001, JNY-COM-FUL-002
Depends on
CAP-COM-FUL-002
Related
CAP-COM-FUL-005, CAP-COM-FUL-006, CAP-COM-FUL-014
Proved by
ATS-COM-FUL-004

Implementation

Executable 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

KindCapabilityProduct areaCommerceModuleFulfillment, Shipping and InventoryRevision1

Read atservices-commerce c8b66a98

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.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Applications fulfill their own sold outcomes without staff copying the sale.Failed or unanswered delivery remains available for investigation.
Surfaces
jobapi

Controls

35 controls apply, from the corpus control catalogue.

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

Permissions

KeyChecked atScope
commerce.obligations.callbackapiglobal

Business Rules

13 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
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.
proved by ATS-COM-FUL-004-01, TST-COM-FUL-044, TST-COM-FUL-055
lifecycleservicetest
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
02must prove
Proposed
A failed or rejected publication leaves the dispatch entries available for a later run.
proved by ATS-COM-FUL-004-01, TST-COM-FUL-044, TST-COM-FUL-055
invariantservicetest
services-commerce:modules/fulfillment/tests/integration/services/register/obligation-dispatcher.integration.spec.js#leaves every row for the next run
03must prove
Proposed
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.
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
invariantservicetest
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)
04must prove
Proposed
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.
origin: D-P4-12 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-12
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
calculationservice, databasetest
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
05must prove
Proposed
Permanent refusal fails delivery and raises an exception, while retryable refusal or an unreachable application leaves delivery in flight for another attempt.
proved by ATS-COM-FUL-004-04, TST-COM-FUL-045
lifecycleservicetest
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
06must prove
Proposed
The fifth queue delivery fails the obligation for exhausted attempts and raises its exception before the message is dead-lettered.
origin: D-P4-07 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-07
proved by ATS-COM-FUL-004-04, TST-COM-FUL-045
lifecycleservicetest
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
07must prove
Proposed
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.
origin: D-P4-09 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-09
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
lifecycleapi, servicetest
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
08must prove
Proposed
Callback access is restricted to application service identities, rejects console and portal callers, and validates the request contract.
proved by ATS-COM-FUL-004-05, TST-COM-FUL-022, TST-COM-FUL-045
permissionapiobserved
services-commerce:modules/fulfillment/aws/api/fulfillment.routes.ts
09must prove
Proposed
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.
origin: D-P4-08 (build decision, not a product ruling): services-commerce:docs/migrations/obligation-register/README.md#D-P4-08
proved by ATS-COM-FUL-004-06, TST-COM-FUL-040, TST-COM-FUL-047
lifecycleservicetest
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
10must prove
Proposed
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.
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
invariantdatabasetest
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)
11must prove
Proposed
A sold line can have only one obligation for each operation and unit, preventing duplicate obligations on retried placement.
proved by ATS-COM-FUL-004-07, TST-COM-FUL-024, TST-COM-FUL-025, TST-COM-FUL-041
invariantdatabasetest
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
12
Proposed
The application role can append delivery attempts but cannot alter or remove the attempt history.
invariantdatabasetest
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)
13
Proposed
The worker logs a warning and acknowledges terminate and allocation-release operations without delivering them while no document produces them.
policyserviceobserved
services-commerce:modules/fulfillment/services/register/obligation-worker.ts

Scenarios

IdGivenWhenThenProvenance
01Three applications respectively complete, defer and refuse authorized work.Deliver the queued instructions.The register records completed, in-progress and failed outcomes and acknowledges each message.test
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

IdGivenWhenThenProvenance
02An application repeatedly returns a retryable failure.Deliver the message for the fifth time.The obligation reaches exhausted-attempt failure and an exception is recorded.test
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

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software