Rhythm 2.0 Specifications

Appearance

CAP-ACC-REC-013Reverse an approved explanation and prepare its replacement

Markdown

CAP-ACC-REC-013

Reverse an approved explanation and prepare its replacement

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

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

Implementation

Executable suites
TST-ACC-REC-023, TST-ACC-REC-028, TST-ACC-REC-036, TST-ACC-REC-052, TST-ACC-REC-091, TST-ACC-REC-095

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

Reverse an approved explanation and prepare its replacement ​

Purpose ​

Approvers need an accountable way to correct finalized reconciliation work.

How It Works ​

The approver records why the approved explanation is wrong. Rhythm evaluates the period and either completes reversal or records a request for independent approval. Accounting mirrors preserve the original effect while undoing its requested consequence. Released money can then be explained in another reconciliation. Missing operational capacity leaves the old explanation or pending request intact.

Relationships ​

Finalization creates the protected record, ledger requests carry its mirrors and readiness reports unfinished reversal approval.

The Formal Contract

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

Outcomes
Correction preserves the earlier approved record.Closed-period reversal retains independent approval.The replacement becomes the payout’s current explanation.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U8)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-08, INV-16)

Controls

22 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-LOG-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.reverseapitenant
accounting.reconciliation-batches.reverseconsoletenant

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
Correction of a finalized reconciliation uses reversal rather than reopening or editing.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1
proved by ATS-ACC-REC-013-01, TST-ACC-REC-036, TST-ACC-REC-095
policyservice, databasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses to reopen a finalized batch; services-accounting:modules/reconciliation/tests/unit/rules/transitions.spec.js#refuses open as batch-reopen-not-offered
02must prove
Confirmed
Reversal requires a reason, key and current version of a finalized record, and another fresh-key reversal fails after completion.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1
proved by ATS-ACC-REC-013-02, TST-ACC-REC-023, TST-ACC-REC-052
validationapi, servicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses a second reversal under another key, naming the state (DEF-ACT-0596); services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses a reversal without an Idempotency-Key with 400; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses an open batch; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records the refusal as batch.reverse-refused
03must prove
Confirmed
In an open period, reversal immediately mirrors the outstanding original requests with debit and credit swapped in the selected operational batch, marks the reconciliation reversed and releases its holdings with the reason.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1
proved by ATS-ACC-REC-012-08, ATS-ACC-REC-013-03, ATS-ACC-REC-014-12, TST-ACC-REC-028, TST-ACC-REC-052, TST-ACC-REC-091
lifecycleservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#asks for the mirrors of the transfer and the fee, debits and credits swapped, in the unit’s batch on its date; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#answers the reversed batch whole; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#releases its claims and payout link with the reason; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records batch.reversed with its dates, batch and mirrors; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#reads the reversal on the reversed batch itself: reason, requester, approver and time (DEF-ACT-0594); services-accounting:modules/reconciliation/tests/unit/rules/posting-plans.spec.js#swaps every line’s debit and credit under the transfer’s reverse key; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: mirrors every posting of the finalize, debits and credits swapped
04must prove
Confirmed
In a closed period, reversal first records a pending request while preserving finalized state and creates no mirrors; a duplicate pending request fails.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1 (a second approver when the month is closed)
proved by ATS-ACC-REC-013-04, ATS-ACC-REC-013-11, ATS-ACC-REC-020-12, TST-ACC-REC-036, TST-ACC-REC-052
policyservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records the request and leaves the batch finalized, awaiting a second approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#asks for no mirror yet; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records batch.reversal-requested; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses a second request while one awaits approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses the requester’s own approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses an approval at a stale version; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses the approval: the batch its mirrors would ride in is in a closed period; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#leaves the reversal awaiting approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#answers the reversed batch with its approver; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#dates the mirrors on the November batch’s date, the original date their document date; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a reversal approved by the person who requested it
05must prove
Confirmed
The reversal requester cannot approve, stale approval fails, and missing operational capacity in an open period leaves approval pending.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1
proved by ATS-ACC-REC-013-04, ATS-ACC-REC-013-11, ATS-ACC-REC-020-12, TST-ACC-REC-036, TST-ACC-REC-052
permissionservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses the requester’s own approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records the request and leaves the batch finalized, awaiting a second approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#asks for no mirror yet; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records batch.reversal-requested; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses a second request while one awaits approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses an approval at a stale version; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses the approval: the batch its mirrors would ride in is in a closed period; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#leaves the reversal awaiting approval; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#answers the reversed batch with its approver; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#dates the mirrors on the November batch’s date, the original date their document date; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a reversal approved by the person who requested it
06must prove
Confirmed
Approved mirrors use the default-selected operational batch’s open-period date and retain the original effect day as document date.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-16)
proved by ATS-ACC-REC-013-04, ATS-ACC-REC-013-11, ATS-ACC-REC-020-12, TST-ACC-REC-036, TST-ACC-REC-052
calculationserviceobserved
services-accounting:modules/reconciliation/services/batch-lifecycle/reverse-batch.ts:completeReversal
07must prove
Confirmed
Released payouts and items can be reconciled again; retained manual entries can receive a subsequent numbered recognition after their earlier one was reversed.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1
proved by ATS-ACC-REC-013-05, ATS-ACC-REC-013-10, TST-ACC-REC-028, TST-ACC-REC-052, TST-ACC-REC-091
calculationservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#recognises the fee under its second key when a new batch reconciles it again; services-accounting:modules/reconciliation/tests/unit/rules/posting-plans.spec.js#numbers a second recognition after a reversal; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: releases the claims, so batch 1042’s captures are outstanding again
08must prove
Confirmed
The reversed record displays the reason, requester, approval identity and completion time.
proved by ATS-ACC-REC-012-08, ATS-ACC-REC-013-03, ATS-ACC-REC-014-12, TST-ACC-REC-028, TST-ACC-REC-052, TST-ACC-REC-091
invariantservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#reads the reversal on the reversed batch itself: reason, requester, approver and time (DEF-ACT-0594); services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#answers the reversed batch whole; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#asks for the mirrors of the transfer and the fee, debits and credits swapped, in the unit’s batch on its date; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#releases its claims and payout link with the reason; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#records batch.reversed with its dates, batch and mirrors; services-accounting:modules/reconciliation/tests/unit/rules/posting-plans.spec.js#swaps every line’s debit and credit under the transfer’s reverse key; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: mirrors every posting of the finalize, debits and credits swapped
09must prove
Confirmed
A reversal without an accepting open batch rolls back completely, retaining finalized state, version and holdings with no mirror or refusal event.
proved by ATS-ACC-REC-013-06, TST-ACC-REC-052
invariantservicetest
services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#writes nothing: the batch finalized at its version, its claims held, no mirror, no event; services-accounting:modules/reconciliation/tests/integration/services/batch-lifecycle/reverse-batch.integration.spec.js#refuses the reversal: no open batch takes its mirrors
10must prove
Confirmed
The sensitive reverse permission controls both the request and its second-person approval.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)
proved by ATS-ACC-REC-013-07, TST-ACC-REC-023, TST-ACC-REC-028
permissionapitest
services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#refuses a principal without accounting.reconciliation-batches.reverse with 403; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: refuses the reverse to a user without accounting.reconciliation-batches.reverse with 403
11
Confirmed
Console reversal asks for a reason, shows pending approval, offers approval and lets staff start another reconciliation after reversal.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U8)
policyconsoleobserved
react-console:components/accounting/reconciliation/workspace/workspace.tsx:ReconWorkspace

Scenarios

IdGivenWhenThenProvenance
01An approved explanation has the wrong reserve amount in an open period.Reverse and prepare the deposit’s corrected explanation.Mirrored accounting releases the original holdings and permits the replacement to finalize.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: reconciles PX-1083 again in a new batch and finalizes it
02The original explanation belongs to a closed period.Request reversal and obtain independent approval with an accepting November batch.Mirrors wait for approval and then use November accounting dates.test
services-accounting:modules/reconciliation/tests/e2e/batch-lifecycle.e2e.spec.js#answers 200 with the reversed batch to another person’s approval once the unit has a November batch

Edge Cases

IdGivenWhenThenProvenance
03The caller lacks reversal authority.Submit reversal.Authorization refuses it.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: refuses the reverse to a user without accounting.reconciliation-batches.reverse with 403

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