Implement M2 typed ledger/flow records (REQ-CORE-006 foundation) by zendev-author[bot] · Pull Request #226 · drevendev/trade_simulation

zendev-author · 2026-09-06T19:16:32Z

Summary

Foundation implementation for REQ-CORE-006: Provide typed ledger/flow records and phase-level invariant hooks for money, goods and physical losses before rich economics (M2).

This PR implements the core typed ledger infrastructure that will support zero-flow reconciliation in M2. The foundation includes:

Typed records for MONEY, GOOD, and PHYSICAL_LOSS flows with attribution
Per-record tick/phase, owner/location, delta, reason and causal linkage
Ledger accumulation container (TickLedger)
Zero-flow validation via conservation law (category totals = 0)
Comprehensive test coverage (9 new tests)

Changed artifacts

docs/spec/IMPLEMENTATION_STATUS.md
docs/spec/implementation_status.csv
src/simulation/index.ts
src/simulation/ledger.test.ts
src/simulation/ledger.ts

Test Plan

TypeScript typecheck: passed
TypeScript tests: 228 passed (228 total, 9 new ledger tests)
TypeScript build: passed
C#/.NET restore: passed
C#/.NET build: passed
C#/.NET tests: 45 passed (REQ-MIGRATION-003 maintained)

Ledger test coverage

createEmptyTickLedger: Creates empty ledger with correct tick
addLedgerRecord: Adds and accumulates records correctly
computeNetFlow: Computes per-category flow aggregation (NOT used in final validation, kept for reference)
validateZeroFlowReconciliation:
- Passes for balanced transfers (zero category total)
- Fails for unmatched flows
- Respects tolerance for small residuals (1e-9 default)
- Properly distinguishes tolerance-respecting vs. oversized residuals

Acceptance criteria

✅ Typed ledger includes tick/phase, stock key, owner/location (bucket support), finite delta, stable reason, causal linkage
✅ Zero-flow reconciliation validates conservation (category totals = 0 within 1e-9 tolerance)
✅ Test-only unmatched delta validation reports category/residual diagnostics
⏳ Phase-level invariant hooks (remaining work for future PR)
⏳ M2 diagnostic projection (remaining work for future PR)
⏳ TickContext integration (remaining work for future PR)
⏳ WorldState-backed reconciliation (remaining work for future PR)

Highest-risk area for review

Zero-flow reconciliation semantic: the implementation validates that each flow category (MONEY, GOOD, PHYSICAL_LOSS) sums to zero across all holders/locations in a tick. This conservation law approach ensures equal-and-opposite transfers reconcile correctly without requiring explicit matching pairs. The tolerance (default 1e-9) respects SimulationConfig.numeric.reconciliationRelativeTolerance for floating-point comparisons.

Blocking gate

None. This is foundation work toward full REQ-CORE-006 gate (M2). Remaining work (phase-level invariant hooks, diagnostic projection, TickContext integration) will be captured as follow-up issues/PRs.

Assumptions and unknowns

Integration into TickContext will happen in a follow-up PR
Phase-level invariant hooks structure will be designed in a follow-up PR
M2 diagnostic projection interface (JSON schema, aggregation logic) is pending specification review

Closes #192

Foundation for Milestone 2 ledger framework: typed records for MONEY, GOOD, and PHYSICAL_LOSS flows with tick/phase attribution, owner/location, finite deltas, stable reason and causal linkage. Provides: - BaseLedgerRecord interface with common fields (tick, phase, reason) - Typed records: MoneyFlowRecord, GoodFlowRecord, PhysicalLossRecord - TickLedger container with immutable record append - computeNetFlow() for per-category flow computation - validateZeroFlowReconciliation() for conservation validation Acceptance criteria satisfied (partial): 1. ✅ Typed ledger includes tick/phase, stock key, owner/location, delta, reason 2. ✅ Test-only unmatched delta validation with category/residual diagnostics 3. ✅ Zero-flow reconciliation via conservation law (category totals = 0) Remaining work for full REQ-CORE-006: - Integration into TickContext - Phase-level invariant hooks - WorldState reconciliation - M2 diagnostic projection Tests: 228 passed (including 9 new ledger tests) TypeScript: typecheck clean, build succeeded C# .NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Adds row for REQ-CORE-006 in docs/spec/implementation_status.csv marking as PARTIAL with PR #226. Describes foundation work completed: typed ledger records, zero-flow reconciliation, test coverage. Regenerates IMPLEMENTATION_STATUS.md from ledger using scripts/implementation_status.py. Implementation status: 15 ledger rows over 32 registry requirements.

zendev-acceptor · 2026-09-06T19:33:53Z

ACCEPT

Verdict on head revision 52b0f51

This PR delivers the foundation implementation of REQ-CORE-006 (M2 typed ledger/flow records), correctly marked as PARTIAL. All merge criteria satisfied:

Verification Summary:

✅ Mergeability: CLEAN, merges cleanly into base
✅ Required checks green at head: build-and-test, policy-guard, typescript, mergeability all pass
✅ Independent verification passed:
- TypeScript: typecheck, 228 tests (9 new ledger tests), build succeeded
- .NET: 45 tests passed, Release build clean, REQ-MIGRATION-003 maintained
✅ Scope: All 5 changed files declared in PR body (src/simulation/ledger.ts/.test.ts, src/simulation/index.ts, docs/spec/IMPLEMENTATION_STATUS.md/implementation_status.csv)
✅ Tests: 9 new comprehensive tests added, no tests deleted or weakened
✅ Handoff: Complete record with achieved outcome, changed artifacts, acceptance criteria status, checks, assumptions, and risk areas
✅ Acceptance criteria: Foundation items met (typed records, zero-flow reconciliation, tolerance handling); diagnostic projection correctly deferred to future PR

Highest-risk area (verified):
Zero-flow reconciliation correctly validates conservation law (category totals = 0 within 1e-9 tolerance from SimulationConfig), tested comprehensively with balanced/unbalanced transfers.

No blocking gates remain. REQ-CORE-006 PARTIAL status accurately recorded in implementation ledger; follow-up work (phase-level hooks, TickContext integration, diagnostic projection, WorldState reconciliation) captured for M2.

… 3, 8, 9 (#278) (#296) * REQ-MARKET-003 ledger row: Fix remaining acceptance criteria 3, 8, 9 for ledger audit - Criterion 3: Update REQ-CORE-006 to IMPLEMENTED with PR #239 merge commit (30e029c...) and evidence naming both #226 foundation and #239 completion - Criterion 8: M2 release planning now validates successfully with all 7 M2 requirements IMPLEMENTED and merge provenance present - Criterion 9: Update REQ-MARKET-002 evidence to note that defaults don't match specification; mark PARTIAL until #270 resolves - Updated REQ-CONFIG-003 evidence to include merged repair PR #288 (Issue #200) with note of semantic validation defect found by SLOPSTER QA - Updated REQ-CONFIG-004 evidence to reflect CONFIG-003 repair merged but blocker (semantic defect) remains - Regenerated IMPLEMENTATION_STATUS.md with corrected evidence All checks pass: TypeScript 439 tests, C# 45 tests, release tagger validation, CSV format validation. Closes #278 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * REQ-MARKET-003 ledger row: Address ACCEPTOR feedback on REQ-CORE-006 evidence Reverts REQ-CORE-006 from IMPLEMENTED back to PARTIAL based on ACCEPTOR verification that PR #239 does not actually implement phase-level invariant hooks (Issue #235 criterion 3). Code only validates at tick-end (line 158 of tickOrchestrator.ts), not at phase boundaries. Evidence updated to document: - Partial completion: TickLedger integration and diagnostic projection merged in PR #239 - Remaining work: Phase-level fail-fast hook implementation and negative-control test - Blocking M2 gate closure until phase-level validation at phase boundaries is implemented All acceptance criteria 3, 8, 9 for Issue #278 remain applicable; REQ-CORE-006 evidence now reflects verified code state rather than unimplemented claims. Checks: TypeScript 439 passed, C# 45 passed, release tagger 16 passed, ledger validation passed. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> --------- Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

…evert ledger to PARTIAL Three defects from ACCEPTOR feedback on PR #333: 1. Reconciliation key validation: currency/good only (not owner-inclusive) - Transfers between different owners now cancel at currency/good level - MONEY: currencyId only; GOOD: goodId only 2. PHYSICAL_LOSS runtime validation: reject NaN, Infinity, negative amounts - addLedgerRecord() validates finite positive/zero amounts 3. Ledger row: reverted to PARTIAL from IMPLEMENTED - Will promote after merge with actual merge commit - Evidence: PRs #226, #239, #326 (merged); completing PR #333 (in progress) Tests: Updated 11 test assertions; added 5 PHYSICAL_LOSS validation tests. Verification: npm test 496 passed, npm run build passed, dotnet test 45 passed (REQ-MIGRATION-003). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

… semantics (#333) * REQ-CORE-006: Keyed reconciliation diagnostics and physical-loss sink semantics Implements the remaining REQ-CORE-006 acceptance gaps after PR #326: 1. validateZeroFlowReconciliation() now reports keyed diagnostics with category/key/residual 2. Each stock key must independently sum to zero (MONEY: currencyId:ownerType:ownerKey, GOOD: goodId:holderType:holderKey:bucket) 3. PHYSICAL_LOSS removed from zero-sum validation - it's a one-sided sink, not a transfer 4. PhaseBoundaryValidationError exposes keyed diagnostics 5. New tests verify keyed mismatch detection and physical-loss exclusion Verification: - npm run typecheck: passed - npm test: 492 tests passed (including new keyed reconciliation tests) - npm run build: succeeded - dotnet build: succeeded (0 warnings, 0 errors) - dotnet test: 45 tests passed (REQ-MIGRATION-003 maintained) Changes: - src/simulation/ledger.ts: Updated validateZeroFlowReconciliation() to return keyed diagnostics - src/simulation/tickOrchestrator.ts: Updated validateTickInvariants() and PhaseBoundaryValidationError - src/simulation/ledger.test.ts: New tests for keyed validation and physical-loss handling - src/simulation/tickOrchestrator.test.ts: New tests for keyed phase-boundary validation Closes #332 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * ledger: record keyed reconciliation completion (PR #333) * REQ-CORE-006: Fix reconciliation key, add PHYSICAL_LOSS validation, revert ledger to PARTIAL Three defects from ACCEPTOR feedback on PR #333: 1. Reconciliation key validation: currency/good only (not owner-inclusive) - Transfers between different owners now cancel at currency/good level - MONEY: currencyId only; GOOD: goodId only 2. PHYSICAL_LOSS runtime validation: reject NaN, Infinity, negative amounts - addLedgerRecord() validates finite positive/zero amounts 3. Ledger row: reverted to PARTIAL from IMPLEMENTED - Will promote after merge with actual merge commit - Evidence: PRs #226, #239, #326 (merged); completing PR #333 (in progress) Tests: Updated 11 test assertions; added 5 PHYSICAL_LOSS validation tests. Verification: npm test 496 passed, npm run build passed, dotnet test 45 passed (REQ-MIGRATION-003). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> --------- Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

…MENTED (#336) After PR #333 (Issue #332) merged as ec1dd89, all REQ-CORE-006 acceptance gaps are closed: - Fixed keyed reconciliation to exclude owner-inclusive account matching - Added PHYSICAL_LOSS runtime validation - Propagated keyed diagnostics through phase-boundary validation Updated ledger row: - STATUS: PARTIAL → IMPLEMENTED - PR: 326 → 333 - MERGE_COMMIT: 715ce2f → ec1dd89 - EVIDENCE: Added PR #333 completion details, preserved #226/#239/#326 history Regenerated IMPLEMENTATION_STATUS.md from authoritative CSV. Verification: implementation_status.py --check passed. Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

github-actions Bot and others added 2 commits September 6, 2026 19:16

zendev-author Bot mentioned this pull request Sep 6, 2026

REQ-CORE-006: Typed ledger/flow records and phase-level invariant hooks #192

Closed

zendev-acceptor Bot merged commit 053cd66 into master Sep 6, 2026
6 of 9 checks passed

zendev-acceptor Bot deleted the claude/issue-192-core-006 branch September 6, 2026 19:33

andy-zen-dev mentioned this pull request Sep 7, 2026

Implementation ledger misrecords recent merges and breaks release provenance #278

Closed

zendev-author Bot mentioned this pull request Sep 8, 2026

REQ-MARKET-003 ledger row: Implement ledger audit acceptance criteria 3, 8, 9 (#278) #296

Merged

1 of 3 tasks

zendev-author Bot mentioned this pull request Sep 8, 2026

REQ-CORE-006: add phase-boundary invariant hooks for M2 fail-fast reconciliation #310

Closed

7 tasks

This was referenced Sep 9, 2026

REQ-CORE-006: finish keyed reconciliation diagnostics and physical-loss sink semantics after #326 #332

Closed

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

Merged

drevendev mentioned this pull request Sep 9, 2026

REQ-CORE-006: reconcile post-merge evidence after #333 #335

Closed

6 tasks

zendev-author Bot mentioned this pull request Sep 9, 2026

REQ-CORE-006: reconcile post-merge evidence after #333 #336

Merged

6 tasks done

Navigation Menu

Repository navigation

Implement M2 typed ledger/flow records (REQ-CORE-006 foundation) - #226

Implement M2 typed ledger/flow records (REQ-CORE-006 foundation)#226
zendev-acceptor[bot] merged 2 commits into
masterfrom
claude/issue-192-core-006

zendev-author Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

zendev-acceptor Bot commented Sep 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Conversation

zendev-author Bot commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changed artifacts

Test Plan

Ledger test coverage

Acceptance criteria

Highest-risk area for review

Blocking gate

Assumptions and unknowns

Uh oh!

Uh oh!

zendev-acceptor Bot commented Sep 6, 2026

ACCEPT

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

zendev-author Bot commented Sep 6, 2026 •

edited

Loading