docs(rivetkit): document actor key overlap

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

• docs(rivetkit): document actor key overlap #4971 👈 (View in Graphite)
• refactor(depot-client): split embedded depot transport #4970 : 1 other dependent PR (#4972 )
• fix(rivetkit): decode legacy v4 actor schedule args #4976
• fix(engine): install rustls provider with pools #4975
• fix(rivetkit): defer initialized persist until state exists #4974
• test(rivetkit): cover failed preflight disconnect handling #4973
• fix(rivetkit): hide pending connections during preflight #4969
• WIP: more fuzz tests #4962
• fix(rivetkit): wrap onMigrate in savepoints #4960 : 1 other dependent PR (#4963 )
• fix(pegboard): align drain grace defaults with stop threshold #4958 : 1 other dependent PR (#4966 )
• fix(rivetkit): preserve bridge error messages #4959
• fix(rivetkit): fire abort signal on shutdown finalize #4957
• fix(rivetkit): use startup kv preload #4956
• fix(client): flatten skipReadyWait option #4955
• ci(publish): add manual preview publish flow #4954
• fix(depot): add ltx decode diagnostics #4953
• fix(universaldb): preserve plain set values #4952
• fix(universaldb): align versionstamp operand encoding #4951
• fix(rivetkit): export database provider types #4950
• wip: kitchen sink agentic loop finish #4949
• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review

Overview: This is a minimal documentation-only PR (2 lines added) that adds a comment explaining an intentional key overlap between LAST_PUSHED_ALARM and WORKFLOW_PREFIX, both of which use byte [6].

---

What the PR does

Documents a non-obvious invariant: LAST_PUSHED_ALARM stores its value at the exact key [6], while workflow data lives under keys prefixed with [6, 1, ...] (since WORKFLOW_STORAGE_PREFIX = [6] + STORAGE_VERSION.WORKFLOW=[1]). The two coexist because no KV operation uses WORKFLOW_PREFIX ([6]) directly as a scan prefix — it always goes through WORKFLOW_STORAGE_PREFIX ([6, 1]).

---

Feedback

Positive:

• This is exactly the kind of non-obvious invariant the CLAUDE.md guidelines call out. The comment explains a hidden constraint that would surprise a reader.
• The comment is placed correctly between the two constants and uses complete sentences per style conventions.
• The explanation is accurate. STORAGE_VERSION.WORKFLOW = 1, so WORKFLOW_STORAGE_PREFIX = [6, 1], which does not collide with the exact [6] alarm key.

Suggestions:

1. Implicit assumption about storage version. The comment says workflow data uses [6, 1, ...] but does not explain why — it is because STORAGE_VERSION.WORKFLOW = 1. If the storage version ever changes, the overlap logic changes. Consider referencing the version constant rather than hardcoding 1 in the comment to make this dependency explicit.

2. Missing guard note. The invariant holds only as long as code scans with WORKFLOW_STORAGE_PREFIX ([6, 1]), not with the raw WORKFLOW_PREFIX ([6]). A future developer who naively prefix-scans on WORKFLOW_PREFIX would silently include the alarm timestamp in results. Adding a note — "never scan with WORKFLOW_PREFIX directly; always use WORKFLOW_STORAGE_PREFIX" — would make the constraint self-enforcing in review.

3. Draft status. If the comment is complete, marking the PR ready would help with visibility.

---

Summary

The change is correct and useful. The suggestions above are optional quality improvements — the comment as-is is already better than nothing. No bugs, no performance or security implications.