chore(actor): align identity semantics

[yordis]

• Actor identity contracts need to preserve the intended self-describing identifier semantics without introducing a duplicate concept.
• Shared event metadata needs stable causality language for replay and audit consumers.
• Breaking validation needs to compare pull requests against the accepted main contract.

[cursor]

PR Summary

Low Risk
Comment and documentation updates plus a CI comparison baseline change; no runtime API or schema field changes in the diff.

Overview
Actor identity guidance and actor.proto comments now treat ActorId as the default for shared causality: one self-describing canonical string (e.g. users/usr_123) in value, with Actor reserved when type and id must stay separate. Docs add on_behalf_of, JSON examples, and rationale for the value field name (no separate ActorRef type).

Buf CI on pull requests compares breaking changes only against main (drops ref=HEAD~1), so validation matches the accepted branch contract rather than the parent commit.

^{Reviewed by Cursor Bugbot for commit 0f0544b. 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	✅ passed	May 26, 2026, 12:18 AM

[coderabbitai]

Warning

Review limit reached

@yordis, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 13 seconds. Learn how PR review limits work.

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

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a32d4dfa-ac41-4ccc-9d69-ce281c59c7ca

📥 Commits

Reviewing files that changed from the base of the PR and between d0d3cc2 and 0f0544b.

📒 Files selected for processing (3)

• .github/workflows/buf.yml
• docs/explanation/actor-identity.md
• proto/trogon/actor/v1alpha1/actor.proto

Walkthrough

This PR refines the actor identity contract by updating both the protobuf documentation comments for ActorId and the explanatory guidance in the actor identity documentation. Changes clarify when to use ActorId as a canonical reference versus Actor for separate class/id fields, with updated examples showing the ActorId JSON shape.

Changes

ActorId Contract Refinement

Layer / File(s)	Summary
ActorId contract definition proto/trogon/actor/v1alpha1/actor.proto	Proto documentation comments redefine ActorId as a stable, self-describing actor reference value, emphasizing consumers should compare the complete canonical value without parsing outside the documented namespace contract.
ActorId usage guidance and examples docs/explanation/actor-identity.md	Explanatory documentation refines rules for choosing ActorId (single canonical reference) versus Actor (separate class and local id fields). Updated EventMetadata and object creation examples show ActorId JSON shape as { "value": ... } and add constraints clarifying when not to use ActorId for the domain object being created/updated/referenced.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• TrogonStack/trogon-proto#52: Introduces the Actor message and initial actor identity documentation; this PR refines the contract and usage semantics for ActorId within that framework.

Suggested labels

buf:skip:breaking

Poem

🐰 A reference pure, stable and true,
ActorId stands as a canonical view,
No parsing required, just value and grace,
The actor's own home in identity's place! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title accurately describes the main change: refining and aligning actor identity semantics documentation across proto comments and markdown explanation files.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation for updating actor identity contracts and event metadata documentation.

_{✏️ 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-2

---

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