feat(actor): preserve event causality

[yordis]

• Domain event streams need stable causality metadata without leaking application IAM terminology.
• Some event contracts only need the durable actor identifier, while others need room for service-specific actor taxonomy.
• Actor taxonomies need room to evolve across services without forcing a closed enum too early.

[cursor]

PR Summary

Low Risk
Additive proto and documentation only; no changes to existing messages or generation behavior in this repo.

Overview
Introduces trogon.actor.v1alpha1 shared value types so domain events can record who caused an action without baking in IAM terms.

Actor carries an open type token plus opaque id for envelopes and fields like created_by when consumers need actor class and identifier. ActorId wraps a single value when the surrounding contract already fixes the actor class.

Adds docs/explanation/actor-identity.md (when to pick each type, JSON shapes, and not conflating actor ids with object ids) and links it from the docs index; the root README now mentions domain actor identity alongside existing extensions.

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

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	⏩ skipped	May 25, 2026, 7:38 PM

[coderabbitai]

Warning

Review limit reached

@yordis, we couldn't start this review because you've used your available PR reviews for now.

Your plan includes 1 review of capacity. Refill in 41 minutes and 23 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 30b1fd37-29c1-4a84-bc4c-7d4178baef44

📥 Commits

Reviewing files that changed from the base of the PR and between 397ea93 and c879e59.

📒 Files selected for processing (4)

• README.md
• docs/README.md
• docs/explanation/actor-identity.md
• proto/trogon/actor/v1alpha1/actor.proto

Walkthrough

This PR introduces a stable Actor value type for cross-service domain event causality. It adds a new protobuf message definition with comprehensive documentation explaining its semantics, field interpretation, and usage patterns, along with updates to the package README and documentation index.

Changes

Actor Value Type Definition

Layer / File(s)	Summary
Actor protobuf contract and Elixir configuration proto/trogon/actor/v1alpha1/actor.proto	Defines the trogon.actor.v1alpha1.Actor message with two string fields: type (stable token) and id (opaque scoped identifier). Configures Elixir codegen with a module prefix via file options.
Actor semantics documentation and package updates docs/explanation/actor-identity.md, docs/README.md, README.md	Explains the Actor message purpose, field semantics, and design guidance (e.g., type as open stable token, id as opaque scoped identifier not for display). Updates documentation index to link the Actor Identity explanation and broadens the main README description to include value types.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Poem

A stable actor stands so tall,
Cross-services it answers the call,
With type and id, a pair so true,
Domain events now know who's who. 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(actor): preserve event causality' directly relates to the main change: introducing a stable Actor message to preserve domain event causality without leaking IAM terminology.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description directly relates to the changeset, explaining the rationale for introducing the Actor message to preserve event causality with stable identifiers.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/add-actor-type

---

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.}