REQ-CORE-006: Keyed reconciliation diagnostics and physical-loss sink semantics

docs/spec/IMPLEMENTATION_STATUS.md

@@ -74,7 +74,7 @@ that fact; this file does not.
 | REQ-CONFIG-005 | `READY` | `IMPLEMENTED` | #86 | #88, `a67e2d2f59c9bcb3234505e45c752b7b21dd4227` | Two merged slices. #76 (Issue #74) added top-level shape validation in `src/config/shapeValidation.ts`, proved by `src/config/shapeValidation.test.ts` (`rejects geography given as a plain object instead of an array`, `rejects a present variation given as an array or non-object`, `rejects a non-object candidate` for both `RunOptions` and `ScenarioDefinition`). #88 added `validateScenarioContent` in `src/config/validation.ts`, proved by `src/config/validation.test.ts`: invalid cross-references (`rejects a region with invalid controllerStateKey`, `rejects a region with invalid settlementCurrencyKey`, `rejects a transport link with invalid region references`, `rejects a cohort with invalid regionKey`, `rejects a production unit with invalid owner reference`), out-of-range values (`rejects a transport link with condition out of [0,1]`, `rejects a cohort with out-of-range healthIndex`, `rejects a cohort with negative population`, `rejects a market with zero or negative price`) and `rejects non-finite values in numeric fields`. Each rejection asserts on the thrown diagnostic, so "fail fast with useful diagnostics; do not silently coerce" is proved rather than assumed. Recorded here after reading the merged code, superseding #105, which promoted the status while leaving evidence that described only the #76 slice. |
 | REQ-CORE-004 | `READY` | `IMPLEMENTED` | #185 | #187, `be1eb42f0a38bab639318ff775c9d85162b363c5` | Canonical tick orchestrator and 16-phase framework (M2). tickOrchestrator.ts defines TickContext (tick-scoped ephemeral state), PendingTransitions (regime/policy changes queued for N+1+), and PhaseHandler type for pluggable phase logic. executeTick() runs phases 0-15 sequentially; computeTickHash() provides deterministic replay verification. 25 comprehensive tests (tickOrchestrator.test.ts): phase constants (2), TickContext initialization (3), phase execution (3), full tick trace (3), deterministic hash (4), no-op handler (3), 100+ tick scenario (3), PendingTransitions barrier (2). All acceptance criteria met: WorldState immutable, TickContext carries phase semantics, orchestrator sequential 0-15, phase-trace test proves no phase 16, 100+ ticks preserve stocks, deterministic hash stable, no undocumented mutation paths. TypeScript: 219 tests passed, typecheck clean, build succeeded. C# (.NET 9): 45 tests passed, build clean (REQ-MIGRATION-003 maintained). REQ-CORE-004 ready for M2 gate. Evidence: docs/spec/implementation_status.csv row 16 (PR #187). |
 | REQ-CORE-005 | `READY` | `IMPLEMENTED` | #188 | #247, `a692ae3e38b310efea59bb10fdc41ce1488e526a` | PendingTransitions contract ensuring Phase-14 decisions cannot mutate current-tick state. Interface defines jurisdictionChanges, stateCreations, policyChanges, monetaryPolicyChanges arrays. Helper functions manage transitions immutably; only changes with activateTick = currentTick are active (CORE-T7). 17 tests prove N+1 causality: changes queued in Phase-14 activate only in tick N+1 or later, never in tick N. WorldState.pendingTransitions initialized empty at genesis. TypeScript verification: 304/304 tests passed, typecheck green, build succeeded (7015bc9). REQ-CORE-005 ready for Phase-1 activation logic in M3+. |
-| REQ-CORE-006 | `READY` | `PARTIAL` | #310 | #326, `715ce2f9a127b5f5f032f8c872ace0e8c4515417` | "Foundation (PR #226, Issue #192): Typed MONEY/GOOD/PHYSICAL_LOSS flow records, TickLedger immutable accumulation, computeNetFlow() per-category computation, validateZeroFlowReconciliation() conservation validation (tolerance 1e-9), 9 foundation tests. Partial completion (PR #239, Issue #235): TickLedger integration into TickContext ephemeral state, M2 diagnostic projection. Phase-boundary fail-fast (PR #326, Issue #310, unmerged): executeTick() extended with phase-boundary validation loop; added PhaseBoundaryValidationError interface; stops execution before next phase if validation fails. Four focused negative-control tests prove: (1) early phase unmatched money flow detected before phase N+1; (2) phase N mismatch prevents phase N+1 compensating flow; (3) balanced flows pass validation; (4) fail-fast diagnostic reports category/key/residual. Verification: npm ci + npm run typecheck + npm test 488 passed + npm run build succeeded; dotnet restore + dotnet build + dotnet test 45 passed. REQ-MIGRATION-003 maintained. Complete slice: M2 phase-boundary fail-fast hooks now implement criterion 3." |
+| REQ-CORE-006 | `READY` | `PARTIAL` | #332 | #326, `715ce2f` | PR #226 (Issue #192, foundation), PR #239 (Issue #235, TickLedger integration), PR #326 (Issue #310, phase-boundary fail-fast) merged and passing. PR #333 (Issue #332) in progress: fixing keyed reconciliation key validation (currency/good only, not owner-inclusive) and adding PHYSICAL_LOSS runtime validation (reject NaN/Infinity/negative). Merged partial evidence: #226, #239, #326; completing evidence pending in PR #333. |
 | REQ-ACCEPTANCE-001 | `READY` | `IMPLEMENTED` | #232 | #263, `7808a9175f7fc3b13b30878d194bce8977ce10c0` | Automated test suite (src/simulation/acceptance-001-stock-preservation.test.ts) with 9 comprehensive tests: baseline scenario construction and frozen WorldState property (2), 100+ tick no-op scenario stock preservation (5), documented interface usage without undocumented mutation paths (1), independent seed handling (1). Test coverage: executes 120+ consecutive no-op ticks with no-op phase handler; verifies reconciliationErrors is null for each tick (stocks preserved); validates only time-derived counters (tick number) change; confirms SimulationConfig.numeric.reconciliationRelativeTolerance (1e-9) is applied; checks TickContext carries public documented properties (tick, phase, transactions, rngSeed); proves all entry points use only public APIs. All acceptance criteria met: Baseline scenario builds without error and produces frozen WorldState; 100+ no-op ticks execute and preserve all stocks exactly (no transactions, zero-flow reconciliation passes); Time-derived counters increment correctly; Tolerance-based reconciliation uses only SimulationConfig.numeric.reconciliationRelativeTolerance (1e-9 default); No milestone-local epsilon or undocumented production mutation paths required. Verified across multiple independent seeds (42, 123, 999) proving isolated stock preservation. TypeScript verification: 360 tests passed (31 files, including 9 new), typecheck clean, build succeeded. C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained). REQ-ACCEPTANCE-001 ready for M2 gate closure. |
 | REQ-ACCEPTANCE-002 | `READY` | `IMPLEMENTED` | #228 | #229, `b642f4c517efa898a8b3c13b7be3e7e25abee805` | Deterministic replay hash for 100+ ticks at M2. New integration test suite (src/simulation/acceptance-002-replay-determinism.test.ts) proves: (1) Baseline scenario builds without error and produces frozen WorldState; (2) 100+ consecutive no-op ticks execute without error preserving stocks exactly (zero transactions); (3) Repeated same-seed 100-tick runs produce identical normalized SHA-256 hashes across multiple independent runs; (4) Different seeds produce different hashes; (5) Phase order remains consistent (phases 0-15) across all ticks; (6) Genesis reconciliation passes before tick execution; (7) Each hash is valid hex and tick-dependent; (8) At least 120 ticks (exceeding 100-tick gate) maintain determinism. Test coverage: 22 comprehensive tests in acceptance-002-replay-determinism.test.ts covering construction, execution, determinism, different seeds, configuration replayability, zero-flow reconciliation, and phase trace consistency. Acceptance criteria fully satisfied: 100+ no-op ticks stable, same-seed determinism proved, different-seed differentiation proved, replay hash deterministic and replayable. TypeScript verification: 250 tests passed (24 files), typecheck clean, build succeeded. C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained). |
 | REQ-ACCEPTANCE-003 | `READY` | `IMPLEMENTED` | #253 | #254, `3e77cf588b53d619a5dc20dadf168c6337f15dd3` | Automated test suite (src/simulation/acceptance-003-zero-flow-reconciliation.test.ts) with 12 comprehensive tests: baseline construction, 100+ tick zero-flow reconciliation health, reconciliation tolerance configuration (SimulationConfig.numeric.reconciliationRelativeTolerance = 1e-9), unmatched delta diagnostic structure, deterministic behavior across runs, phase trace integration. All tests pass (334/334 TypeScript, 45/45 C#/.NET). Zero-flow reconciliation passes for no-op scenario across 100+ ticks; reconciliation error structure ready for M3+ economic ledger records. |

docs/spec/implementation_status.csv

@@ -13,7 +13,7 @@ REQ-CONFIG-003,IMPLEMENTED,299,300,91507ac339b1fed65a8d0970941e8fc74eacc87c,"Fou
 REQ-CONFIG-004,IMPLEMENTED,325,329,10146155be38ea3fa103dd162a6b8891334e65c9,"Composite multi-PR completion: PR #208 (Issue #201, merge 83ff432) delivered aggregate-only reconciliation; PR #315 (Issue #306, merge 68aca0d) added owner-bound identity validation for money, goods, capital, population and resources with negative tests for owner/location swaps; PR #324 (Issue #317, merge 35b1717) completed final FX-pool reserve reconciliation with MonetaryAuthority wallet repair, extending genesis ActorRef with MONETARY_AUTHORITY, emitting owner-bound MONEY_ENDOWMENT records for wallet balances, reconciling them separately from FX_POOL_OPENING, projecting FX-pool base/quote reserves at pool+currency granularity, and including equal-and-opposite cross-pool control. All canonical stock categories (money, goods, population, capital, resources) reconcile within configured canonical tolerance 1e-9. Tests: 475+ TypeScript tests passed; typecheck clean; build succeeded; legacy .NET 45 tests passed (REQ-MIGRATION-003 maintained). Acceptance: opening stock reconciliation passes within canonical tolerances for every tracked stock category."
 REQ-CONFIG-005,IMPLEMENTED,86,88,a67e2d2f59c9bcb3234505e45c752b7b21dd4227,"Two merged slices. #76 (Issue #74) added top-level shape validation in `src/config/shapeValidation.ts`, proved by `src/config/shapeValidation.test.ts` (`rejects geography given as a plain object instead of an array`, `rejects a present variation given as an array or non-object`, `rejects a non-object candidate` for both `RunOptions` and `ScenarioDefinition`). #88 added `validateScenarioContent` in `src/config/validation.ts`, proved by `src/config/validation.test.ts`: invalid cross-references (`rejects a region with invalid controllerStateKey`, `rejects a region with invalid settlementCurrencyKey`, `rejects a transport link with invalid region references`, `rejects a cohort with invalid regionKey`, `rejects a production unit with invalid owner reference`), out-of-range values (`rejects a transport link with condition out of [0,1]`, `rejects a cohort with out-of-range healthIndex`, `rejects a cohort with negative population`, `rejects a market with zero or negative price`) and `rejects non-finite values in numeric fields`. Each rejection asserts on the thrown diagnostic, so ""fail fast with useful diagnostics; do not silently coerce"" is proved rather than assumed. Recorded here after reading the merged code, superseding #105, which promoted the status while leaving evidence that described only the #76 slice."
 REQ-CORE-004,IMPLEMENTED,185,187,be1eb42f0a38bab639318ff775c9d85162b363c5,"Canonical tick orchestrator and 16-phase framework (M2). tickOrchestrator.ts defines TickContext (tick-scoped ephemeral state), PendingTransitions (regime/policy changes queued for N+1+), and PhaseHandler type for pluggable phase logic. executeTick() runs phases 0-15 sequentially; computeTickHash() provides deterministic replay verification. 25 comprehensive tests (tickOrchestrator.test.ts): phase constants (2), TickContext initialization (3), phase execution (3), full tick trace (3), deterministic hash (4), no-op handler (3), 100+ tick scenario (3), PendingTransitions barrier (2). All acceptance criteria met: WorldState immutable, TickContext carries phase semantics, orchestrator sequential 0-15, phase-trace test proves no phase 16, 100+ ticks preserve stocks, deterministic hash stable, no undocumented mutation paths. TypeScript: 219 tests passed, typecheck clean, build succeeded. C# (.NET 9): 45 tests passed, build clean (REQ-MIGRATION-003 maintained). REQ-CORE-004 ready for M2 gate. Evidence: docs/spec/implementation_status.csv row 16 (PR #187)."
-REQ-CORE-006,PARTIAL,310,326,715ce2f9a127b5f5f032f8c872ace0e8c4515417,"""Foundation (PR #226, Issue #192): Typed MONEY/GOOD/PHYSICAL_LOSS flow records, TickLedger immutable accumulation, computeNetFlow() per-category computation, validateZeroFlowReconciliation() conservation validation (tolerance 1e-9), 9 foundation tests. Partial completion (PR #239, Issue #235): TickLedger integration into TickContext ephemeral state, M2 diagnostic projection. Phase-boundary fail-fast (PR #326, Issue #310, unmerged): executeTick() extended with phase-boundary validation loop; added PhaseBoundaryValidationError interface; stops execution before next phase if validation fails. Four focused negative-control tests prove: (1) early phase unmatched money flow detected before phase N+1; (2) phase N mismatch prevents phase N+1 compensating flow; (3) balanced flows pass validation; (4) fail-fast diagnostic reports category/key/residual. Verification: npm ci + npm run typecheck + npm test 488 passed + npm run build succeeded; dotnet restore + dotnet build + dotnet test 45 passed. REQ-MIGRATION-003 maintained. Complete slice: M2 phase-boundary fail-fast hooks now implement criterion 3."""
+REQ-CORE-006,PARTIAL,332,326,715ce2f,"PR #226 (Issue #192, foundation), PR #239 (Issue #235, TickLedger integration), PR #326 (Issue #310, phase-boundary fail-fast) merged and passing. PR #333 (Issue #332) in progress: fixing keyed reconciliation key validation (currency/good only, not owner-inclusive) and adding PHYSICAL_LOSS runtime validation (reject NaN/Infinity/negative). Merged partial evidence: #226, #239, #326; completing evidence pending in PR #333."
 REQ-ACCEPTANCE-002,IMPLEMENTED,228,229,b642f4c517efa898a8b3c13b7be3e7e25abee805,"Deterministic replay hash for 100+ ticks at M2. New integration test suite (src/simulation/acceptance-002-replay-determinism.test.ts) proves: (1) Baseline scenario builds without error and produces frozen WorldState; (2) 100+ consecutive no-op ticks execute without error preserving stocks exactly (zero transactions); (3) Repeated same-seed 100-tick runs produce identical normalized SHA-256 hashes across multiple independent runs; (4) Different seeds produce different hashes; (5) Phase order remains consistent (phases 0-15) across all ticks; (6) Genesis reconciliation passes before tick execution; (7) Each hash is valid hex and tick-dependent; (8) At least 120 ticks (exceeding 100-tick gate) maintain determinism. Test coverage: 22 comprehensive tests in acceptance-002-replay-determinism.test.ts covering construction, execution, determinism, different seeds, configuration replayability, zero-flow reconciliation, and phase trace consistency. Acceptance criteria fully satisfied: 100+ no-op ticks stable, same-seed determinism proved, different-seed differentiation proved, replay hash deterministic and replayable. TypeScript verification: 250 tests passed (24 files), typecheck clean, build succeeded. C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained)."
 REQ-VISUALIZATION-004,IMPLEMENTED,160,220,f199c8677e99256c4b9ca46d68772b80ef7aa1b3,"M1 Milestone Preview (REQ-VISUALIZATION-004): deterministic JSON snapshot of canonical world-gen overview without exposing mutable domain objects. src/diagnostics/m1Preview.ts generates typed M1Preview interface exposing scenario ID/seed/configVersion, world topology counts (stateCount, regionCount, currencyCount, etc.), and arrays of State/Currency/Region/Clan details. src/diagnostics/m1Preview.test.ts (12 tests) generates docs/m1-preview.json from baseline-multistate-v1 scenario and seed 42; asserts M1Preview schema completeness, non-zero entity counts, deterministic generation invariance, and that docs/index.html references m1-preview.json without runtime imports. Smoke test: generated artifact is deterministically serializable, contains 4 states (State Alpha/Beta/Gamma/Delta), 24 regions, 4 currencies, 8 clans, 216 cohorts, 172 production units. All acceptance criteria met: M1 preview JSON generated deterministically from baseline scenario; GitHub Pages displays world-gen topology via static artifact (no mutable WorldState exposure); one-way read-only diagnostic output; TypeScript 231/231 tests passed, typecheck clean, build succeeded; C# 45/45 tests passed, build clean (REQ-MIGRATION-003 maintained)."
 REQ-VISUALIZATION-005,IMPLEMENTED,243,244,5777e08957350dc610790f7e8cd59a0e5a70476d,"M2 Milestone Preview (REQ-VISUALIZATION-005): deterministic JSON snapshot of canonical M2 tick orchestration and zero-flow reconciliation without exposing mutable domain objects. src/diagnostics/m2Preview.ts generates typed M2Preview interface exposing scenario ID/seed/configVersion, world topology counts, phase trace (0-15 proof with no phase 16), tick counter (firstTick/lastTick/ticksExecuted = 1/101/101), and reconciliation health (passedTicks=101/failedTicks=0/tolerance=1e-9). src/diagnostics/m2Preview.test.ts (13 tests) generates docs/m2-preview.json from baseline-multistate-v1 scenario and seed 42 executing 101 no-op ticks; asserts M2Preview schema completeness, phase trace exactly 0-15 (no phase 16), tick counter preservation, reconciliation passes (all 101 ticks pass with zero unmatched deltas within tolerance 1e-9), deterministic generation invariance, and that docs/index.html references m2-preview.json without runtime imports. Smoke test: generated artifact is deterministically serializable, phase sequence correct (16 phases/tick * 101 ticks = 1616 total phases), tick range 1-101, reconciliation status clean (passedTicks=101, failedTicks=0). All acceptance criteria met: M2 preview JSON generated deterministically from baseline scenario; 100+ ticks (101 executed) maintain zero-flow reconciliation; phase trace proves 0-15 without phase 16; GitHub Pages displays tick/phase/reconciliation health via static artifact (no mutable WorldState exposure); one-way read-only diagnostic output; TypeScript 287/287 tests passed, typecheck clean, build succeeded; C#/.NET 45/45 tests passed, build clean (REQ-MIGRATION-003 maintained)."