Skip to content

DST harness + README alignment for frozen-snapshot periods#24

Merged
pbudzik merged 1 commit into
mainfrom
feat/dst-harness
May 16, 2026
Merged

DST harness + README alignment for frozen-snapshot periods#24
pbudzik merged 1 commit into
mainfrom
feat/dst-harness

Conversation

@pbudzik

@pbudzik pbudzik commented May 16, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds tests/dst.rs — a Deterministic Simulation Testing harness that drives random sequences of Ingest / Flush / RollupTick / CompactTick / Restart / ClosePeriod against a parallel reference model. After every step it asserts §19.5 (raw sum per account matches the model); at the end of each sequence it does a final flush + rebuild_rollups + tick + compact and asserts §19.8 (raw == rollup). 64 cases per run; failures shrink to a minimum-length op trace.
  • Aligns README with the closed-period frozen-snapshot semantics from PR Frozen-snapshot semantics for closed periods #23 — the GET /periods/{YYYY-MM} endpoint now returns frozen + pending_adjustments + net_total for closed periods, not just state + total. Adds a Period lifecycle subsection and a Status bullet for the DST harness.

Notes

  • The original failing seed (a RollupTick on an empty DB, advancing the watermark past hour 0 before any events arrived) is checked in via tests/dst.proptest-regressions so CI replays it before generating novel cases. The fix in the harness is to call rebuild_rollups(0, i64::MAX) before the final reconciliation tick — same primitive operators use in production when rollups drift.
  • The reference model deliberately stays minimal: acked-event hashes, per-account totals, closed period set. It does not model the rollup watermark or segment layout — the SUT's raw query reflects all of that, which is exactly what we want to compare against.

Test plan

  • cargo test — all 145 tests pass (139 existing + 1 DST + new properties)
  • cargo build --release clean
  • DST seed for the originally-found watermark-advance edge case is captured in the regressions file

🤖 Generated with Claude Code

Adds a state-machine driver (`tests/dst.rs`) that runs randomized
sequences of Ingest / Flush / RollupTick / CompactTick / Restart /
ClosePeriod against a parallel reference model, asserting raw sum ==
model after every step and raw == rollup at the end. 64 cases per
run; failures shrink to a minimum-length op trace.

README updates: closed-period endpoint now documented as returning
frozen snapshot + pending adjustments + net total (was "state +
total" from the lifecycle-only PR), plus a "Period lifecycle"
subsection and a Status bullet calling out the DST harness.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pbudzik pbudzik merged commit 29e23e1 into main May 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant