--- id: DOM-ACC-REC-004 title: Reconciliation Problem realises: CON-ACC-REC-004 product_area: accounting module: reconciliation revision: 3 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-ACC-REC-reconciliation readable_by: [] lifecycle: STATE-ACC-REC-005 custom_fields: none identity: >- The service assigns a time-ordered identity and the next workspace number. A condition key reuses an existing detected problem while it is open, investigating or accepted. attributes: - name: number kind: number required: true computed: true notes: Creation allocates the next module-local number. - name: kind kind: enum required: true computed: false notes: >- Current detectors cover overdue money, unreconciled payouts, bank disagreement and drift; staff can raise manual concerns. - name: severity kind: enum required: true computed: false notes: Blockers and warnings have different effects on period readiness. - name: status kind: enum required: true computed: false notes: >- Status records whether the concern is open, being investigated, resolved or accepted. - name: business unit kind: reference required: true computed: false notes: The business unit scopes reconciliation responsibility attention. - name: subjects kind: collection required: true computed: false notes: >- A primary subject and up to fifty subjects identify local payouts, items or reconciliations with navigation metadata. - name: title and description kind: text required: true computed: false notes: Detector or staff text names and explains the concern. - name: amount kind: money required: false computed: false notes: >- Optional exposure includes both amount and a currency available to the unit. - name: period anchor date kind: date required: false computed: false notes: An optional anchor day associates the concern with a fiscal period. - name: condition key kind: text required: true computed: false notes: >- The private condition key identifies detector work; each manual concern uses its own key. - name: owner kind: reference required: false computed: false notes: An optional workspace user can own the investigation. - name: steps kind: collection required: false computed: false notes: Up to twenty checklist positions retain completion actor and time. - name: notes kind: collection required: false computed: false notes: >- Up to two hundred append-only notes accept four thousand characters apiece. - name: resolution kind: collection required: false computed: false notes: 'Closing retains the written conclusion, actor and time.' - name: acceptance request kind: collection required: false computed: false notes: >- Blocker acceptance retains a complete request and, on approval, the independent approver. - name: history kind: computed required: false computed: true notes: Retained activity includes acceptance command refusals. - name: version kind: number required: true computed: true notes: >- Most edits compare versions; note addition and acceptance withdrawal do not accept an expected version. relationships: - to: DOM-ACC-REC-001 cardinality: many-to-many through subjects ownership: The concern owns the references naming its subjects. cross_service: false - to: DOM-ACC-REC-002 cardinality: many-to-many through subjects ownership: The concern owns the references naming its subjects. cross_service: false - to: DOM-ACC-REC-003 cardinality: many-to-many through subjects ownership: >- The explanation owns its holding references and preserves released history. cross_service: false - to: DOM-ACC-REC-005 cardinality: many-to-one per period ownership: Assessment reads the relationship without owning the underlying record. cross_service: false invariants: - id: INV-DOM-ACC-REC-004-01 statement: >- The raising service suppresses open, investigating and accepted conditions; the unique index prevents duplicate active open or investigating conditions. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exceptions_dedupe_uidx; services-accounting:modules/reconciliation/services/persistence/reconciliation-exceptions.ts:raiseException - id: INV-DOM-ACC-REC-004-02 statement: Resolution and acceptance require a written conclusion. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exceptions_resolution_check - id: INV-DOM-ACC-REC-004-03 statement: >- Staff move active concerns between open and investigation or close them; reopening is reserved to detection. enforced_at: - service provenance: observed source: >- services-accounting:modules/reconciliation/services/rules/transitions.ts:EXCEPTION_TRANSITIONS - id: INV-DOM-ACC-REC-004-04 statement: >- Accepted blockers retain a requester and an approver distinct from requester and resolver; warnings have no approver. enforced_at: - service - database provenance: documented source: 'services-accounting:docs/reconciliation/architecture.md#13.2 Workflow' - id: INV-DOM-ACC-REC-004-05 statement: >- A complete acceptance request belongs only to a blocker that is open, investigating or accepted. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exceptions_acceptance_request_check - id: INV-DOM-ACC-REC-004-06 statement: Retained notes cannot be revised or removed. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-exceptions.table.ts:reconciliation_exception_notes_refuse_mutation_trigger - id: INV-DOM-ACC-REC-004-07 statement: >- Blocker mutations invoke attention synchronization in their transaction; Platform records change only when publishing is enabled. enforced_at: - service provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-blocker-items.ts:syncBlockerAttention - id: INV-DOM-ACC-REC-004-08 statement: >- An overdue concern cannot resolve while its subject remains overdue and unclaimed on the evaluated day. enforced_at: - service provenance: documented source: >- services-accounting:docs/reconciliation/architecture.md#24a. ACCT-M8 WP-B: the service gaps the baseline run found (API and postings) physical: - accounting.reconciliation_exceptions - accounting.reconciliation_exception_subjects - accounting.reconciliation_exception_steps - accounting.reconciliation_exception_notes - accounting.reconciliation_events evidence: - >- services-accounting at f47cb263: modules/reconciliation/db/reconciliation-exceptions.table.ts; services/persistence/reconciliation-exceptions.ts, reconciliation-blocker-items.ts, bank-mismatch-exceptions.ts; services/exceptions/detectors.ts, exception-resolution.ts, exception-titles.ts; services/rules/transitions.ts, blocker-attention.ts; attention/reconciliation-blockers.attention.ts; metadata/reconciliation-exceptions.object.ts; docs/reconciliation/architecture.md ยง13. - >- react-console at baf6dae3: components/accounting/reconciliation/exceptions-screen.tsx. --- # Reconciliation Problem ## What It Models An exception retains a reconciliation concern and the investigation used to conclude it. Missing money, stale deposits, bank disagreement, drift and manually raised concerns share this work record. ## Identity and Attributes Condition keys prevent repeated detection from duplicating current work. Status records progress, severity controls readiness, and closing retains an explanation with its actors. ## Relationships Subjects identify the payouts, settlement effects or explanations involved. Readiness carries associated concerns with their principal finding and separately lists accepted period concerns. ## Invariants The structured invariants identify investigation, acceptance and retained-note protections. Blocker attention joins the business transaction when enabled; disabling publication leaves business records without attention. ## How It Is Stored and Shared Reconciliation owns the investigation and registers read-only exception metadata for Platform attention. Platform supplies audience resolution and presentation; custom fields are absent. ## Open Design Questions Acceptance currently suppresses future raising of the same condition. Product must decide whether that acceptance should ever be reconsidered, and late-posting review needs an implemented path.