--- title: Accounting Reconciliation Design Examination examined_at: '2026-10-23' examiner: codex branch: agent/accounting-reconciliation-desi-exam-1 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f rhythm-v2-docs: f65fe08976f1c5df212fd5839c34e405dcb15c3c examined: artifacts: 49 domain_objects: 5 state_models: 5 workflows: 11 service_contracts: 1 screen_contracts: 7 decision_records: 20 responsibility_module_rows: 1 invariants: 44 transitions: 47 workflow_hops: 57 operation_entries: 52 screen_display_rows: 26 source_and_anchor_fields: 231 new_findings: 7 new_open_questions: 0 new_inference_operations: 0 planning_authority: - source: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md:147' decision_ids: - D1 - D2 - D3 - D4 - D5 - D6 - D7 - D8 - D9 - D10 approver: Andrew approved_at: '2026-10-22 10:40 ET' evidence: authoring: - AGENTS.md - 'specs/CONVENTIONS.md §6, §9' - specs/templates/* - briefs/design/accounting-reconciliation.brief.md planning: - specs/accounting/reconciliation/MODULE.md - specs/accounting/reconciliation/planning/features/** - specs/accounting/reconciliation/planning/concepts/** - specs/accounting/reconciliation/planning/capabilities/** - specs/accounting/reconciliation/planning/journeys/** - specs/accounting/reconciliation/planning/acceptance/** - specs/accounting/reconciliation/FINDINGS.md - specs/accounting/reconciliation/ID_REGISTRY.md service: - 'services-accounting:modules/reconciliation/**' - 'services-accounting:aws/accounting.service.ts' - 'services-accounting:aws/accounting.responsibilities.ts' - 'services-accounting:aws/accounting.attention.ts' - 'services-accounting:aws/cdk.json' - 'services-accounting:lib/attention.ts' - 'services-accounting:modules/transactions/services/payments/ports/settlement-items.ts' - 'services-accounting:modules/batches/services/engine/posting-documents.ts' - 'services-accounting:modules/batches/services/rules/reconciliation-entry-rules.ts' - 'services-accounting:modules/batches/services/assignment/default-batch.ts' - 'services-accounting:modules/fiscal-close/services/readiness/**' - 'services-accounting:modules/maintenance/services/scheduled-work/accounting-scheduled-work.ts' - 'services-accounting:docs/reconciliation/architecture.md' - 'services-accounting:docs/migrations/reconciliation/README.md' - 'services-accounting:db/migrations/0063_reconciliation_records.sql' - 'services-accounting:docs/accounting/schedules.md' console: - 'react-console:app/(console)/console/[tenantId]/accounting/reconciliation/**' - 'react-console:components/accounting/reconciliation/**' - 'react-console:lib/accounting/reconciliation/**' - 'react-console:e2e/mock/accounting-reconciliation.mock.spec.ts' unavailable: - services-platform standards cited by the supplied architecture - '@rhythmsoftware/macroservice-attention shared sweep implementation' - shared scheduled queue implementation outside the examined module verification_value_changes: - id: DOM-ACC-REC-004 path: invariants.0.source old: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exceptions_dedupe_uidx new: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exceptions_dedupe_uidx; services-accounting:modules/reconciliation/services/persistence/reconciliation-exceptions.ts:raiseException - id: DOM-ACC-REC-003 path: invariants.11.provenance old: documented new: observed - id: DOM-ACC-REC-003 path: invariants.11.source old: 'services-accounting:docs/reconciliation/architecture.md#9.3 Transaction boundaries (exact)' new: >- services-accounting:modules/reconciliation/services/batch-lifecycle/finalize-batch.ts:finalizeReconciliationBatch - id: DOM-ACC-REC-002 path: invariants.3.enforced_at.0 old: database new: service - id: DOM-ACC-REC-002 path: invariants.3.source old: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_write_once_trigger new: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_write_once_trigger; services-accounting:modules/reconciliation/services/persistence/settlement-item-recordings.ts:markItemEligible - id: SVC-ACC-REC-reconciliation path: operations.3.permission old: accounting.payouts.read (evaluates the payout command keys) new: accounting.payouts.read - id: SVC-ACC-REC-reconciliation path: operations.11.permission old: accounting.reconciliation-batches.read (evaluates the other batch keys) new: accounting.reconciliation-batches.read - id: STATE-ACC-REC-004 path: transitions.11.source old: >- services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem new: >- services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem; services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:splitSettlementItem - id: SCR-ACC-REC-001 path: permission old: 'accounting.application.access, with the reconciliation read keys for the records it loads' new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-001 path: displays.3.source old: Console state; fiscal period from Books new: Browser filters and a calendar-month label derived from the current day - id: SCR-ACC-REC-003 path: permission old: >- accounting.reconciliation-batches.read and accounting.payouts.read; editing needs accounting.reconciliation-batches.update new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-003 path: displays.4.source old: listReconciliationSourceBatches and loaded settlement items new: Browser grouping of loaded settlement items by operational batch - id: SCR-ACC-REC-003 path: displays.5.source old: listReconciliationBatchEvents and listPayoutEvents new: Browser-created creation and finalization entries; history routes are not called - id: SCR-ACC-REC-003 path: displays.6.source old: DOM-ACC-REC-003 reversal new: >- Console adapter retains pending reason but omits completed reversal reason, requester and approver - id: SCR-ACC-REC-006 path: permission old: accounting.reconciliation-exceptions.read (behind accounting.application.access) new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-007 path: permission old: accounting.reconciliation-batches.read (behind accounting.application.access) new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-007 path: displays.2.source old: DOM-ACC-REC-005 clearing lines new: >- Readiness adapter expects aggregate balance and outstanding fields absent from the service response - id: SCR-ACC-REC-007 path: actions.0.operation_id old: 'none: navigation from the finding''s route key' new: 'none: navigation from local finding-code and entity-type mappings' - id: SCR-ACC-REC-002 path: permission old: accounting.payouts.read (behind accounting.application.access) new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-004 path: permission old: accounting.reconciliation-batches.read (behind accounting.application.access) new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants - id: SCR-ACC-REC-005 path: permission old: accounting.settlement-items.read (behind accounting.application.access) new: >- accounting.application.access; shared loading also requires payout, settlement-item, reconciliation and exception read grants added_transition_sources: - artifact: STATE-ACC-REC-003 from: draft to: balanced source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:claimSettlementItems; services-accounting:modules/reconciliation/services/rules/batch-status.ts:displayStatusOf - artifact: STATE-ACC-REC-003 from: balanced to: draft source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:releaseSettlementItems; services-accounting:modules/reconciliation/services/rules/batch-status.ts:displayStatusOf validation: - command: npm ci && npm run check result: passed; zero conformance errors - command: npm test result: 'passed; four tests, zero failures' - command: pinned source and literal anchor audit result: 231 source/anchor fields reviewed; no missing referenced path or checked literal anchor --- # Accounting Reconciliation Design Examination ## Scope and Method The examination checked the complete design against the pinned service and console, then rewrote its narrative and structured explanatory text in OpenAI wording. The reconciliation module row and section of Accounting Responsibilities received the same treatment. Identifiers, ownership references, decision origins, intent and implementation-evidence values remain unchanged except for the verification changes recorded in the metadata. Each invariant, transition, workflow hop and operation was compared with its cited declaration or implementation. Database claims were checked against migrations as well as table declarations; source-symbol existence alone was not treated as proof of enforcement. Screen review followed routes, components, loading, adapters and command dispatch rather than assuming that an available service operation is displayed. The plan’s explicit approval entry supports the existing decision origins even though its final answer table is blank. Approved decisions were cited rather than decided again. Planning artifacts were left unchanged, and implementation disagreements remain findings rather than new product approvals. ## Counts and Coverage | Coverage | Examined | Result | |---|---:|---| | Design artifacts | 49 | Five domain objects, five state models, eleven workflows, one service contract, seven screen contracts and twenty decision records. | | HTTP operations | 45 of 45 | Every reconciliation route operation has a service-contract entry with access, permission and publication metadata. | | In-process functions | 7 of 7 contracted functions | Transaction recording, readiness and posting-source functions are represented in the service contract and responsibility inventory. This count excludes private implementation helpers. | | Physical tables | 18 of 18 | Every reconciliation table is represented by a domain object, including shared supporting evidence, activity and request-key records. Readiness is computed and owns no table. | | Screen routes | 7 of 7 | The seven route surfaces have contracts; payout entry and exception detail controls are covered within their parent surfaces. | | Invariant rows | 44 | Enforcement location and provenance were checked; service-only and database protections are distinguished. | | Transition rows | 47 | Five local models describe stored and derived state; immediate balance and return-to-draft transitions were added. | | Workflow hops | 57 | All eleven workflows were checked against their sources, commit boundaries and failure behavior. | | Display rows | 26 | Browser-derived displays and omitted service fields are identified. | | Owned durable state machines | 0 | Local lifecycles are service and database logic. Batch posting and Close execution belong to adjacent modules. | | Owned queues | 0 | Daily work uses shared Accounting schedule dispatch; its three work kinds and attention repair have workflow coverage. Shared queue retries are documented dependencies, not independently verified module guarantees. | | Inference calls and operations | 0 | No examined module call invokes a model task. All nineteen service, workflow and screen artifacts carry empty inference lists. | | New findings | 7 | Two high, four medium and one low; existing product questions remain open. | ## Changes by Artifact Every row below received a complete final-text pass. The change column records verification corrections or states that the evidence already supported the design. Evidence values changed during verification are listed individually in the metadata, including prior and replacement values. | Artifact | Verification result and change | |---|---| | `ADR-ACC-REC-001` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-002` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-003` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-004` | Qualified universal lock and expected-version statements. | | `ADR-ACC-REC-005` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-006` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-007` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-008` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-009` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-010` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-011` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-012` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-013` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-014` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-015` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-016` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-017` | Verified the cited origin, implemented choice and alternatives; no evidence correction was needed. | | `ADR-ACC-REC-018` | Limited audited refusal claims to the explicit guard paths. | | `ADR-ACC-REC-019` | Recorded dollar-cent display and the empty accounting plan’s exponent-check exception. | | `ADR-ACC-REC-020` | Recorded unversioned dismissals and the limits of browser command sequences. | | `DOM-ACC-REC-001` | Corrected historical holdings cardinality and the evidence-attachment version exception. | | `DOM-ACC-REC-002` | Made processor optional; separated service-protected eligibility dates from database-protected identity and references. | | `DOM-ACC-REC-003` | Recorded finalization counter repair and the dismissal version exception. | | `DOM-ACC-REC-004` | Distinguished database deduplication from service suppression of accepted concerns; qualified attention and supplemental command versions. | | `DOM-ACC-REC-005` | Removed the unsupported promise that a caller transaction freezes all assessed records. | | `SCR-ACC-REC-001` | Described shared read requirements, browser-computed summaries and the calendar-month period label. | | `SCR-ACC-REC-002` | Described shared read requirements and dollar-cent input and display. | | `SCR-ACC-REC-003` | Corrected source-batch and history sources, completed reversal omissions, partial saving and shared read requirements. | | `SCR-ACC-REC-004` | Described shared read requirements and the limits of loaded reconciliation details. | | `SCR-ACC-REC-005` | Described shared read requirements and the outstanding-list action baseline. | | `SCR-ACC-REC-006` | Described shared read requirements and the actual note, acceptance and investigation controls. | | `SCR-ACC-REC-007` | Replaced server-directed navigation with local linking and exposed missing clearing, currency and availability fields. | | `STATE-ACC-REC-001` | Limited lock and version claims to commands that actually use those mechanisms. | | `STATE-ACC-REC-002` | Included the accounting-date reset when verified bank evidence becomes a mismatch. | | `STATE-ACC-REC-003` | Made the claim requirement explicit, added immediate balance and return-to-draft edges, and corrected reversal dating. | | `STATE-ACC-REC-004` | Added split-command evidence for the resolution transition. | | `STATE-ACC-REC-005` | Recorded unversioned withdrawal and restoration of the underlying investigating state. | | `SVC-ACC-REC-reconciliation` | Corrected two read permissions; aligned internal functions, integration semantics, default-batch ownership and failure limits. | | `WF-ACC-REC-001` | Verified caller-owned settlement recording and transaction rollback; no evidence correction was needed. | | `WF-ACC-REC-002` | Replaced global serialization with maximum-plus-one allocation, uniqueness and five savepoint attempts. | | `WF-ACC-REC-003` | Recorded unversioned dismissal and stale browser planning after a failed reload. | | `WF-ACC-REC-004` | Replaced an event seam with later in-process posting-source reads. | | `WF-ACC-REC-005` | Separated the open-day helper from the operational batch date used for mirror requests. | | `WF-ACC-REC-006` | Removed an unsupported reconciliation event-publication seam. | | `WF-ACC-REC-007` | Qualified append-only storage and described synchronous source loading by the posting engine. | | `WF-ACC-REC-008` | Separated purge transactions and qualified repeat detection, dispatch and unavailable queue implementation. | | `WF-ACC-REC-009` | Distinguished audience registration from delivery; retained the disabled switch and sweep overlap limits. | | `WF-ACC-REC-010` | Removed the expected-version claim for acceptance withdrawal. | | `WF-ACC-REC-011` | Qualified close-time concurrency, selected-batch dating, the current-day preview and local console navigation. | ## Responsibility and Registry Changes The reconciliation responsibility inventory retains its five owned objects and fifty-two service entries. Attention items, local activity and scheduled occurrences now match the service contract’s event inventory, and default operational batch selection is delegated to Batch Management. Its prose points to invariant homes and describes the important implementation limits without restating their rules. Seven finding identifiers were reserved before use. The existing numbering finding was corrected to describe collision retries rather than universal serialization, and the findings table remains continuous. The module’s catalog status now records design examination; individual artifact approval states were not promoted. ## Open Disagreements | Finding | Unresolved issue | Required follow-through | |---|---|---| | `FND-ACC-REC-037` | Currency is discarded and all console money uses dollar cents. | Decide supported currencies and make input, display and adapters agree with account currency. | | `FND-ACC-REC-038` | Close-time readiness does not freeze every assessed financial or investigation record. | Establish the required close consistency boundary and identify the commands that must join it. | | `FND-ACC-REC-039` | Readiness navigation, clearing fields, currency and payment availability are lost or mismatched in the console. | Align the response and adapter before relying on the screen for controller review. | | `FND-ACC-REC-040` | Supplemental commands lack the version protection described by the draft. | Decide which commands require version checks and how partially saved drafts recover. | | `FND-ACC-REC-041` | Counter repair and service-only eligibility-date protection differ from the architectural account. | Reconcile the approved planning language with the required enforcement and repair policy. | | `FND-ACC-REC-042` | Source-batch and activity views are browser constructions, with completed reversal details omitted. | Decide the history and correction evidence the workspace must show. | | `FND-ACC-REC-043` | Platform compliance and disabled-attention schedule bootstrap cannot be established from the supplied source. | Inspect the shared implementation and standards before claiming production detection and delivery guarantees. | Earlier findings still govern bank verification, late-posting review, duplicate acknowledgement, approval contributors, attention enablement and partial draft saving. The five existing product questions were not answered by this examination. The approved planning rules remain their current homes; resolving implementation disagreement requires an explicit product or implementation decision. ## Validation and Commit Discipline Dependency installation, corpus conformance and the corpus test suite passed: zero conformance errors and four passing tests. Literal path and anchor review found no missing checked reference. These checks validate the corpus and its references; they do not establish runtime recovery of unavailable shared services. Verification corrections were committed before final-text rewrites, and each design artifact has its own rewrite commit. The additional derived-state coverage was also followed by a separate final-text commit. Work stayed on the task branch in a worktree; no source implementation, reader, planning artifact or publication workflow was changed, and no push or deployment was performed. ## Verdict for Andrew The examined design is a faithful, qualified account of the module at the pinned commits, with implementation disagreements retained as findings rather than converted into approvals. Its weakest areas are controller-facing evidence in the console and the consistency and production scheduling guarantees around period close. Before implementation preparation starts, decide the currency scope, close consistency boundary, required investigation and correction evidence, and the resolution of the existing bank-verification, late-review, attention and draft-saving gaps.