Implement REQ-CORE-005: PendingTransitions for future policy/jurisdiction/lifecycle effects

docs/spec/IMPLEMENTATION_STATUS.md

@@ -73,7 +73,7 @@ that fact; this file does not.
 | REQ-CONFIG-004 | `READY` | `PARTIAL` | #135 | #179 | Returned to PARTIAL by the operator on 2026-09-06 after the post-merge QA blocker on #179: `reconcileGenesisStocks(ledger, config)` in `src/simulation/genesisReconciliation.ts` reads no world state, sums ledger records and rejects negative totals only, so an omitted or duplicated opening stock passes; Handoff/03 section 20 and section 24 invariants 12/18 require the ledger totals to equal the constructed tick-0 stocks. Repair: Issue #201; its pull request returns this row to IMPLEMENTED with the proving tests named. Merged slices that stand: Genesis ledger and opening-stock reconciliation completed in PR #179: WorldGenesisLedger schema defines 7 genesis record types (MONEY_ENDOWMENT, GOOD_ENDOWMENT, POPULATION_ENDOWMENT, CAPITAL_ENDOWMENT, RESOURCE_ENDOWMENT, BOND_OPENING_POSITION, FX_POOL_OPENING); buildInitialWorld() refactored to record all endowments during steps 3-10 (MonetaryAuthority, State, Clan, Cohort, ProductionUnit registries); reconcileGenesisStocks() verifies conservation within SimulationConfig.numeric.reconciliationRelativeTolerance (1e-9 default) for each category; reconciliation failure throws diagnostic error naming affected category/key/total/residual. Acceptance criteria met: ledger interface defined and immutable; worldGenesisLedger included in WorldState; all opening-stock entries recorded deterministically; reconciliation passes for baseline-multistate-v1 scenario; TypeScript: 181/181 tests passed, typecheck clean, build succeeded; .NET: 45/45 tests passed, build clean (REQ-MIGRATION-003 requirement maintained). REQ-CONFIG-004 acceptance requirement fully satisfied and ready for M1 gate. |
 | 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 | Canonical tick orchestrator and 16-phase framework (M2). tickOrchestrator.ts defines TickContext (tick-scoped ephemeral state) |
-| REQ-CORE-005 | `READY` | `NOT_STARTED` | — | — | — |
+| REQ-CORE-005 | `READY` | `IMPLEMENTED` | #188 | #247 | PendingTransitions contract ensuring Phase-14 decisions cannot mutate current-tick state. Interface defines jurisdictionChanges |
 | REQ-CORE-006 | `READY` | `PARTIAL` | #192 | #226 | M2 typed ledger/flow records foundation (PR #226). Implements: (1) Typed records for MONEY, GOOD, PHYSICAL_LOSS flows with tick/phase, owner/location attribution, delta and reason; (2) TickLedger container for immutable record accumulation; (3) computeNetFlow() for per-category flow computation; (4) validateZeroFlowReconciliation() validating conservation law (category totals = 0 within tolerance 1e-9). Test coverage: 9 new tests covering record creation, accumulation, flow computation, balanced transfers, unmatched flows, tolerance handling. Remaining work: phase-level invariant hooks, M2 diagnostic projection, TickContext integration, WorldState reconciliation. TypeScript: 228 tests passed (9 new), typecheck clean, build succeeded. C# .NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained). Foundation ready for M2 gate follow-up work. |
 | REQ-ACCEPTANCE-001 | `READY` | `NOT_STARTED` | — | — | — |
 | REQ-ACCEPTANCE-002 | `READY` | `IMPLEMENTED` | #228 | #229 | 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 |
@@ -90,7 +90,7 @@ that fact; this file does not.
 | REQ-ACCEPTANCE-004 | `READY` | `NOT_STARTED` | — | — | — |
 | REQ-VISUALIZATION-006 | `READY` | `NOT_STARTED` | — | — | — |
 
-**Summary: 16 of 32 requirement identifiers implemented.**
+**Summary: 17 of 32 requirement identifiers implemented.**
 Also recorded: 3 partial.
 The denominator is the data-row count of the mirrored registry at generation time; it is never carried forward from an earlier revision. Work that is claimed but not yet merged is a `status:in-progress` label on its Issue, not a row here.
 

docs/spec/implementation_status.csv

@@ -17,4 +17,5 @@ REQ-CORE-006,PARTIAL,192,226,,"M2 typed ledger/flow records foundation (PR #226)
 REQ-ACCEPTANCE-002,IMPLEMENTED,228,229,,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,,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,,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).
-REQ-MARKET-001,IMPLEMENTED,246,248,,Ephemeral MarketIntent contract and budget commitment ledger for M3 local market procurement (sections 5-6 of MARKETS_TRADE_FX_CONTRACTS.md). src/simulation/marketIntent.ts defines: MarketIntent interface (id, actor, regionId, goodId, side, purpose, quantities/budgets, inventory buckets); comprehensive validation covering all specification constraints (non-negative/finite quantities, BUY maxSpend, SELL minimumReserveQuantity, ProductionUnit bucket routing [INPUT/OUTPUT/INVESTMENT for specific purposes], actor ownership validation); BudgetCommitmentLedger interface tracking actor+currency+envelope commitments with commitment tracking, overcommitment prevention, and reusable-envelope release. src/simulation/marketIntent.test.ts: 35 comprehensive tests covering valid MarketIntent creation for all actor types (Clan, State, ProductionUnit) and purposes (CONSUMPTION, INPUT, INVESTMENT, PUBLIC_PROCUREMENT, INVENTORY_REBALANCE); validation rejection of non-finite/negative values; budget ledger operations (creation, commitment accumulation, envelope isolation, overcommitment prevention, partial/full release, reusability handling); ProductionUnit-specific bucket routing and validation. src/simulation/tickOrchestrator.ts extended: TickContext now includes budgetLedger field (initialized empty per tick); phase handlers in M3+ can manage budget commitments through the ephemeral ledger without mutation of persistent WorldState. All acceptance criteria met: MarketIntent schema fully defined with all required/optional fields; validation rejects non-finite/negative quantities and invalid constraints; BUY maxSpend and SELL minimumReserveQuantity validated; budget ledger prevents overcommitment within envelope limits; ProductionUnit intents use explicit INPUT/OUTPUT/INVESTMENT buckets; static-fixture test suite covers all constraint classes with 35 tests. TypeScript verification: 322 tests passed (28 files), typecheck clean, build succeeded. C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained).
+REQ-MARKET-001,IMPLEMENTED,246,248,,Ephemeral MarketIntent contract and budget commitment ledger for M3 local market procurement (sections 5-6 of MARKETS_TRADE_FX_CONTRACTS.md). src/simulation/marketIntent.ts defines: MarketIntent interface (id, actor, regionId, goodId, side, purpose, quantities/budgets, inventory buckets); comprehensive validation covering all specification constraints (non-negative/finite quantities, BUY maxSpend, SELL minimumReserveQuantity, ProductionUnit bucket routing [INPUT/OUTPUT/INVESTMENT for specific purposes], actor ownership validation); BudgetCommitmentLedger interface tracking actor+currency+envelope commitments with commitment tracking, overcommitment prevention, and reusable-envelope release. src/simulation/marketIntent.test.ts: 35 comprehensive tests covering valid MarketIntent creation for all actor types (Clan, State, ProductionUnit) and purposes (CONSUMPTION, INPUT, INVESTMENT, PUBLIC_PROCUREMENT, INVENTORY_REBALANCE); validation rejection of non-finite/negative values; budget ledger operations (creation, commitment accumulation, envelope isolation, overcommitment prevention, partial/full release, reusability handling); ProductionUnit-specific bucket routing and validation. src/simulation/tickOrchestrator.ts extended: TickContext now includes budgetLedger field (initialized empty per tick); phase handlers in M3+ can manage budget commitments through the ephemeral ledger without mutation of persistent WorldState. All acceptance criteria met: MarketIntent schema fully defined with all required/optional fields; validation rejects non-finite/negative quantities and invalid constraints; BUY maxSpend and SELL minimumReserveQuantity validated; budget ledger prevents overcommitment within envelope limits; ProductionUnit intents use explicit INPUT/OUTPUT/INVESTMENT buckets; static-fixture test suite covers all constraint classes with 35 tests. TypeScript verification: 322 tests passed (28 files), typecheck clean, build succeeded. C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained).
+REQ-CORE-005,IMPLEMENTED,188,247,,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+.

src/diagnostics/m2Preview.ts

@@ -60,6 +60,7 @@ export function generateM2Preview(worldState: WorldState, ticks: number = 100):
   let currentWorld = worldState;
   const emptyPendingTransitions = {
     jurisdictionChanges: [],
+    stateCreations: [],
     policyChanges: [],
     monetaryPolicyChanges: [],
   };

src/simulation/acceptance-002-replay-determinism.test.ts

@@ -15,9 +15,8 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { buildInitialWorld } from "./worldState";
+import { buildInitialWorld, type PendingTransitions } from "./worldState";
 import { executeTick, computeTickHash, noOpPhaseHandler, initializeTickContext } from "./tickOrchestrator";
-import type { PendingTransitions } from "./tickOrchestrator";
 import { baselineScenario } from "../config/fixtures/baselineScenario";
 import { baselineDefinitionPack } from "../config/fixtures/baselineDefinitionPack";
 import { createDefaultSimulationConfig } from "../config/simulationConfig";
@@ -28,6 +27,7 @@ import { createDefaultSimulationConfig } from "../config/simulationConfig";
 function createEmptyPendingTransitions(): PendingTransitions {
   return {
     jurisdictionChanges: [],
+    stateCreations: [],
     policyChanges: [],
     monetaryPolicyChanges: [],
   };

src/simulation/index.ts

@@ -19,6 +19,7 @@ export {
   type StateState,
   type TransportLinkState,
   type WorldState,
+  type PendingTransitions,
 } from "./worldState";
 
 export {
@@ -31,7 +32,6 @@ export {
   noOpPhaseHandler,
   type TickContext,
   type EconomicTransaction,
-  type PendingTransitions,
   type PhaseHandler,
 } from "./tickOrchestrator";