Build a Cross-Projection Event-Sourcing Snapshot and Point-in-Time Replay Engine With Consistency Verification

[Emmyt24]

Description

eventReplayService.ts replays from the raw event log, but there's no snapshot mechanism — rebuilding any projection (campaign, governance, stream, vault) from scratch means replaying the entire event history from ledger zero, which won't scale and has no way to verify the rebuilt state matches a known-good prior state.

Requirements and Context

• Design a snapshot format capturing the full state of each projection type (campaign, governance, stream, vault) at a given ledger height, versioned for forward compatibility
• Implement scheduled snapshot capture and extend the replay engine to resume from the nearest usable snapshot instead of ledger zero
• Add a consistency verification pass: replaying from a snapshot to a later ledger must produce output byte-identical to replaying from ledger zero to that same ledger
• Document the snapshot format and versioning strategy for future projection schema changes
• Proof of work (required): this is a hard/complex issue — the PR description must include (1) a screenshot of the full relevant test suite run showing all tests passing, and (2) a screenshot of a successful project/module build or compile (npm run build) with no errors. PRs missing either screenshot will not be reviewed.

Suggested Execution

Branch: feat/backend-snapshot-replay-engine

Implement Changes

• Add a ProjectionSnapshot table/model and a snapshot-writer job that captures each projection type on a schedule
• Extend eventReplayService.ts to accept a target ledger and select the nearest usable snapshot as its starting point
• Add the snapshot-vs-zero-replay consistency check as an automated test across all four projection types
• Document the snapshot format and versioning strategy

Test and Commit

Run npx vitest run src/__tests__/eventReplayService.snapshot.test.ts — snapshot-based replay produces output identical to full replay for all four projection types. Then run npm run build and confirm it completes with no errors. Attach a screenshot of both the passing test run and the successful build to the PR description as proof of work.

Example Commit Message

feat(backend): cross-projection snapshot and point-in-time replay engine

Closes #<issue>

Guidelines

• Branch from main, open a PR back to main
• All new code must have corresponding tests
• Run npm run lint and npm run test before pushing
• Follow existing naming conventions and file structure
• PR description must reference this issue number (e.g., Closes #<issue>)
• Keep commits atomic and use conventional commit format
• This is a hard/complex issue: PR must include a screenshot of the test suite passing and a screenshot of a successful build/compile — PRs without both screenshots will be marked incomplete and not merged