feat: event record API refactor

[patrickleet]

Summary by CodeRabbit

Release Notes

• New Features

  • Added event payload codec infrastructure with bitcode serialization support
  • Upcaster chain validation detects invalid transitions (same-version, backward, cyclic)

• Bug Fixes

  • Serialization errors are now properly returned instead of panicking
  • Corrupted read-model records are detected and reported
  • Invalid upcaster configurations are rejected at runtime

• Documentation

  • Added Postgres event store contract specification

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ab550b34-920a-401f-abb7-ce225b5204d1

📥 Commits

Reviewing files that changed from the base of the PR and between 93733c9 and 1a8bbee.

📒 Files selected for processing (53)

• docs/postgres-event-store.md
• docs/research-and-roadmap.md
• sourced_rust_macros/src/lib.rs
• src/aggregate/aggregate.rs
• src/commit_builder/mod.rs
• src/emitter/entity_ext.rs
• src/entity/entity.rs
• src/entity/event_record.rs
• src/entity/mod.rs
• src/entity/upcaster.rs
• src/hashmap_repo/repository.rs
• src/lib.rs
• src/microsvc/error.rs
• src/outbox/commit.rs
• src/outbox/message.rs
• src/outbox_worker/repository_ext.rs
• src/outbox_worker/worker.rs
• src/read_model/in_memory.rs
• src/repository/error.rs
• src/snapshot/repository.rs
• tests/blob_game/main.rs
• tests/bomberman/commands.rs
• tests/bomberman/domain/game_map.rs
• tests/bomberman/error.rs
• tests/enqueue/aggregate.rs
• tests/enqueue/main.rs
• tests/event_store/main.rs
• tests/microsvc/basic.rs
• tests/microsvc/handlers/counter_create.rs
• tests/microsvc/handlers/counter_increment.rs
• tests/read_models/main.rs
• tests/sagas/distributed.rs
• tests/sagas/handlers/inventory/init.rs
• tests/sagas/handlers/inventory/reserve.rs
• tests/sagas/handlers/messages.rs
• tests/sagas/handlers/orders/complete.rs
• tests/sagas/handlers/orders/create.rs
• tests/sagas/handlers/payments/process.rs
• tests/sagas/handlers/saga/on_inventory_reserved.rs
• tests/sagas/handlers/saga/on_order_completed.rs
• tests/sagas/handlers/saga/on_order_created.rs
• tests/sagas/handlers/saga/on_payment_succeeded.rs
• tests/sagas/handlers/saga/start.rs
• tests/sagas/microsvc_saga.rs
• tests/sagas/orchestration.rs
• tests/snapshots/main.rs
• tests/sourced/aggregate.rs
• tests/sourced/main.rs
• tests/sourced_enqueue/main.rs
• tests/sourced_snapshot/main.rs
• tests/sourced_upcasting/main.rs
• tests/todos/main.rs
• tests/upcasting/main.rs

---

📝 Walkthrough

Walkthrough

This PR introduces codec-aware event record storage with explicit payload codec metadata, replaces the PayloadError type with a unified EventRecordError, and makes event digestion, snapshot setting, and outbox operations return SourcedResult instead of panicking. It updates all proc-macros to synthesize and propagate errors, refactors CommitBuilder and OutboxWorker to handle failures explicitly, and adds error conversions across handler and service boundaries. Extensive test updates handle now-fallible operations throughout.

Changes

Codec Infrastructure & Fallible Event Recording

Layer / File(s)	Summary
Codec & Error Type Infrastructure src/entity/event_record.rs, src/entity/mod.rs, src/lib.rs, docs/postgres-event-store.md	Introduces PayloadCodec trait and BitcodePayloadCodec implementation; replaces PayloadError with EventRecordError; extends EventRecord with payload_codec and payload_codec_version fields with serde defaults; documents schema and backward compatibility for the Postgres event store contract.
Entity Event Recording with Error Handling src/entity/entity.rs, src/hashmap_repo/repository.rs, tests/event_store/main.rs, tests/sourced/aggregate.rs, tests/upcasting/main.rs	Makes Entity::digest, digest_v, digest_empty, and set_snapshot return SourcedResult; serializes payloads via BitcodePayloadCodec; avoids mutation on serialization failure; updates set_snapshot to sync committed_version; updates test setup to unwrap results.
OutboxMessage Codec-Aware Construction src/outbox/message.rs, src/outbox/commit.rs, tests/sagas/handlers/messages.rs	Updates all OutboxMessage constructors and encode methods to return SourcedResult using BitcodePayloadCodec; adds lease deadline validation with overflow/epoch checks; replaces expect() with error-aware construction; updates test message creation to unwrap results.
Upcaster Error Handling & Validation src/entity/upcaster.rs, src/aggregate/aggregate.rs, src/snapshot/repository.rs	Introduces UpcastError enum for same-version, backward-version, and cycle detection; makes upcast_events return Result with validation logic; propagates errors in hydration paths; adds unit tests for error cases.
Proc-Macro Error Propagation & Return Type Synthesis sourced_rust_macros/src/lib.rs, tests/enqueue/aggregate.rs, tests/sourced/aggregate.rs	Updates #[digest], #[enqueue], aggregate!, and #[sourced] macros to synthesize SourcedResult return types, wrap method bodies with guarded error propagation, emit ?-based fallible calls, and propagate errors through generated replay arms; adds tail-expression try support.
EntityEmitter & CommitBuilder Error Handling src/emitter/entity_ext.rs, src/commit_builder/mod.rs	Makes EntityEmitter::enqueue_with return SourcedResult, avoiding serialization when replaying; refactors CommitBuilder to capture read-model serialization errors and defer reporting to commit* phases via check_staged() helper; adds FailingView and FailingSerialize test fixtures.
OutboxWorker & Repository Error Propagation src/outbox_worker/worker.rs, src/outbox_worker/repository_ext.rs, tests/todos/main.rs	Updates process_message and process_batch to return SourcedResult; propagates errors from claim/complete/release/fail via ?; adds claimed flag to track successful claims; updates repository_ext to use ? on state transitions; extends batch test coverage.
Error Type Conversions & Integration Points src/repository/error.rs, src/microsvc/error.rs, tests/bomberman/error.rs, tests/read_models/main.rs, tests/microsvc/handlers/*, tests/sagas/handlers/*	Adds From<EventRecordError> implementations for HandlerError, RepositoryError, and GameError; enables automatic error coercion in handler closures; updates saga handlers and microsvc handlers to use ? for fallible operations; updates game commands to propagate errors.
Widespread Test Updates for Fallible Operations tests/blob_game/main.rs, tests/bomberman/commands.rs, tests/bomberman/domain/game_map.rs, tests/enqueue/main.rs, tests/read_models/main.rs, tests/sagas/distributed.rs, tests/sagas/orchestration.rs, tests/snapshots/main.rs, tests/sourced/main.rs, tests/sourced_enqueue/main.rs, tests/sourced_snapshot/main.rs, tests/sourced_upcasting/main.rs, tests/todos/main.rs, tests/upcasting/main.rs, tests/read_model/in_memory.rs	Updates all test suites to handle now-fallible aggregate and entity operations by adding .unwrap() on initialize, digest*, complete, and worker calls; refactors test setup into chained multiline style; adds new test helpers and error assertions; maintains existing assertion logic and test semantics across gameplay, saga orchestration, read-model, and upcasting scenarios.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• patrickleet/sourced_rust#14: Applies the same core event-record compatibility infrastructure—codec-aware EventRecordError, fallible SourcedResult returns, error-propagating macros, and Postgres event store contract documentation—with direct code-level overlap in entity recording, proc-macro generation, and error handling patterns.

Poem

🐰 A codec for all, and errors for none!
Bitcode frames each event, with SourcedResult fun.
When digests might fail, we propagate with ?,
And tests now unwrap—what a beautiful spree! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/harden-event-record-compatibility