--- id: STATE-ACC-REC-004 title: Settlement item outstanding standing object: DOM-ACC-REC-002 product_area: accounting module: reconciliation revision: 3 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: not-yet-eligible meaning: Eligibility is absent or later than the requested day. - name: held meaning: Eligible money has no expected release day. - name: in-transit meaning: Unclaimed money has not passed its expected arrival day. - name: late meaning: Arrival is past expectation but within business-day grace. - name: overdue meaning: >- Unclaimed money is past grace without an active or accepted overdue concern. - name: under-investigation meaning: An active overdue investigation explains the past-grace state. - name: accepted meaning: >- An accepted concern removes the overdue blocker while money remains outstanding. - name: in-open-reconciliation meaning: An open explanation actively claims the effect. - name: settled meaning: An approved explanation actively claims the effect. - name: resolved meaning: Permanent resolution ends the original effect’s outstanding standing. transitions: - from: not-yet-eligible to: in-transit trigger: 'Reach eligibility on the requested day, or clear an electronic check.' guard: 'The effect remains unresolved and unclaimed, with a usable expected day.' side_effects: - Recalculate standing; clearing can fill stored timing once. who: Requested day or clearing caller provenance: observed source: >- services-accounting:modules/reconciliation/services/rules/outstanding-state.ts:outstandingStateOf - from: in-transit to: late trigger: Evaluate after the expected arrival day. guard: 'The effect is unheld, unresolved and still within grace.' side_effects: - Report late arrival as a readiness warning. who: Requested day provenance: observed source: >- services-accounting:modules/reconciliation/services/rules/outstanding-state.ts:outstandingStateOf - from: late to: overdue trigger: Evaluate after business-day grace. guard: >- The effect remains unheld and unresolved without an active or accepted overdue concern. side_effects: - Report an overdue readiness blocker. who: Requested day provenance: observed source: >- services-accounting:modules/reconciliation/services/rules/outstanding-state.ts:outstandingStateOf - from: overdue to: under-investigation trigger: Detect the missing arrival. guard: The detector can raise or reopen its condition. side_effects: - Retain the blocker and invoke enabled attention publication. who: Daily detector provenance: observed source: >- services-accounting:modules/reconciliation/services/scheduled/overdue-sweep.ts:sweepOverdueSettlement - from: under-investigation to: accepted trigger: Approve acceptance of the overdue concern. guard: The concern satisfies independent acceptance guards. side_effects: - Remove its overdue blocker while preserving money in clearing. who: Independent acceptance actors provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-exceptions.ts:approveExceptionAcceptance - from: under-investigation to: overdue trigger: >- Resolve the concern using a judged day when its overdue condition does not hold. guard: >- Resolution checks that day; a later requested day can still show overdue money. side_effects: - A later successful detector can reopen the condition. who: Authorized investigator provenance: documented source: 'services-accounting:docs/reconciliation/architecture.md#15.3 Checks' - from: in-transit to: in-open-reconciliation trigger: Claim a traveling effect. guard: >- The effect is compatible, unresolved, not a split original and free of another active claim. side_effects: - Increase the draft’s held amount. who: Authorized preparer provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:claimSettlementItems - from: overdue to: in-open-reconciliation trigger: Claim an overdue effect. guard: Ordinary claim guards pass. side_effects: - >- Create the draft holding; detector clearing waits for settlement or resolution. who: Authorized preparer provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:claimSettlementItems - from: in-open-reconciliation to: in-transit trigger: >- Release preparation while the requested day still classifies the effect in transit. guard: The explanation is open and the financial command version matches. side_effects: - >- Retain release history; otherwise standing follows current timing and concern facts. who: Authorized preparer provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:releaseSettlementItems - from: in-open-reconciliation to: settled trigger: Approve its holding explanation. guard: Finalization passes all guards. side_effects: - Protect the claim; later detection can clear the old overdue concern. who: Eligible finalizer provenance: observed source: >- services-accounting:modules/reconciliation/services/batch-lifecycle/finalize-batch.ts:finalizeReconciliationBatch - from: settled to: in-transit trigger: Complete reversal of its approved holder. guard: Reversal guards pass and the holding is released. side_effects: - >- Recalculate standing from the requested day; the result may be late or overdue instead. who: Authorized reversal actors provenance: observed source: >- services-accounting:modules/reconciliation/services/batch-lifecycle/reverse-batch.ts:reverseReconciliationBatch - from: overdue to: resolved trigger: 'Resolve, write off or split an unheld overdue effect.' guard: >- The effect is current and unresolved; write-off also has accounts and an accepting batch. side_effects: - >- Retain resolution; create parts or write-off requests as appropriate and clear the original concern. who: Authorized settlement resolver provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem; services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:splitSettlementItem - from: in-transit to: resolved trigger: Split or resolve an unheld traveling effect. guard: Ordinary resolution or split guards pass. side_effects: - End the original outstanding position; parts carry forward a split. who: Authorized settlement resolver provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:splitSettlementItem - from: in-open-reconciliation to: resolved trigger: Remove a draft-created manual effect or abandon its draft. guard: The effect belongs to that open preparation. side_effects: - Release its claim and retain withdrawn resolution. who: Authorized preparer provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:removeManualItem invalid: - from: settled to: resolved why: >- An approved claim must be released through reversal before ordinary resolution. - from: resolved to: in-transit why: Original resolution is permanent; split parts have their own positions. - from: settled to: in-open-reconciliation why: Exclusive active claiming prevents a second open holder. concurrency: >- Outstanding standing is a read-time classification, not a persisted timeline. Financial commands lock relevant records; effect resolution and split compare item versions, while claiming is protected by the reconciliation version and exclusive active index. invariants: - INV-DOM-ACC-REC-002-05 - INV-DOM-ACC-REC-002-06 - INV-DOM-ACC-REC-002-08 - INV-DOM-ACC-REC-002-09 evidence: - >- services-accounting at f47cb263: modules/reconciliation/services/rules/outstanding-state.ts, business-days.ts; services/persistence/settlement-items.ts, reconciliation-allocations.ts; services/scheduled/overdue-sweep.ts; services/settlement-items/settlement-item-recording.ts; docs/reconciliation/architecture.md §12.2 to §12.4, §15.3. --- # Settlement item outstanding standing ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> not_yet_eligible : recorded before eligibility [*] --> held : reserve without release not_yet_eligible --> in_transit : eligibility day or check cleared in_transit --> late : past expected day late --> overdue : past grace overdue --> under_investigation : sweep raises exception under_investigation --> accepted : acceptance approved in_transit --> in_open_reconciliation : claimed overdue --> in_open_reconciliation : claimed in_open_reconciliation --> in_transit : released or draft voided in_open_reconciliation --> settled : draft finalized settled --> in_transit : reconciliation reversed overdue --> resolved : written off, resolved or split in_transit --> resolved : split or resolved resolved --> [*] ``` ## Transitions Explained Outstanding standing combines the requested day with current resolution, holdings and concern facts. These arrows illustrate common changes; querying another day is not a historical snapshot of all those facts. ## What Cannot Happen Claimed effects cannot use ordinary split or resolution commands, but withdrawing draft-created manual effects is a distinct path. Release and reversal recalculate the timing result rather than always returning to in transit. ## Concurrency and Timing Outstanding standing is a read-time classification, not a persisted timeline. Financial commands lock relevant records; effect resolution and split compare item versions, while claiming is protected by the reconciliation version and exclusive active index.