Skip to content

CAP-ACC-REC-008Prepare a payout explanation from matching evidence

Markdown

CAP-ACC-REC-008

Prepare a payout explanation from matching evidence

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

The Formal Contract

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

Outcomes
An active explanation owns each payout exclusively.Candidate reasons support evidence-led selection.Other draft holdings remain visible separately.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: matching by evidence (suggested / all, claims, dismissals, releases))services-accounting:docs/reconciliation/architecture.md#11.2 Tiers (Andrew's Decision 1, 2026-10-16)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U2, U3)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-06, INV-13)

Controls

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

Permissions

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

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Creation links one to fifty nonvoided payouts from one merchant, rejects any already actively held payout and replays the same reconciliation under its request key.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-13, INV-19)
validationapi, service, databasetest
02must prove
Confirmed
Concurrent attempts to reconcile one payout produce one active holder, and the loser receives that reconciliation and its preparer.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-06)
invariantservice, databasetest
03must prove
Confirmed
A created reconciliation is open and numbered, retains its creator as preparer, links the payouts at their net amounts and starts with their negative total as its difference.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U7: difference is net reconciled minus payout)
lifecycleservice, databasetest
04must prove
Confirmed
Matching considers unresolved eligible items in the reconciliation’s unit, merchant and currency, separates items held by another open draft and hides conflicting processor payout references unless searched.
calculationservicetest
05must prove
Confirmed
Candidate strength follows payout reference, processor line, authoritative settlement grouping, expected-day correlation since the prior deposit or a five-business-day fallback, then weak manual suggestion, with reasons retained.
origin: services-accounting:docs/reconciliation/architecture.md#11.2 Tiers (Andrew's Decision 1, 2026-10-16)
calculationservicetest
services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected after the previous deposit and before this one; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate the processor reports paid in this payout; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate settled in a processor batch with an item claimed by payout reference; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected 4 business days before the deposit, with no previous payout; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected on the sixth business day before the deposit, with no previous payout; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate the same whatever amount it carries; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 4: suggests by date alone, never a combination of amounts that adds up to the deposit; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0595.spec.ts#ACT-ACC-0595
06must prove
Confirmed
Matching does not seek combinations of amounts that equal the deposit; amounts serve display and search only.
origin: services-accounting:docs/reconciliation/brief.md#Matching engine (Andrew’s product brief, 2026-10-15)
policyservicetest
services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate the same whatever amount it carries; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate the processor reports paid in this payout; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate settled in a processor batch with an item claimed by payout reference; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected after the previous deposit and before this one; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected 4 business days before the deposit, with no previous payout; services-accounting:modules/reconciliation/tests/unit/rules/match-ranking.spec.js#ranks a candidate expected on the sixth business day before the deposit, with no previous payout; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 4: suggests by date alone, never a combination of amounts that adds up to the deposit; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0595.spec.ts#ACT-ACC-0595
07must prove
Confirmed
Suggested results include undismissed ranks one through four, while all results add weaker and dismissed rows; the default fourteen-day-before and three-day-after window extends for an older previous deposit and supports explicit widening.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope)
policyservicetest
08must prove
Confirmed
Dismissal belongs to this reconciliation, optionally records a reason, leaves version and totals alone, is repeat-safe and can be undone while open.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope)
policyservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#leaves the batch’s version and totals as they were; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#answers the dismissal as written; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#answers a second dismissal of the item with the first; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#records no event for the second dismissal; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#refuses another merchant account’s item with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#refuses a dismissal in a batch that is not open with 409 batch-not-open; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-dismissals.integration.spec.js#refuses a second undo with 404; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-dismissals.table.integration.spec.js#refuses deleting the dismissal of a finalized batch (RHF30); react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0595.spec.ts#ACT-ACC-0595
09must prove
Confirmed
Open reconciliation notes replace or clear up to four thousand characters using the saved version; sealed reconciliations reject that change.
validationapi, servicetest
10must prove
Confirmed
The workspace separates manual entries from matched items grouped by operational batch and provides chronological activity.
origin: services-accounting:docs/reconciliation/brief.md#Three core concepts (Andrew’s product brief, 2026-10-15)
policyservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-workspaces.queries.integration.spec.js#groups the active claims by operational batch with their count and amount, the claims without one last; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-workspaces.queries.integration.spec.js#answers every event oldest first with every mapped property, and no cursor after the last; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#lists the operational batch the remaining claim came from; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#lists every event of the batch, oldest first
11must prove
Confirmed
Create, read and update permissions separately govern opening, inspection and notes or dismissal, with no write actions for readers and no cross-workspace reads.
permissionapitest
services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#refuses the reader a create with 403; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#lets a principal with the read key alone read the batch; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#offers the reader no action; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#answers 404 for tenant A’s batch in tenant B; services-accounting:tests/unit/reconciliation-matching-routes.spec.ts#serves the create under accounting.reconciliation-batches.create; services-accounting:tests/unit/reconciliation-matching-routes.spec.ts#serves every command on an open batch under accounting.reconciliation-batches.update; services-accounting:tests/unit/reconciliation-matching-routes.spec.ts#serves the candidates, the source batches and the history under accounting.reconciliation-batches.read
12
Confirmed
The console begins reconciliation from a payout and retrieves the all-candidates view before applying suggestion filters locally.
policyconsoleobserved

Scenarios

IdGivenWhenThenProvenance
01Forty-two captures and a refund fall within the fallback window before the sample deposit.Inspect suggested candidates.Their expected-day evidence places them in the correlation suggestions.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 4: suggests the 42 captures and the refund tier 4, within 5 business days before the deposit (no previous payout)
02The gift is expected after the deposit day.Inspect all candidates.It remains a weak candidate with the after-deposit reason rather than a suggestion.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 4: never suggests the $500 gift, expected after the deposit, and says so among all candidates

Edge Cases

IdGivenWhenThenProvenance
03Two preparers select the same payout concurrently.Both create an explanation.One wins and the refusal identifies its reconciliation and preparer.test

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.