--- id: WF-ACC-REC-008 title: Run the daily reconciliation checks trigger: >- Daily local schedules or an authorized on-demand command invoke detection and request-key cleanup. product_area: accounting module: reconciliation revision: 3 status: draft design_intent: confirmed origin: >- ACCT-M8 plan D9 (the daily sweep scheduled per workspace through the Accounting scheduler), approved by Andrew 2026-10-22; services-accounting docs/reconciliation/architecture.md §24a (DEP-ACC-604) implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 implements: - CAP-ACC-REC-017 - CAP-ACC-REC-015 moves: - STATE-ACC-REC-005 crosses: - SVC-ACC-REC-reconciliation idempotency: >- Scheduler occurrence identity and detector condition keys limit duplicates. Further runs may process additional rows or reopen resolved work; a reconciliation job has no retained whole-run answer. concurrency: >- Detection runs transactionally per invocation. Purge uses package-controlled batches and an advisory lock; queue retry and worker limits are documented but not independently inspected. hops: - 'n': 1 actor_or_service: Hourly reconciliation attention pass action: >- During the hourly handler, create missing daily schedules and preserve existing schedule edits. anchor: >- services-accounting:modules/reconciliation/services/scheduled/reconciliation-schedules.ts:ensureReconciliationSchedules seam: schedule on_failure: >- A failed workspace bootstrap is handled by the shared sweep wrapper, whose full behavior remains unverified. left_inconsistent: Missing schedules can leave that workspace without daily work. observer: >- Logs are the available local evidence; missing-schedule reporting is absent. provenance: observed source: >- services-accounting:modules/reconciliation/aws/lambda/RECONCILIATION_ATTENTION_SWEEP.ts:handler - 'n': 2 actor_or_service: Accounting schedule dispatcher action: Dispatch due schedule occurrences to shared Accounting execution. anchor: >- services-accounting:docs/accounting/schedules.md#The dispatcher and the consumer seam: schedule on_failure: Documented dispatch recovery republishes queued runs. left_inconsistent: A queued occurrence can wait for later dispatch. observer: Scheduler history and monitoring are documented observers. provenance: documented source: >- services-accounting:docs/accounting/schedules.md#The dispatcher and the consumer - 'n': 3 actor_or_service: Accounting schedule consumer action: Run the registered work kind in the occurrence’s workspace and local date. anchor: >- services-accounting:modules/reconciliation/services/scheduled/reconciliation-scheduled-work.ts seam: queue on_failure: >- The documented consumer retries and dead-letters failures and can pause repeated failures. left_inconsistent: Paused execution leaves detection stale until restored. observer: Scheduler history and alarms provide the documented signals. provenance: documented source: >- services-accounting:docs/accounting/schedules.md#The dispatcher and the consumer - 'n': 4 actor_or_service: Overdue sweep action: >- Raise overdue and stale-payout concerns, then clear resolved or finalized subjects, with five hundred rows per step. anchor: >- services-accounting:modules/reconciliation/services/scheduled/overdue-sweep.ts:sweepOverdueSettlement seam: sync on_failure: Detection transaction failure rolls back that run. left_inconsistent: >- Concerns can lag financial facts; readiness separately computes overdue items. observer: Run outcomes and detection metrics report work and limits. provenance: observed source: >- services-accounting:modules/reconciliation/services/scheduled/overdue-sweep.ts:sweepOverdueSettlement - 'n': 5 actor_or_service: Drift check action: >- Compare every open and approved explanation’s counters with holdings and raise drift concerns without repair. anchor: >- services-accounting:modules/reconciliation/services/scheduled/drift-check.ts:checkTotalsDrift seam: sync on_failure: A failed check does not commit its new concerns. left_inconsistent: Drift can remain unreported until another successful check. observer: The drift metric includes zero and feeds integrity monitoring. provenance: observed source: >- services-accounting:modules/reconciliation/services/scheduled/drift-check.ts:checkTotalsDrift - 'n': 6 actor_or_service: Request-key purge action: >- Purge expired retained answers and abandoned claims across workspaces through the shared package. anchor: >- services-accounting:modules/reconciliation/services/persistence/idempotency-keys.ts:purgeIdempotencyKeys seam: sync on_failure: >- Failure is reported by the caller; later purge invocations can resume remaining cleanup. left_inconsistent: Expired keys can remain until cleanup succeeds. observer: The purge metric reports removed keys. provenance: observed source: >- services-accounting:modules/reconciliation/services/scheduled/reconciliation-jobs.ts:runReconciliationJob branches: - >- On-demand work uses acceptance authority; a unit filter limits only newly overdue settlement detection. waits: - New missing-money concerns normally wait until the daily sweep. evidence: - >- services-accounting at f47cb263: modules/reconciliation/services/scheduled/*.ts; aws/lambda/RECONCILIATION_ATTENTION_SWEEP.ts; services/persistence/unreconciled-payouts.ts, settlement-items.ts, idempotency-keys.ts; modules/maintenance/services/scheduled-work/accounting-scheduled-work.ts; docs/accounting/schedules.md; tests/integration/services/scheduled/reconciliation-scheduled-work.integration.spec.js, reconciliation-schedules.integration.spec.js. 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-DAT-001, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-001, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005] --- # Run the daily reconciliation checks ## What It Does Daily work raises missing-money and integrity concerns and removes obsolete request-key state. Local schedules are bootstrapped from the attention handler rather than from a dedicated schedule owner. ## The Flow ```mermaid sequenceDiagram participant H as Hourly attention pass participant S as Schedule dispatcher participant Q as Schedule queue and consumer participant J as Reconciliation job participant D as Accounting database H->>D: create missing daily schedules S->>D: claim due schedules, insert runs S->>Q: one message per run Q->>J: run the work kind for the local day J->>D: raise and clear blockers in one transaction J-->>Q: outcome, metric ``` ## When Something Fails Detection failure leaves concerns stale, although readiness still computes overdue positions. Bounded scans can revisit the same rows, and missing or paused schedules have no automatic owner repair. Shared-wrapper behavior with attention disabled remains unknown. ## Open Design Questions Schedule bootstrap, pause recovery, bounded scan continuation and operational authority need decisions before relying on daily coverage.