Rhythm 2.0 Specifications

Appearance

CAP-ACC-TRX-020Coordinate financial commands across applications

Markdown

CAP-ACC-TRX-020

Coordinate financial commands across applications

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationPartially observed

Planning

Feature
FEAT-ACC-TRX-06
Exercised by
FAS-ACC-TRX-06-01, FAS-ACC-TRX-06-03, FAS-ACC-TRX-06-04, FAS-ACC-TRX-06-05
Key concepts
CON-ACC-TRX-006
Actors
ACT-ACC-021, ACT-ACC-022
Journeys
JNY-ACC-TRX-006
Related
CAP-ACC-TRX-001, CAP-ACC-TRX-007, CAP-ACC-TRX-009, CAP-ACC-TRX-014, CAP-ACC-TRX-016, CAP-ACC-TRX-018
Open questions
OQ-ACC-TRX-001
Proved by
ATS-ACC-TRX-020

Implementation

Executable suites
TST-ACC-TRX-016, TST-ACC-TRX-031, TST-ACC-TRX-032, TST-ACC-TRX-041, TST-ACC-TRX-043, TST-ACC-TRX-052, TST-ACC-TRX-081, TST-ACC-TRX-121, TST-ACC-TRX-206, TST-ACC-TRX-211, TST-ACC-TRX-223

KindCapabilityProduct areaAccountingModuleTransactionsRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Coordinate financial commands across applications ​

Purpose ​

Connected applications retry financial work safely and consume Accounting’s resulting facts.

How It Works ​

Commerce uses a registered service identity and separate functions for billing, tender and reversal. Commands retain actor attribution and use retry identities to avoid duplicate effects. Accounting appends receivable history alongside successful financial changes. Configured change delivery retries receiver failures, while an absent Commerce receiver currently acknowledges events with a log. Platform processor events are applied transactionally once. Order-line positions remain available for financial reconstruction. Workspace deletion removes owned financial data before dependent configuration.

Relationships ​

  • Issue customer bills and numbered quotes supplies or continues the related financial work.
  • Collect processor payments and resolve uncertainty supplies or continues the related financial work.
  • Complete invoice settlement with credit and money supplies or continues the related financial work.
  • Unwind billed purchases and their collected value supplies or continues the related financial work.
  • Find money records and understand available work supplies or continues the related financial work.
  • Preserve and read monthly receivables aging supplies or continues the related financial work.

The Formal Contract

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

Outcomes
Connected applications retry financial work safely and consume Accounting’s resulting facts.Order-line positions remain available for financial reconstruction. Workspace deletion removes owned financial data before dependent configuration.
Surfaces
apijob
Intent sources
services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-07services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M4-1services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M4-2services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M4-6services-accounting:docs/accounting/invoices.md#Invoices

Controls

33 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-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-VEN-001 TC-VEN-002 TC-VEN-003 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.invoices.createapitenant
accounting.payments.createapitenant
accounting.reversals.createapitenant
accounting.tax.calculateapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Commerce authenticates as its own registered service identity through separately restricted billing, tender, reversal and tax functions; unknown identities are denied.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-07
proved by ATS-ACC-TRX-014-09, ATS-ACC-TRX-019-08, ATS-ACC-TRX-020-01, ATS-ACC-TRX-020-09, TST-ACC-TRX-016, TST-ACC-TRX-206
permissionapi, servicetest
services-accounting:modules/transactions/tests/e2e/service-functions.e2e.spec.js#it refuses a principal the registry does not know (403) and an event that is not a package (400)
02must prove
Proposed
Service-created records identify the service actor and preserve the originating person when supplied.
proved by ATS-ACC-TRX-001-17, ATS-ACC-TRX-016-08, ATS-ACC-TRX-020-02, ATS-ACC-TRX-020-09, TST-ACC-TRX-121
invariantservicetest
services-accounting:modules/transactions/tests/integration/services/service-calls/service-caller.integration.spec.js#it records the service principal as the actor of what it creates
03must prove
Confirmed
A retry key replays the stored result for the same command body, rejects altered reuse and remains reusable after a refused command commits nothing.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
proved by ATS-ACC-TRX-001-17, ATS-ACC-TRX-008-09, ATS-ACC-TRX-014-09, ATS-ACC-TRX-020-03, ATS-ACC-TRX-020-09, TST-ACC-TRX-052, TST-ACC-TRX-223
policyapi, service, databasetest
services-accounting:modules/transactions/tests/integration/services/invoices/idempotency.integration.spec.js#it refuses the second request 409 idempotency_key_reused
04must prove
Proposed
Retry-key ownership spans the workspace, preventing another actor from executing an independent command under a used key.
origin: services-accounting:docs/accounting/invoices.md#Invoices
proved by ATS-ACC-TRX-020-04, TST-ACC-TRX-052, TST-ACC-TRX-081, TST-ACC-TRX-211
policyservice, databasetest
services-accounting:modules/transactions/tests/integration/services/invoices/idempotency.integration.spec.js#it refuses the second person 409 idempotency_key_in_use, never an unhandled error (DEF-ACT-0800)
05must prove
Confirmed
Racing identical requests execute the financial effect once, although a competing request can receive a lifecycle refusal rather than a replay.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
proved by ATS-ACC-TRX-007-12, ATS-ACC-TRX-020-05, ATS-ACC-TRX-020-09, TST-ACC-TRX-052
invariantservice, databasetest
services-accounting:modules/transactions/tests/integration/services/invoices/idempotency.integration.spec.js#it issues the invoice once and refuses the other issue invoice_not_draft
06must prove
Confirmed
Receivable history records each monetary change and reconstructs both current balances and earlier positions at their known-time cutoff.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
proved by ATS-ACC-TRX-016-08, ATS-ACC-TRX-020-06, ATS-ACC-TRX-020-09, TST-ACC-TRX-043
invariantservice, databasetest
services-accounting:modules/transactions/tests/integration/services/invoices/as-of.integration.spec.js#it answers, as of today and known now, exactly the live balance of every open invoice (FC-07)
07must prove
Proposed
Transactional receivable events retry failed configured delivery, but acknowledge and log events when Commerce has no configured receiver.
proved by ATS-ACC-TRX-020-07, TST-ACC-TRX-031, TST-ACC-TRX-032
policyserviceobserved
services-accounting:modules/transactions/services/change-events/commerce-financial-facts.ts:commerceFinancialFactsHandler
08must prove
Proposed
Platform-routed processor events are consumed transactionally by identity, so redelivery changes nothing and unrelated or unknown payments are ignored.
proved by ATS-ACC-TRX-007-12, ATS-ACC-TRX-012-12, ATS-ACC-TRX-013-10, ATS-ACC-TRX-020-08, ATS-ACC-TRX-020-09, TST-ACC-TRX-016, TST-ACC-TRX-041
invariantservice, databasetest
services-accounting:modules/transactions/tests/integration/services/integrations/integration-events.integration.spec.js#it records every event it handles or ignores by id in the handling transaction, and a replay is ignored by the row, not by a lookup
09
Confirmed
The order-line position view supplies Commerce with invoiced, settled, credited, refunded and abandoned amounts.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
policydatabasetest
services-accounting:modules/transactions/tests/integration/services/persistence/order-line-positions.queries.integration.spec.js#it answers a paid line as settled in full
10
Proposed
Accounting still serves Commerce tax quotes despite the recorded transfer of tax determination to Commerce.
origin: OQ-ACC-TRX-001
policyapitest
services-accounting:modules/transactions/tests/e2e/service-functions.e2e.spec.js#it serves the calculation as Commerce: a quote of a line with no address is zero with the warning, and nothing else is served
11
Proposed
Deletion purges transaction data before dependent configuration and refuses to purge an active workspace.
lifecycleservicetest
services-accounting:modules/transactions/tests/integration/services/lifecycle/transactions-participant.integration.spec.js#it refuses to purge a live tenant, with nothing removed

Scenarios

IdGivenWhenThenProvenance
01Commerce needs to bill an order using resolved terms.Invoke its separate billing service.The issued invoice identifies Commerce as the creating actor.test
react-console:acceptance/accounting/playwright/journeys/cross-application/ACT-ACC-0800.spec.ts#ACT-ACC-0800
02A request’s completion is uncertain to another operator.Submit a retry using its original key.The operation returns its earlier result or a refusal without a second financial execution.test
react-console:acceptance/accounting/playwright/journeys/cross-application/ACT-ACC-0807.spec.ts#ACT-ACC-0807

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