REQ-CORE-006 completion: M2 ledger hooks and worldstate reconciliation #235

Goal

Complete REQ-CORE-006 foundation by implementing phase-level invariant hooks and integrating M2 typed ledger/flow records with WorldState reconciliation for zero-flow validation across the 100+ tick no-op scenario.

Evidence

Specification: docs/spec/mirror/06 - Handoff/11 — REPOSITORY_MIGRATION_AND_MILESTONE_GATES.md, Milestone 2 section

• Requirement ID: REQ-CORE-006
• Registry status: READY
• Current implementation: PARTIAL (foundation merged in PR Implement M2 typed ledger/flow records (REQ-CORE-006 foundation) #226)
• Dependencies: REQ-CORE-004 (IMPLEMENTED), REQ-CONFIG-001 (IMPLEMENTED)

Scope

Build on PR #226 foundation (typed records, TickLedger, computeNetFlow, validateZeroFlowReconciliation) to complete:

1. Phase-level invariant hooks: Integrate hooks into TickContext that enforce conservation laws and catch mutations that violate zero-flow reconciliation at phase boundaries

2. TickContext integration: Ensure TickLedger is passed through TickContext across all 16 phases and accumulates records deterministically

3. WorldState reconciliation: After tick completion, call validateZeroFlowReconciliation against the accumulated TickLedger to prove all stocks balance within SimulationConfig.numeric.reconciliationRelativeTolerance

4. M2 diagnostic projection: Implement a normalized read-only view of MONEY/GOOD/PHYSICAL_LOSS flows with tick/phase/owner attribution for the Milestone Preview (future visualization)

Non-goals

• Do not implement Phase-specific economic logic or business rules (M3+ markets, production, fiscal effects)
• Do not add market telemetry or per-actor flow projection
• Do not create new tolerance values; use only SimulationConfig.numeric.reconciliationRelativeTolerance

Acceptance criteria

1. ✓ TickLedger is passed through TickContext.currentLedger and accumulated deterministically across all 16 phases (0-15)
2. ✓ validateZeroFlowReconciliation() is called after each no-op tick and passes for all stock categories (MONEY, GOOD, PHYSICAL_LOSS, POPULATION, CAPITAL, RESOURCE)
3. ✓ Phase-level invariant hooks detect and fail-fast on any early mutation that would violate zero-flow conservation before tick completion
4. ✓ Repeated 100+ tick runs preserve stocks exactly (within tolerance) and produce identical replay hash
5. ✓ No production mutation path or milestone-local epsilon/tolerance is invented; all reconciliation uses the resolved SimulationConfig.numeric values
6. ✓ TypeScript: npm ci, npm run typecheck, npm test, npm run build all pass (expanding test suite with phase/hook validation)
7. ✓ C#/.NET: dotnet build/test remain green (REQ-MIGRATION-003 requirement maintained)

Verification

npm ci && npm run typecheck && npm test && npm run build
dotnet restore && dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build

• New integration test: 100+ ticks with full ledger accumulation and zero-flow validation
• Phase trace test extended to assert no unrecorded mutations between phases
• Tolerance-based reconciliation proof comparing against SimulationConfig.numeric.reconciliationRelativeTolerance (1e-9 default)

Dependencies

• REQ-CORE-004: IMPLEMENTED ✓ (TickContext, phase orchestrator)
• REQ-CONFIG-001: IMPLEMENTED ✓ (Configuration and tolerance values)
• Prior merged foundation: PR Implement M2 typed ledger/flow records (REQ-CORE-006 foundation) #226 (TickLedger, flow records, validateZeroFlowReconciliation)

References

• Merged foundation: PR Implement M2 typed ledger/flow records (REQ-CORE-006 foundation) #226 (Issue REQ-CORE-006: Typed ledger/flow records and phase-level invariant hooks #192, now closed)
• Spec sections: REPOSITORY_MIGRATION_AND_MILESTONE_GATES.md lines defining M2 ledger/hooks/reconciliation
• Handoff/01 section 9-10 for invariant references