feat: add initial state module

[yordis]

Summary

In upstream Commanded, the aggregate module serves dual purposes: it defines both the state struct (via defstruct) and the behavior (execute/2, apply/2). This coupling is a hard blocker when aggregate state comes from an external source like protobuf—generated modules cannot be modified without being overwritten on regeneration.

This PR adds an initial_state option to the router's dispatch macro. When provided, initial_state.initial_state/0 is called to build the aggregate's initial state instead of struct(AggregateModule), fully decoupling the aggregate behavior module from the state representation. If initial_state is omitted the existing behavior is unchanged.

Note

This aligns with the Functional Decider Pattern, where an aggregate is a set of pure functions (execute, apply, initial_state) operating on state, rather than a stateful object that owns its data structure.

Related

• feat: add aggregate identity handling to use Commanded.Aggregate.Identity protocol #43 -- related: adds Commanded.Aggregate.Identity protocol, also motivated by protobuf / external struct use cases

[cursor]

PR Summary

Medium Risk
Changes core aggregate lifecycle/routing and state rebuilding paths by introducing configurable initial state modules and consistency checks, which could affect command dispatch and snapshot rebuild behavior if misconfigured.

Overview
Adds a new initial_state option to the router dispatch macro and command dispatch pipeline, allowing aggregates to initialize/rebuild state via initial_state.initial_state/0 (instead of struct(aggregate_module)) and propagating this through aggregate startup and aggregate_state/… calls.

Tightens validation and safety: rejects invalid initial_state modules, enforces consistent initial_state per aggregate across dispatched commands, and prevents opening an already-running aggregate with a conflicting initial_state.

Updates tests and docs to cover separate state-module aggregates and snapshotting behavior, and relaxes an OTel exception-message assertion.

Test DB config now reads Postgres hostname from PG_HOST (please confirm PG_HOST is defined in every environment where tests run, e.g. CI/dev).

^{Reviewed by Cursor Bugbot for commit 6b98b7c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Draft detected.

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7be7b1f8-53e9-4f2b-ba9e-4d86c71f9ea8

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch split-aggregate-and-payload-mod

---

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 and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5b638a0. Configure here.}