Rhythm 2.0 Specifications

Appearance

CAP-ACC-REC-011Finalize a balanced explanation with eligible approval

Markdown

CAP-ACC-REC-011

Finalize a balanced explanation with eligible approval

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-ACC-REC-03
Exercised by
FAS-ACC-REC-03-01, FAS-ACC-REC-03-02, FAS-ACC-REC-03-03, FAS-ACC-REC-03-04, FAS-ACC-REC-07-01, FAS-ACC-REC-07-03, JNY-ACC-REC-003
Key concepts
CON-ACC-REC-003, CON-ACC-REC-001
Actors
ACT-ACC-018
Journeys
JNY-ACC-REC-001, JNY-ACC-REC-006
Depends on
CAP-ACC-REC-009, CAP-ACC-REC-010, CAP-ACC-REC-014
Related
CAP-ACC-REC-013, CAP-ACC-REC-020
Proved by
ATS-ACC-REC-011

Implementation

Executable suites
TST-ACC-REC-001, TST-ACC-REC-007, TST-ACC-REC-022, TST-ACC-REC-023, TST-ACC-REC-036, TST-ACC-REC-049, TST-ACC-REC-050, TST-ACC-REC-051, TST-ACC-REC-073, TST-ACC-REC-082, TST-ACC-REC-091, TST-ACC-REC-094

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

Finalize a balanced explanation with eligible approval ​

Purpose ​

Approvers need a protected financial record of a prepared deposit explanation.

How It Works ​

The approver inspects the saved draft and its supporting choices. Rhythm recomputes balance from actual holdings rather than trusting displayed counters. It evaluates approval eligibility and accounting setup before completing the decision. Successful finalization protects the explanation and creates the applicable requests for later posting. A failed prerequisite leaves preparation open, and console draft saving can change the approver’s eligibility.

Relationships ​

Claims and manual entries prepare the balance, accounting requests reach posting and reversal supplies the supported correction path.

The Formal Contract

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

Outcomes
Exact recomputed balance is required for finalization.Independent approval is required by default and waived decisions stay marked.Generated accounting distinguishes the transfer from individual recognition effects.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D7services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D2services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-07, INV-08, INV-12, INV-15, INV-16)

Controls

28 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-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-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-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-AI-005 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.reconciliation-batches.finalizeapitenant
accounting.reconciliation-batches.finalizeconsoletenant

Business Rules

13 rules, 12 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
Finalize checks the request key and read version, replays a successful identical call without another ledger request and rejects a fresh-key attempt on the finalized record.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command)
proved by ATS-ACC-REC-011-01, TST-ACC-REC-023, TST-ACC-REC-049
validationapi, servicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses another key after success, naming the state (DEF-ACT-0596); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#replays the stored answer for the same key and request; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#asks the ledger for nothing more on the replay; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses a request without an Idempotency-Key with 400; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses a body whose version is not a number with 400
02must prove
Confirmed
Finalize recomputes the difference from actual claims and payout links, rejects any nonzero amount with an audited refusal and leaves the reconciliation open.
✓ A reconciliation one cent short is refused with a difference of -1.✗ Counters that read zero over rows that do not are refused.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-07)
proved by ATS-ACC-REC-011-02, ATS-ACC-REC-011-12, TST-ACC-REC-007, TST-ACC-REC-023, TST-ACC-REC-036, TST-ACC-REC-049
calculationservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch whose counters balance but whose rows do not; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch one minor unit short, naming the difference; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#leaves the refused batch open; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records the refusal as batch.finalize-refused with the difference; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#finalizes a batch whose rows balance whatever its counters say, writing the rows’ totals; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses an unbalanced batch with 409, its code and its difference; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a finalized batch whose difference is not zero (INV-07); react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0597.spec.ts#ACT-ACC-0597
03must prove
Confirmed
The default second-person policy excludes the creator and anyone who claimed, released, added manual items or linked payouts, recording a refused self-approval.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3
proved by ATS-ACC-REC-009-12, ATS-ACC-REC-011-03, ATS-ACC-REC-011-11, ATS-ACC-REC-011-12, ATS-ACC-REC-011-14, ATS-ACC-REC-020-11, TST-ACC-REC-001, TST-ACC-REC-007, TST-ACC-REC-023, TST-ACC-REC-049, TST-ACC-REC-094
policyservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a person who claimed items in it; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses the person who created the batch; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records the refusal as batch.finalize-refused; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#lets the preparer finalize where the tenant does not require a second person, waived; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records segregation.waived for that finalize; services-accounting:modules/reconciliation/tests/unit/rules/segregation.spec.js#refuses a preparer while a second person is required; services-accounting:modules/reconciliation/tests/unit/rules/segregation.spec.js#records any finalize as waived when the tenant does not require a second person; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses the preparer with 403 segregation-required; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0590.spec.ts#ACT-ACC-0590; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0597.spec.ts#ACT-ACC-0597
04must prove
Confirmed
With the second-person requirement disabled, preparers can finalize and every finalization records that the control was waived.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3
proved by ATS-ACC-REC-011-03, ATS-ACC-REC-011-14, ATS-ACC-REC-020-11, TST-ACC-REC-023, TST-ACC-REC-049, TST-ACC-REC-094
policyservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records segregation.waived for that finalize; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses the person who created the batch; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a person who claimed items in it; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records the refusal as batch.finalize-refused; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#lets the preparer finalize where the tenant does not require a second person, waived; services-accounting:modules/reconciliation/tests/unit/rules/segregation.spec.js#refuses a preparer while a second person is required; services-accounting:modules/reconciliation/tests/unit/rules/segregation.spec.js#records any finalize as waived when the tenant does not require a second person; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses the preparer with 403 segregation-required
05must prove
Confirmed
Finalization rejects a voided reconciliation, absent payout links, voided linked payouts and resolved claimed items.
proved by ATS-ACC-REC-011-04, ATS-ACC-REC-011-12, TST-ACC-REC-007, TST-ACC-REC-049
validationservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch whose item was resolved after it was claimed; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch whose payout was voided after it was linked; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch that explains no payout; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a voided batch; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0597.spec.ts#ACT-ACC-0597
06must prove
Confirmed
Finalize creates a single transfer request containing nonzero net lines per bank and a clearing total when nonzero, plus required unrecognized manual or imported fee, reserve and adjustment requests; an all-zero transfer is omitted.
✓ A 9,725.00 deposit with a 225.00 fee and 50.00 reserve asks for three balanced entries.✗ A zero payout asks for its fee only.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D7
proved by ATS-ACC-REC-009-12, ATS-ACC-REC-010-12, ATS-ACC-REC-011-05, ATS-ACC-REC-011-11, ATS-ACC-REC-014-11, TST-ACC-REC-001, TST-ACC-REC-049, TST-ACC-REC-091
calculationserviceobserved
services-accounting:modules/reconciliation/services/batch-lifecycle/finalize-batch.ts:plansOf
07must prove
Confirmed
Missing default accounts stop finalization before writes and identify the account purpose requiring setup.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D7 (refused by name when a default is missing)
proved by ATS-ACC-REC-011-06, TST-ACC-REC-049, TST-ACC-REC-051
validationservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a fee in a unit with no processor_fee_expense default; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-posts-to-subledger.integration.spec.js#is refused naming the missing default; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-posts-to-subledger.integration.spec.js#asks the ledger for nothing, so batch posting has nothing to post for it
08must prove
Confirmed
After operational batch posting, reconciliation entries offset the posted captures and refunds it explains in processor clearing.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D2
proved by ATS-ACC-REC-010-12, ATS-ACC-REC-011-05, ATS-ACC-REC-014-11, TST-ACC-REC-049, TST-ACC-REC-091
invariantserviceobserved
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-posts-to-subledger.integration.spec.js
09must prove
Confirmed
Finalized holdings, notes, totals and payout amounts remain sealed; reversal is the supported way to release them.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-08)
proved by ATS-ACC-REC-011-07, ATS-ACC-REC-011-13, TST-ACC-REC-049
lifecycleservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#locks the finalized batch against updates and deletes; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses releasing one of its claims (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses changing its payout’s amount (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses changing the batch itself (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#resolves the payout’s unbalanced-payout exception naming the batch; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records batch.finalized by the approver with the posting dates, batch and keys
10must prove
Confirmed
Finalize closes open unbalanced-payout exceptions and records the finalizer, operational batch, dates and ledger keys.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U10: finalize resolves only exceptions whose condition it cleared)
proved by ATS-ACC-REC-011-07, ATS-ACC-REC-011-13, TST-ACC-REC-049
lifecycleservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#resolves the payout’s unbalanced-payout exception naming the batch; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#locks the finalized batch against updates and deletes; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses releasing one of its claims (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses changing its payout’s amount (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses changing the batch itself (RHF30); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#records batch.finalized by the approver with the posting dates, batch and keys
11must prove
Confirmed
Period locking serializes finalize with close, marks closed-period effects late and uses the default-selected operational batch’s date only when that batch accepts work in an open period, without automatically selecting a later batch.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-16)
proved by ATS-ACC-REC-011-08, ATS-ACC-REC-011-15, ATS-ACC-REC-018-13, TST-ACC-REC-049, TST-ACC-REC-050
policyservice, databaseobserved
services-accounting:modules/reconciliation/services/persistence/reconciliation-ledger-postings.ts:recordPostings
12must prove
Confirmed
The sensitive finalize permission and preparation guards determine whether finalize is offered, including an explanation when preparation prevents it.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3
proved by ATS-ACC-REC-011-09, TST-ACC-REC-023, TST-ACC-REC-073, TST-ACC-REC-082
permissionapi, servicetest
services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/batch-views.integration.spec.js#names why finalize is withheld from the person who prepared it; services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses a principal without accounting.reconciliation-batches.finalize with 403; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/batch-views.integration.spec.js#offers finalize to a person who did not prepare it; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/batch-views.integration.spec.js#does not offer finalize to the person who prepared it, the tenant requiring a second person; services-accounting:modules/reconciliation/tests/integration/services/reconciliation-batches/batch-views.integration.spec.js#offers finalize to the preparer once the tenant turns the second-person rule off; services-accounting:modules/reconciliation/tests/unit/rules/batch-actions.spec.js#offers finalize only while balanced; services-accounting:modules/reconciliation/tests/unit/rules/batch-actions.spec.js#keeps only the actions whose permission the caller holds; services-accounting:modules/reconciliation/tests/unit/rules/batch-actions.spec.js#offers a finalized batch its reversal alone
13
Confirmed
Console finalize is hidden from a disqualified preparer, saves current draft changes first and labels a waived result as finalized without second approval.
proved by ATS-ACC-REC-011-10, TST-ACC-REC-022
policyconsoleobserved
react-console:components/accounting/reconciliation/workspace/workspace.tsx:ReconWorkspace

Scenarios

IdGivenWhenThenProvenance
01The sample explanation balances with fee and reserve entries prepared by one person.Have that preparer attempt approval, then an independent approver finalize.Preparation prevents self-approval and the independent decision creates the required transfer and recognitions.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 7: posts the fee 22500, the reserve 5000 and the bank 972500 against the clearing account, each balanced
02The explanation differs by one minor unit.Attempt finalize.The difference is reported and the draft stays open.test
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#refuses a batch one minor unit short, naming the difference

Edge Cases

IdGivenWhenThenProvenance
03A fee-only deposit is negative.Finalize its explanation.Accounting requests the transfer from bank back to clearing.test
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#posts a bank debit from the bank to clearing
04No operational batch accepts the generated requests.Attempt finalize.Rollback leaves the open version intact without a request or event.test
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/finalize-batch.integration.spec.js#writes nothing when refused for want of a batch: the batch open at its version, no request, no event

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