fix!: fence aggregate replay by event schema version

[patrickleet]

An aggregate handler currently accepts any event with its registered name if the payload happens to decode. Because replay payloads are positional, an older or future schema with the same layout can silently apply the wrong domain semantics.

Generated replay now checks the event schema version after the existing upcaster stage and before decoding or invoking the handler. Rejected events cannot change aggregate state or append events. Both #[sourced] and aggregate! use the same generated check, including snapshot-tail loads through native and cell repositories.

For example, this handler accepts version 2 directly and version 1 only through a declared upcaster to version 2:

#[event("renamed", version = 2)]
fn rename(&mut self, name: String) {
    self.name = name;
}

Lower-level registrations now declare the handler version explicitly:

aggregate!(Account, entity {
    "renamed"(name), version = 2 => rename,
});

Omitted versions default to 1, consistent with #[event] and #[digest]. The README documents the syntax and migration.

Breaking change

aggregate! registrations for versioned handlers must declare version = N matching their recorder. Unsupported older and future versions now fail replay even when their payload layouts match. Existing stored events are unchanged; supported older events require a complete upcaster chain to the handler version.

Validation

• Reproduced the bug on the unmodified base: all three initial regressions failed (both generated replay paths and full hydration).
• Eight regression tests cover unchanged aggregate/entity state on rejection, old and future same-shaped payloads, unit and ignored-payload handlers, exact versions, same-shaped upcasting, incomplete chains, snapshot prefixes/tails, and unchanged cell repository storage.
• cargo test --workspace --all-targets passed.
• cargo test --workspace --all-features --all-targets --quiet passed.
• Focused sourced/aggregate upcasting, snapshot, replay-property tests and the complete macro test suite passed.
• Changed-file rustfmt --check and git diff --check passed.

The all-features run uses the repository's normal environment-gated integration tests; it does not claim a live celld deployment test.

Whole-workspace cargo fmt --all -- --check still reports pre-existing differences in eight untouched files on base f095c863: src/lib.rs, src/microsvc/cell_host/{causal,command}.rs, src/microsvc/mod.rs, src/microsvc/service/{routes,runtime,tests}.rs, and tests/causal_wait_path/main.rs. This PR leaves that unrelated formatting out.

Stacked on #245; this PR contains only the replay-version change.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: b4fd3911-c1da-4e58-85ea-e70c35020989

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}