Rhythm 2.0 Specifications

Appearance

CAP-ACC-REC-009Allocate settlement money to one explanation

Markdown

CAP-ACC-REC-009

Allocate settlement money to one explanation

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-ACC-REC-02
Exercised by
FAS-ACC-REC-02-01, FAS-ACC-REC-02-02, FAS-ACC-REC-02-03, FAS-ACC-REC-02-04, FAS-ACC-REC-02-05, JNY-ACC-REC-004
Key concepts
CON-ACC-REC-003, CON-ACC-REC-002
Actors
ACT-ACC-017, ACT-ACC-018
Journeys
JNY-ACC-REC-001
Depends on
CAP-ACC-REC-008
Related
CAP-ACC-REC-010, CAP-ACC-REC-011
Proved by
ATS-ACC-REC-009
Executed by
TST-ACC-REC-008

Implementation

Executable suites
TST-ACC-REC-027, TST-ACC-REC-034, TST-ACC-REC-036, TST-ACC-REC-059, TST-ACC-REC-074, TST-ACC-REC-075, TST-ACC-REC-083

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

Allocate settlement money to one explanation ​

Purpose ​

Preparers need selections that remain coherent under concurrent work.

How It Works ​

A preparer chooses the settlement effects that belong to the deposit. Rhythm checks the item set and the current draft before committing allocations. Claims retain the evidence behind selection, and release preserves the earlier allocation as history. The console saves differences in an order that frees obsolete holdings before adding new ones. Another holder or stale version prevents an unsafe update.

Relationships ​

Draft creation supplies the workspace, manual entries add processor adjustments and finalization approves the complete allocation.

The Formal Contract

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

Outcomes
Allocations prevent two explanations from using one effect.Committed holdings determine the difference.Version checks protect concurrent preparation.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: claims, releases, concurrency by version)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U2, U3, U7)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-02, INV-05, INV-07, INV-19)

Controls

20 controls apply, from the corpus control catalogue.

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-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-DAT-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005

Permissions

KeyChecked atScope
accounting.reconciliation-batches.updateapitenant
accounting.reconciliation-batches.updateconsoletenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A claim uses the read version and one to five hundred item references, reporting all ineligible, resolved, incompatible or already-held-here items together.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope)
proved by ATS-ACC-REC-009-01, TST-ACC-REC-059
validationapi, servicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses every problem at once with 400, naming each item; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses an item already claimed in this batch with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses more than 500 items with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#writes no claim after the refusals
02must prove
Confirmed
An item has only one active claim across draft and finalized reconciliations; competing attempts yield one winner and identify the existing holder and preparer to the other.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-05)
proved by ATS-ACC-REC-009-02, TST-ACC-REC-027, TST-ACC-REC-034, TST-ACC-REC-075
invariantservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/claim-concurrency.integration.spec.js#refuses the second with 409 item_held naming the first batch and its preparer; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/claim-concurrency.integration.spec.js#lets the first claim succeed; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/claim-concurrency.integration.spec.js#leaves exactly one active claim of the item; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses a second draft’s claim of an item another draft holds; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses a draft’s claim of an item a finalized batch holds; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#refuses a claim of an item another batch holds with 409 item_held, naming that batch and its preparer
03must prove
Confirmed
Difference equals claimed money minus payout money in integer minor units, yielding Draft with no claims, In Progress with a nonzero difference and Balanced with a zero difference while open.
✓ 43 items of 10,000.00 against 9,725.00 read +275.00, in progress.✗ A balanced reconciliation is not finalized.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U7)
proved by ATS-ACC-REC-009-03, ATS-ACC-REC-009-11, ATS-ACC-REC-009-12, ATS-ACC-REC-010-11, TST-ACC-REC-036, TST-ACC-REC-074, TST-ACC-REC-083
calculationservice, databasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#generates the difference as claimed items less payouts, the brief’s sign; services-accounting:modules/reconciliation/tests/unit/rules/batch-status.spec.js#is a draft with nothing claimed, whatever its difference; services-accounting:modules/reconciliation/tests/unit/rules/batch-status.spec.js#is in progress with a claim and a difference short of zero; services-accounting:modules/reconciliation/tests/unit/rules/batch-status.spec.js#is balanced with a claim and a difference of exactly zero; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/brief-example.integration.spec.js#is in progress once the 42 captures and the refund are claimed, 27500 over the payout
04must prove
Confirmed
Claims preserve matching strength, explanation, source batch and claimant; each claim or release operation advances version once and writes audit history.
proved by ATS-ACC-REC-008-12, ATS-ACC-REC-009-04, TST-ACC-REC-027, TST-ACC-REC-059
lifecycleservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#stores the tier and the reasons the ranking gives each claim, and its operational batch; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#balances the batch with the two claims, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#records batch.items-claimed with the ids, the amount and the versions; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#stores each claim with its tier, its explanation, its operational batch and who claimed it
05must prove
Confirmed
Release removes money from current totals but keeps the claim with release time, actor and reason, freeing the item for reuse; manual entries use removal instead.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope)
proved by ATS-ACC-REC-009-05, TST-ACC-REC-059
lifecycleservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#keeps the released claim as history, with its time, actor and reason; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#takes the released claim out of the totals, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#lets the released item be claimed again; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses to release an item the batch does not claim with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses to release a manual item as a claim with 400
06must prove
Confirmed
Authoritative acceptance claims the processor-linked payout-reference and settlement-grouping candidates together; repeating it with no new candidate preserves the version.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U3: Accept All covers authoritative matches only)
proved by ATS-ACC-REC-009-06, TST-ACC-REC-059
policyservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#claims the tier 1 and tier 3 candidates and nothing else; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#changes the totals and the version in the same command; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#claims nothing more when accepted again, leaving the version as it was
07must prove
Confirmed
Claims change only an open reconciliation at its current version; stale edits fail.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-08)
proved by ATS-ACC-REC-009-07, TST-ACC-REC-027, TST-ACC-REC-034, TST-ACC-REC-059
validationservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a claim in a batch that is not open with 409 batch-not-open; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a claim at a version that is not the batch’s with 409 StaleObject; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses a claim into a finalized batch; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses the release of a finalized batch’s claim; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#refuses a claim at a version already moved on with 409
08must prove
Confirmed
A claim covers the complete item and preserves one unit, merchant and currency between item and reconciliation.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-02)
proved by ATS-ACC-REC-009-08, TST-ACC-REC-034, TST-ACC-REC-036
invariantdatabasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses a claim of part of an item (RHF35); services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses an item of another merchant account and currency; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses an item of another business unit; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a 10,001st claim
09must prove
Confirmed
A reconciliation cannot contain more than ten thousand claims.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-19)
proved by ATS-ACC-REC-009-08, TST-ACC-REC-034, TST-ACC-REC-036
invariantdatabasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a 10,001st claim; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses an item of another merchant account and currency; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses an item of another business unit; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-allocations.table.integration.spec.js#refuses a claim of part of an item (RHF35)
10must prove
Confirmed
Update permission governs claim, release and authoritative acceptance; read-only callers cannot use them.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)
proved by ATS-ACC-REC-009-09, TST-ACC-REC-027
permissionapitest
services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#refuses the reader a claim with 403
11
Confirmed
Save Draft sends only differences from the persisted draft, processing releases and removals before new claims and manual entries.
policyconsoletest
react-console:lib/accounting/reconciliation/adapter.test.ts#releases and removes before it claims and adds, and sends only what differs

Scenarios

IdGivenWhenThenProvenance
01The sample draft has forty-three candidates totaling ten thousand dollars.Claim those effects.Difference is positive two hundred seventy-five dollars and status is In Progress.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 5: claims the 43 items, 27500 over the payout (claimed − payout, INV-07)
02Two captures carry the deposit’s processor reference.Accept authoritative matches.Both receive the strongest matching rank and balance the explanation.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#claims the two captures carrying PX-1083 at tier 1, balancing RB-10001

Edge Cases

IdGivenWhenThenProvenance
03Two open drafts compete for one settlement item.Claim concurrently.One allocation succeeds and the other reports its holder.test
services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/claim-concurrency.integration.spec.js#leaves exactly one active claim of the item

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