Rhythm 2.0 Specifications

Appearance

CAP-ACC-REC-020Separate duties and retain trustworthy reconciliation records

Markdown

CAP-ACC-REC-020

Separate duties and retain trustworthy reconciliation records

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-ACC-REC-07
Exercised by
FAS-ACC-REC-07-01, FAS-ACC-REC-07-02, FAS-ACC-REC-07-03, FAS-ACC-REC-07-04, FAS-ACC-REC-07-05
Key concepts
CON-ACC-REC-003, CON-ACC-REC-001, CON-ACC-REC-002, CON-ACC-REC-004
Actors
ACT-ACC-019, ACT-ACC-017, ACT-ACC-018, ACT-ACC-007, ACT-ACC-011
Journeys
JNY-ACC-REC-006
Related
CAP-ACC-REC-011, CAP-ACC-REC-013, CAP-ACC-REC-016
Proved by
ATS-ACC-REC-020

Implementation

Executable suites
TST-ACC-REC-016, TST-ACC-REC-017, TST-ACC-REC-018, TST-ACC-REC-026, TST-ACC-REC-029, TST-ACC-REC-031, TST-ACC-REC-032, TST-ACC-REC-033, TST-ACC-REC-038, TST-ACC-REC-064, TST-ACC-REC-087, TST-ACC-REC-093, TST-ACC-REC-097

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

Separate duties and retain trustworthy reconciliation records ​

Purpose ​

Controllers need permissions, retry safeguards and history that support accountable financial work.

How It Works ​

A controller assigns roles using the declared preparation and approval policies. Rhythm evaluates those grants at service boundaries and narrows applicable screen actions. Keyed financial decisions can be retried without repeating their committed effect. History retains committed activity while isolation keeps workspace records separate. Missing waiver administration, incomplete file export and the ungated note control remain design concerns.

Relationships ​

Platform owns role assignment, Books stores the approval setting and reconciliation workflows use the shared permission, key and activity controls.

The Formal Contract

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

Outcomes
Roles can separate preparation from sensitive approval.Keyed retries preserve committed financial effects.Committed activity and workspace isolation support accountable review.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions (preparer and approver policies); idempotency of every money command)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D5services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U13)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-01, INV-03)

Controls

31 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-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-DAT-005 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-AI-005 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.application.accessapitenant
accounting.payouts.readapitenant
accounting.reconciliation-batches.finalizeapitenant
accounting.reconciliation-batches.reverseapitenant
accounting.settlement-items.resolveapitenant
accounting.reconciliation-exceptions.acceptapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
The catalogue defines sixteen reconciliation keys: read-tier inspection, user-tier ordinary changes and four sensitive administrator approvals for finalize, reverse, resolve and accept, without bulk keys.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)
proved by ATS-ACC-REC-020-01, TST-ACC-REC-097
permissionapitest
services-accounting:tests/unit/reconciliation-permissions.spec.ts#makes every approval tier admin and sensitive; services-accounting:tests/unit/reconciliation-permissions.spec.ts#publishes exactly the reconciliation keys of the architecture, no bulk among them; services-accounting:tests/unit/reconciliation-permissions.spec.ts#makes each read tier read, so the Read Only policy carries it; services-accounting:tests/unit/reconciliation-permissions.spec.ts#makes the ordinary writes tier user: reconciliation’s records are records, not configuration
02must prove
Confirmed
Declared preparer and approver policies separate duties, with preparers reading and doing ordinary work and approvers adding the four sensitive approvals; a role must assign a policy before it grants access.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: preparer and approver policies)
proved by ATS-ACC-REC-011-14, ATS-ACC-REC-016-10, ATS-ACC-REC-020-02, ATS-ACC-REC-020-11, ATS-ACC-REC-020-13, TST-ACC-REC-097
permissionapitest
services-accounting:tests/unit/reconciliation-permissions.spec.ts#lets the preparer record payouts and prepare reconciliations, and approve nothing; services-accounting:tests/unit/reconciliation-permissions.spec.ts#lets the approver do what the preparer does and the four approvals; services-accounting:tests/unit/reconciliation-permissions.spec.ts#files both policies under the accounting application
03must prove
Confirmed
Permission grants operate throughout the workspace, while financial records retain their unit context for accounting.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D5
proved by ATS-ACC-REC-020-03, TST-ACC-REC-016, TST-ACC-REC-026
permissionapiobserved
services-accounting:aws/accounting.service.ts:ReconciliationBuiltInPolicies
04must prove
Confirmed
Keyed creation, payout void or verification, manual addition, finalize, reverse, split, resolution and acceptance require a header key up to 255 characters, scope retries to caller and operation, reject changed bodies and retain keys until purge.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command)
proved by ATS-ACC-REC-020-04, TST-ACC-REC-017, TST-ACC-REC-031, TST-ACC-REC-032
validationapi, service, databaseobserved
services-accounting:modules/reconciliation/services/persistence/idempotency-keys.ts:requireIdempotencyKey; services-accounting:modules/reconciliation/aws/api/payouts.routes.ts; services-accounting:modules/reconciliation/aws/api/reconciliation.routes.ts; services-accounting:modules/reconciliation/aws/api/matching.routes.ts; services-accounting:modules/reconciliation/aws/api/batch-lifecycle.routes.ts; services-accounting:modules/reconciliation/aws/api/outstanding.routes.ts
05must prove
Confirmed
Audit events keep the actual actor and bounded detail in the command transaction, with keys where applicable; bulk claims may emit several, repeat no-ops and replay may emit none, and rollback emits none, while history permits deletion only in purge.
origin: services-accounting:docs/reconciliation/brief.md#Controls (Andrew’s product brief, 2026-10-15): audit trails
proved by ATS-ACC-REC-001-14, ATS-ACC-REC-016-11, ATS-ACC-REC-020-05, ATS-ACC-REC-020-12, ATS-ACC-REC-020-14, TST-ACC-REC-038, TST-ACC-REC-064
invariantservice, databaseobserved
services-accounting:modules/reconciliation/services/persistence/reconciliation-events.ts:recordEvent; services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts; services-accounting:modules/reconciliation/db/reconciliation-events.table.ts; services-accounting:modules/reconciliation/services/persistence/idempotency-keys.ts
06must prove
Confirmed
Refusals carry a stable machine code independently of their displayed wording.
proved by ATS-ACC-REC-020-06, TST-ACC-REC-029, TST-ACC-REC-093
policyapitest
services-accounting:modules/reconciliation/tests/e2e/refusal-codes.e2e.spec.js#keeps the code a refusal carries: a create without an Idempotency-Key answers 400 idempotency_key_required; services-accounting:modules/reconciliation/tests/e2e/refusal-codes.e2e.spec.js#answers a payout edit whose body breaks its schema 400 validation_failed; services-accounting:modules/reconciliation/tests/e2e/refusal-codes.e2e.spec.js#answers an unknown payout 404 not_found; services-accounting:modules/reconciliation/tests/e2e/refusal-codes.e2e.spec.js#answers a payout edit at a version already moved on 409 stale_version; services-accounting:modules/reconciliation/tests/e2e/refusal-codes.e2e.spec.js#answers a cursor the list did not answer 400 invalid_request; services-accounting:modules/reconciliation/tests/unit/rules/refusal-codes.spec.js#keeps the code a refusal carries; services-accounting:modules/reconciliation/tests/unit/rules/refusal-codes.spec.js#names a state refusal without a refusal word illegal_operation
07must prove
Confirmed
Workspace isolation prevents reading or writing another customer’s reconciliation records.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-01)
proved by ATS-ACC-REC-004-09, ATS-ACC-REC-020-07, TST-ACC-REC-018, TST-ACC-REC-033
invariantdatabasetest
services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses a row written for another tenant; services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#hides them from another tenant; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0610.spec.ts#ACT-ACC-0610
08must prove
Confirmed
Missing authentication fails before access, and denied Accounting access prevents reconciliation reads.
proved by ATS-ACC-REC-020-03, TST-ACC-REC-016, TST-ACC-REC-026
permissionapitest
services-accounting:modules/reconciliation/tests/e2e/reconciliation-lists.e2e.spec.js#refuses a request without a security context with 401; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0608.spec.ts#ACT-ACC-0608; services-accounting:modules/reconciliation/tests/e2e/reconciliation-lists.e2e.spec.js#refuses a principal denied accounting.application.access with 403
09must prove
Confirmed
Amounts use integer minor units, reject arithmetic beyond the exact safe range and display the currency’s decimal places.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-03)
proved by ATS-ACC-REC-020-08, TST-ACC-REC-087
calculationservicetest
services-accounting:modules/reconciliation/tests/unit/rules/money.spec.js#refuses a sum past the safe-integer range; services-accounting:modules/reconciliation/tests/unit/rules/money.spec.js#refuses a fraction, naming what it expected; services-accounting:modules/reconciliation/tests/unit/rules/money.spec.js#formats an exponent of 0 with no decimal point
10must prove
Confirmed
Second-person finalization defaults on and can be represented as waived in settings, but no current product operation or screen changes that setting.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3 (turning it off is an audited administrator’s change)
proved by ATS-ACC-REC-020-09
policyserviceobserved
services-accounting:modules/books/services/persistence/settings.ts:toSettings
11
Confirmed
Console action gates cover creation, finalize, reverse, verification, resolution and acceptance with permission hints; the exception-note button checks text presence without update permission.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U13)
permissionconsoleobserved
react-console:components/accounting/reconciliation/exceptions-screen.tsx:ExceptionDetail
12
Confirmed
Exports retain reconciliation record identities and relationships while excluding operational retry keys and integration connection or execution references.
policyserviceobserved
services-accounting:modules/reconciliation/export/reconciliation.dataset.ts:reconciliationExport
13must prove
Confirmed
Evidence exports contain asset references without copyable service addresses, so a retained reference alone does not prove that the package contains the document.
proved by ATS-ACC-REC-020-10
policyserviceobserved
services-accounting:modules/reconciliation/export/reconciliation.dataset.ts:reconciliationExport

Scenarios

IdGivenWhenThenProvenance
01People hold preparer, approver and access-only roles.Exercise reconciliation under each role.Preparation and approval follow their distinct grants, while access-only cannot read records.test
react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0608.spec.ts#ACT-ACC-0608
02A finalize already succeeded under its request key.Retry the identical request.The saved answer returns with no further ledger request.test
services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#replays the same answer for the same Idempotency-Key

Edge Cases

IdGivenWhenThenProvenance
03Two colleagues choose identical key text for payout creation.Submit as each caller.They remain separate requests and payout duplicate checks govern the second creation.test
react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0609.spec.ts#ACT-ACC-0609

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