--- id: SVC-ACC-REC-reconciliation title: Reconciliation Service Module product_area: accounting module: reconciliation repository: services-accounting source_module: modules/reconciliation revision: 2 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-ACC-REC-001 - DOM-ACC-REC-002 - DOM-ACC-REC-003 - DOM-ACC-REC-004 - DOM-ACC-REC-005 does_not_own: - >- Books controls merchant and bank configuration, account purposes, independence settings and fiscal calendar records. - >- Transactions owns causing documents and invokes settlement recording through its port; Batch Management implements the current default-batch selection. - >- Batch Management owns operational batches, posting generations and ledger execution. - 'Close owns period completion, recovery and retained closing evidence.' - >- Platform supplies security evaluation, attention infrastructure, record assets, metadata and export execution. - >- Request keys are shared Accounting infrastructure hosted here, rather than ownership of other modules’ commands. operations: - operation_id: listPayouts intent: >- Find payouts in accounting-date order using financial context, reference, verification and lifecycle filters. access: console permission: accounting.payouts.read realises: - CAP-ACC-REC-004 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: createPayout intent: >- Create a manually reported deposit with duplicate checks and a retained request key. access: console permission: accounting.payouts.create realises: - CAP-ACC-REC-001 published_to_submissions: >- not published: finance staff enter statement deposits; processor imports are deferred. - operation_id: checkPayoutDuplicates intent: >- Check existing deposits for hard or possible duplication without creating a record. access: console permission: accounting.payouts.read realises: - CAP-ACC-REC-001 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: getPayout intent: >- Inspect payout facts, evidence, active holder and caller-eligible commands. access: console permission: accounting.payouts.read realises: - CAP-ACC-REC-004 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: updatePayout intent: >- Replace editable payout values at the read version and update any open holder’s amount. access: console permission: accounting.payouts.update realises: - CAP-ACC-REC-002 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: voidPayout intent: Retain cancellation of an unheld payout with its reason and request key. access: console permission: accounting.payouts.delete realises: - CAP-ACC-REC-002 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: verifyPayoutBank intent: >- Retain bank evidence and an agreement or mismatch outcome under a request key. access: console permission: accounting.payouts.verify realises: - CAP-ACC-REC-003 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: attachPayoutEvidence intent: >- Add a record-asset document while the payout is live and not approval-sealed. access: console permission: accounting.payouts.update realises: - CAP-ACC-REC-002 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: listPayoutEvents intent: Read payout activity in chronological pages. access: console permission: accounting.payouts.read realises: - CAP-ACC-REC-004 - CAP-ACC-REC-020 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: listReconciliationBatches intent: >- Browse numbered explanations with payout details and unit, merchant and state filters. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-019 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: createReconciliationBatch intent: Create an open explanation holding one to fifty compatible free payouts. access: console permission: accounting.reconciliation-batches.create realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: getReconciliationBatch intent: >- Inspect holdings, manual effects, balance and allowed or withheld commands. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: updateReconciliationBatchNotes intent: Replace or clear notes on current open preparation. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: listReconciliationCandidates intent: Read ranked compatible effects in the requested candidate view. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: claimReconciliationItems intent: Take whole-effect claims for an open explanation at its current version. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-009 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: releaseReconciliationItems intent: Release selected open-preparation holdings and preserve release history. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-009 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: acceptAuthoritativeCandidates intent: >- Claim currently authoritative processor-reference candidates at the expected version. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-009 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: addReconciliationManualItem intent: >- Create and claim a documented manual fee, reserve or adjustment with a request key. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-010 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: removeReconciliationManualItem intent: Withdraw a manual effect created in current open preparation. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-010 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: dismissReconciliationItem intent: >- Set a compatible suggestion aside for this open explanation without changing its version. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: undismissReconciliationItem intent: Remove an open explanation’s dismissal without changing its version. access: console permission: accounting.reconciliation-batches.update realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: listReconciliationSourceBatches intent: Read source operational batches with held-effect counts and amounts. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-008 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: listReconciliationBatchEvents intent: Read chronological activity for an explanation. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-008 - CAP-ACC-REC-020 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: finalizeReconciliationBatch intent: >- Approve exact balanced holdings and atomically create the required accounting requests. access: console permission: accounting.reconciliation-batches.finalize realises: - CAP-ACC-REC-011 - CAP-ACC-REC-014 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: voidReconciliationBatch intent: Cancel open preparation with a reason and release its holdings. access: console permission: accounting.reconciliation-batches.delete realises: - CAP-ACC-REC-012 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: reverseReconciliationBatch intent: >- Reverse approval in an open document period or retain a closed-period request for independent approval. access: console permission: accounting.reconciliation-batches.reverse realises: - CAP-ACC-REC-013 - CAP-ACC-REC-014 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: approveReconciliationBatchReversal intent: Complete a pending reversal as a different authorized actor. access: console permission: accounting.reconciliation-batches.reverse realises: - CAP-ACC-REC-013 - CAP-ACC-REC-014 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: getReconciliationReadiness intent: >- Evaluate reconciliation blockers, warnings and money positions for a period and state day. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-018 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: listSettlementItems intent: 'Browse effects with requested-day standing, age and holding details.' access: console permission: accounting.settlement-items.read realises: - CAP-ACC-REC-006 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: summarizeSettlementItems intent: 'Aggregate requested-day effects by standing, processor and currency.' access: console permission: accounting.settlement-items.read realises: - CAP-ACC-REC-006 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: getSettlementItem intent: >- Inspect effect evidence, claims, resolution, split parts and possible payout links. access: console permission: accounting.settlement-items.read realises: - CAP-ACC-REC-006 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: splitSettlementItem intent: Divide an unheld unresolved effect into exact parts under a request key. access: console permission: accounting.settlement-items.resolve realises: - CAP-ACC-REC-007 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: resolveSettlementItem intent: >- Permanently resolve an unheld effect and create accounting requests when writing it off. access: console permission: accounting.settlement-items.resolve realises: - CAP-ACC-REC-007 - CAP-ACC-REC-014 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: listReconciliationExceptions intent: >- Find investigation records by state, severity, kind, scope, owner or subject. access: console permission: accounting.reconciliation-exceptions.read realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: createReconciliationException intent: >- Raise a documented manual concern over compatible local financial subjects. access: console permission: accounting.reconciliation-exceptions.update realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: getReconciliationException intent: 'Inspect a concern’s subjects, checklist, notes and retained activity.' access: console permission: accounting.reconciliation-exceptions.read realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: updateReconciliationException intent: >- Assign ownership or move current active work between open and investigating. access: console permission: accounting.reconciliation-exceptions.update realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: addReconciliationExceptionNote intent: >- Append a retained investigation note without an expected-version requirement. access: console permission: accounting.reconciliation-exceptions.update realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: setReconciliationExceptionStep intent: Change checklist completion at the current version with actor and time. access: console permission: accounting.reconciliation-exceptions.update realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: resolveReconciliationException intent: >- Conclude active work in writing after checking any overdue condition on the judged day. access: console permission: accounting.reconciliation-exceptions.update realises: - CAP-ACC-REC-015 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: acceptReconciliationException intent: >- Accept a warning or request blocker acceptance with conclusion, key and current version. access: console permission: accounting.reconciliation-exceptions.accept realises: - CAP-ACC-REC-016 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: approveReconciliationExceptionAcceptance intent: Grant a pending blocker acceptance as an independent actor. access: console permission: accounting.reconciliation-exceptions.accept realises: - CAP-ACC-REC-016 - CAP-ACC-REC-020 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: withdrawReconciliationExceptionAcceptance intent: >- Withdraw the caller’s current pending acceptance under a key without an expected version. access: console permission: accounting.reconciliation-exceptions.accept realises: - CAP-ACC-REC-016 published_to_submissions: >- not published: authorized finance preparation, correction or approval with no declared intake binding. - operation_id: runReconciliationScheduledWork intent: >- Invoke overdue detection, drift checking or cross-workspace key cleanup using operational acceptance authority. access: console permission: accounting.reconciliation-exceptions.accept realises: - CAP-ACC-REC-017 published_to_submissions: >- not published: operational execution trigger with no business intake binding. - operation_id: getReconciliationOverview intent: >- Read currency-separated reconciliation stages, recent deposits and attention counts. access: console permission: accounting.reconciliation-batches.read realises: - CAP-ACC-REC-019 published_to_submissions: >- not published: staff inspection or computed review with no declared intake binding. - operation_id: recordSettlementItem intent: >- Record or reuse a deterministic money effect inside the causing transaction. access: internal permission: >- none: an in-process call that runs in the caller's authorized transaction and refuses without one realises: - CAP-ACC-REC-005 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: markSettlementItemEligible intent: >- Establish a cleared check’s eligibility and expected arrival once in the caller transaction. access: internal permission: 'none: an in-process call inside the caller''s transaction' realises: - CAP-ACC-REC-005 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: assessReconciliationReadiness intent: >- Compute period reconciliation checks inside an existing caller transaction. access: internal permission: 'none: an in-process call inside the caller''s transaction' realises: - CAP-ACC-REC-018 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: assertPeriodWritable intent: >- Share-lock relevant fiscal periods and report a permissible day and late flag. access: internal permission: 'none: an in-process call inside the caller''s transaction' realises: - CAP-ACC-REC-011 - CAP-ACC-REC-018 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: listPostingsInBatches intent: >- Supply the operational posting engine with retained requests from its batches. access: internal permission: 'none: an in-process read inside Batch Management''s posting transaction' realises: - CAP-ACC-REC-014 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: listPendingPostings intent: Read bounded oldest pending requests for an operational batch. access: internal permission: 'none: an in-process read' realises: - CAP-ACC-REC-014 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. - operation_id: loadPosting intent: Inspect one accounting request and its ordered lines. access: internal permission: 'none: an in-process read' realises: - CAP-ACC-REC-014 published_to_submissions: >- not published: internal Accounting function with no declared intake binding. events: - name: accounting.reconciliation_blockers attention item direction: produced when: >- Blocker changes and enabled repair passes invoke attention publication or resolution. payload_summary: >- Exception identity and title with unit scope, responsibility audience, condition facts and conclusion outcome. - name: reconciliation audit event direction: produced when: >- Committed financial commands and eligible audited refusals retain module-local history. payload_summary: >- Record, activity kind, actor, source, time, reason, key and bounded detail; this history is not an interservice event stream. - name: >- accounting.reconciliation.overdue-sweep, drift-check and idempotency-purge occurrences direction: consumed when: The shared scheduler invokes a registered daily reconciliation work kind. payload_summary: >- Work kind, workspace subject and occurrence instant used to calculate the local work day. jobs: - >- An hourly attention handler bootstraps missing daily schedules and repairs enabled blocker attention. - >- Daily local cleanup at 03:00 removes expired request-key state across workspaces. - >- Daily local drift work at 05:30 compares retained counters with financial holdings. - >- Daily local overdue work at 06:00 raises and clears missing-money and stale-payout concerns with bounded scans. integrations: - system: Transactions direction: inbound contract: >- The settlement port records processor effects and eligibility within the document caller’s transaction. - system: Batch Management direction: outbound contract: >- Operational batch posting reads immutable requests as an in-process source and determines posted status from unreversed entries. - system: Month-End Close direction: inbound contract: >- Close evaluates readiness in its caller transaction; period coordination belongs to its closing flow. - system: Books direction: outbound contract: >- Reconciliation reads financial configuration and shares fiscal-period locks where posting requires them. - system: Platform attention and responsibilities direction: outbound contract: >- Enabled attention publication and resolution join exception writes; responsibility metadata determines the intended audience. - system: Platform security direction: outbound contract: >- Sixteen permission keys and two built-in financial policies provide workspace-wide route authority. - system: Platform exports direction: outbound contract: >- The export dataset retains eight record categories but omits operational keys and integration references. - system: Platform metadata direction: outbound contract: >- Read-only exception registration supplies the object identity used by attention. - system: Platform record assets direction: outbound contract: >- Evidence uses confidential record-asset references; copyable export addresses are still missing. consistency: - rule: Caller-recorded settlement effects share the document transaction. kind: transactional compensation: Caller rollback removes the settlement effect with its document change. - rule: >- Each service mutation commits its applicable record, counters, version and activity together; keyed answers and enabled attention join where that command uses them. kind: transactional compensation: >- Business rollback removes applicable writes; uncertain key completion can retain a claim until expiry. - rule: >- Finalization, reversal completion and write-off retain their accounting requests with the causing mutation. kind: transactional compensation: >- Reversal supplies opposite requests; missing accepting batch aborts without an audited request-write failure. - rule: Operational posting later supplies the requests’ ledger entries. kind: eventual compensation: >- Unposting removes current ledger completion; readiness exposes pending requests. - rule: Scheduled concerns can lag source financial facts. kind: eventual compensation: >- A later pass can update concerns; readiness independently classifies overdue money. - rule: >- Enabled source attention joins blocker writes; hourly repair uses separate page transactions. kind: eventual compensation: >- Later enabled repair republishes active blockers and clears stale items; overlap still requires concurrency review. - rule: >- Workspace draft saving applies a series of independently committed commands. kind: eventual compensation: >- No compensation reverses earlier saved steps; reload can reveal the partial result. evidence: - >- services-accounting at f47cb263: modules/reconciliation/aws/api/*.routes.ts, *.schemas.ts; aws/reconciliation.module.ts; aws/lambda/RECONCILIATION_ATTENTION_SWEEP.ts; attention/reconciliation-blockers.attention.ts; metadata/reconciliation-exceptions.object.ts; export/reconciliation.dataset.ts; services/**; aws/accounting.service.ts (permission groups and ReconciliationBuiltInPolicies); modules/maintenance/services/scheduled-work/accounting-scheduled-work.ts; modules/transactions/services/payments/ports/settlement-items.ts; modules/batches/services/engine/posting-documents.ts; modules/fiscal-close/services/readiness/*. - >- services-accounting: docs/reconciliation/architecture.md §9, §10, §16, §18, §24a; docs/milestones/plans/ACCT-M8-plan.md. - >- No route or registration in the module declares a Submissions binding. The Platform submission-compatible operations standard was not readable from this job and is cited as the CRM design records it. controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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-SEC-001, TC-SEC-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-007, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-006, TC-AVL-001, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-AI-005, TC-PRV-001, TC-PRV-002] --- # Reconciliation Service Module ## What This Service Is For Reconciliation explains processor deposits and outstanding arrivals within Accounting. It owns payout and preparation work, retains investigations and supplies Close with financial readiness. ## Boundary The service owns the five domain-object designs and their supporting records. Books supplies configuration, Transactions supplies source effects, Batch Management executes accounting, and Close decides period completion; Platform provides shared facilities. ## Operations in Words Staff record and verify payouts, prepare holdings and deductions, approve or reverse explanations, and investigate outstanding money. Separate read operations support summaries and readiness. Internal callers use transaction-bound functions for recording, posting source reads and close assessment. ## Events and Jobs Module-local audit records, attention items and scheduled occurrences have different delivery semantics. There is no reconciliation lifecycle event stream or owned durable state machine; shared Accounting execution dispatches the daily work. No examined code calls a model, so inference lists remain empty. ## Consistency Guarantees The structured consistency rows define applicable commit boundaries and their limits. Atomic approval requests can remain unposted, console saving can partially commit, and attention can be disabled. Workspace records use forced row-level isolation; global timing seeds are read-only reference data. Code and migration evidence support these mechanisms, but the unavailable Platform standards do not establish independently verified cross-platform compliance.