chore: write/update docs

[MasterPtato]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 20, 2025 8:52pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 20, 2025 8:52pm
rivet-inspector	Ignored	Preview		Nov 20, 2025 8:52pm
rivet-site	Ignored	Preview		Nov 20, 2025 8:52pm

[MasterPtato]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(rivetkit): implement new hibernating ws protocol #3464 : 2 dependent PRs (#3452 , #3487 )
• fix(actor-kv): fix listing keys #3484
• fix(guard): handle actor stopped during ws/req #3481
• chore: rename retry -> hibernate in runner protocol #3473
• fix(udb): update backoff algo #3469
• chore: write/update docs #3468 👈 (View in Graphite)
• chore: add debug scripts #3467
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[claude]

PR Review: Documentation Updates

Summary

This PR adds valuable documentation for the actor lifecycle and serverless flows while removing an outdated script reference from CLAUDE.md. Overall, this is a positive contribution to the project's documentation.

Positive Aspects

✅ Clear Visual Documentation: The Mermaid sequence diagrams effectively illustrate complex system interactions
✅ Comprehensive Coverage: Both ideal and edge-case scenarios are documented ("Messy Serverless Flow")
✅ Good Organization: Separate files for different concerns (actor lifecycle vs serverless flows)
✅ Cleanup: Removed reference to outdated update_workspace.ts script

Suggestions for Improvement

1. Missing File Extension in CLAUDE.md (Line 111)

The removed line references a non-existent file path. Consider verifying if this script removal is intentional or if documentation elsewhere needs updating.

2. Documentation Clarity

ACTOR_LIFECYCLE_FLOW.md:

• Line 28: A->>U: appears incomplete - should specify what is returned to the user (e.g., A->>U: 201 Created (actor_id))
• Lines 40-41, 44-45: Empty message arrows (RWF->>RWS: and RWS->>RWF:) could benefit from labels describing what's being communicated
• Consider adding a brief introduction paragraph explaining what this diagram represents and when to reference it

SERVERLESS_FLOW.md:

• Lines 68-83: Commented-out Mermaid code should either be removed or have a comment explaining why it's kept
• Line 95: Commented participant (%% participant A as API) - remove if unused
• Multiple empty message arrows throughout - consider labeling them for clarity
• The "Messy Serverless Flow" diagram is quite complex. Consider:
  • Adding numbered steps or annotations
  • Breaking into multiple smaller diagrams
  • Adding a summary table of edge cases handled

3. Missing Context

Consider adding:

• A top-level README in docs/engine/ explaining the documentation structure
• Links between related documents
• Glossary for abbreviations (AWF, RWF, RWS, etc.) or expand them on first use
• When to use each diagram (troubleshooting guide, onboarding, etc.)

4. Mermaid Syntax Consistency

The diagrams use consistent theming (theme: mc, look: classic) which is good, but consider:

• Adding version comments if specific Mermaid features are required
• Testing rendering in common viewers (GitHub, GitLab, VS Code)
• Some empty arrows might not render clearly in all viewers

Minor Issues

• Line consistency: Both files end without trailing newlines (which is fine, but verify your .editorconfig preferences)
• Commenting style: Mix of %% comments and uncommented sections in SERVERLESS_FLOW.md

Testing Recommendations

Since these are documentation files:

1. Verify Mermaid diagrams render correctly on GitHub
2. Review with team members unfamiliar with the system to ensure clarity
3. Validate that the flows match current implementation

Verdict

LGTM with suggestions - The documentation adds significant value. The suggestions above are mostly about polish and clarity rather than blocking issues. Consider addressing the empty message arrows and adding contextual documentation before merging.

---

Review generated with assistance from Claude Code

[claude]

PR Review: Documentation Updates for Rivet Engine

This PR adds comprehensive documentation for key Rivet engine components. The documentation is well-structured and provides valuable insights into the system architecture. Here's my detailed review:

Strengths

Excellent Visual Documentation

• The Mermaid sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md provide clear visualizations of complex workflows
• The "Messy Serverless Flow" diagram is particularly valuable as it documents edge cases and race conditions that developers need to understand

Comprehensive Coverage

• Documents critical components: Guard (routing/proxying), actor lifecycle, hibernating websockets, runner shutdown, and serverless flows
• The terminology document provides a helpful reference for understanding abbreviations used throughout

Clear Structure

• Documentation is well-organized in docs/engine/ directory
• Cross-references between docs (e.g., GUARD.md → HIBERNATING_WS.md) help readers navigate

Issues & Suggestions

1. Empty Documentation Files

Severity: Medium

Three files are created but left empty:

• docs/engine/ACTOR_KV.md
• docs/engine/GASOLINE.md
• docs/engine/GATEWAY.md

Recommendation: Either add content to these files or remove them from this PR. Empty files can be confusing for readers. Based on the existing docs:

• GASOLINE.md should document the workflow engine mentioned in CLAUDE.md
• GATEWAY.md appears to be a duplicate concept with GUARD.md - clarify the distinction or merge

2. Typo in HIBERNATING_WS.md

Severity: Low

Line 25:

- When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hiberating requests are still active.

Should be: hibernating (not hiberating)

3. Inconsistent Terminology

Severity: Low

GUARD.md line 8 uses "Gateway" in the title "Rivet Guard" context, but the document differentiates between Guard and Gateway. From reading the docs:

• Guard = HTTP routing/proxying layer
• Gateway = Used in sequence diagrams as a participant (appears to be the same as Guard?)

Recommendation: Add clarification to TERMINOLOGY.md about Guard vs Gateway distinction, or use consistent naming in diagrams.

4. CLAUDE.md Change Context Missing

Severity: Low

The PR removes these lines from CLAUDE.md:

# When adding a new package to the workspace
deno run -A scripts/cargo/update_workspace.ts

Question: Is this script no longer needed, or was this workflow changed? Consider adding a commit message explanation or updating relevant documentation if the workflow changed.

5. Incomplete Step in HIBERNATING_WS.md

Severity: Low

Line 14 (step 9) starts with a bare numbered list without context:

9. 
	- If the actor is awoken from any other source...

Recommendation: Add a brief intro sentence after "9." like:

9. When the websocket is hibernating, the following can occur:
	- If the actor is awoken from any other source...

6. SERVERLESS.md Commented-Out Code

Severity: Low

Lines 68-83 in "Ideal Serverless Flow" contain commented-out Mermaid code for actor sleep flow.

Recommendation: Either:

• Uncomment if this flow should be documented
• Remove if it's not part of the "ideal" flow
• Add a comment explaining why it's omitted (e.g., "Actor sleep flow omitted for clarity - see Messy Serverless Flow")

Minor Suggestions

1. GUARD.md line 36: "is websocket" → "its websocket"

   - The runner sends HTTP responses and websocket messages back to Rivet through is websocket via the runner protocol

2. Cross-reference consistency: Consider adding a header comment in each file linking to related docs, e.g.:

   # Hibernating Websockets
   
   Related: [GUARD.md](GUARD.md), [ACTOR_LIFECYCLE.md](ACTOR_LIFECYCLE.md)

3. RUNNER_SHUTDOWN.md: Consider adding a sequence diagram similar to other docs for visual consistency

Performance, Security & Testing

Not Applicable: This PR only adds documentation files, so there are no code changes to review for performance, security vulnerabilities, or test coverage.

Summary

This is a valuable documentation addition that will help developers understand Rivet's complex distributed actor system. The main action items are:

1. ✅ Fix the typo: "hiberating" → "hibernating"
2. ✅ Fix the grammar: "through is websocket" → "through its websocket"
3. 🔧 Decide whether to add content or remove empty .md files
4. 📝 Clarify Guard vs Gateway terminology
5. 🧹 Clean up commented-out Mermaid code in SERVERLESS.md

Overall: Approve with minor changes recommended

Great work documenting these complex flows! 🎉

[claude]

Code Review: Documentation Updates

Overview

This PR adds comprehensive technical documentation for core Rivet Engine components. The additions are valuable for understanding the system architecture, but there are several issues to address.

---

Critical Issues

1. Empty GASOLINE.md File

Location: docs/engine/GASOLINE.md
Issue: The file is completely empty (0 bytes added according to the diff).

According to CLAUDE.md:32, Gasoline is described as "Workflow Engine" which "Handles complex multi-step operations with reliability and observability." This is a critical component that should be documented.

Recommendation: Either:

• Add proper documentation for Gasoline/workflow engine
• Remove this file from the PR until content is ready
• Add a TODO comment indicating planned content

---

Issues to Fix

2. Typo: "hiberating" → "hibernating"

Location: docs/engine/HIBERNATING_WS.md:25

- When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hiberating requests are still active.
+ When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hibernating requests are still active.

3. Grammar Error: "through is websocket" → "through its websocket"

Location: docs/engine/GUARD.md:36

- The runner sends HTTP responses and websocket messages back to Rivet through is websocket via the runner protocol
+ The runner sends HTTP responses and websocket messages back to Rivet through its websocket via the runner protocol

4. Incomplete Text: "how maximum returned keys" → "how many maximum returned keys"

Location: docs/engine/ACTOR_KV.md:32

- Limit - how maximum returned keys
+ Limit - maximum number of returned keys

---

Documentation Quality Suggestions

5. ACTOR_KV.md - Clarify Version Metadata

Location: docs/engine/ACTOR_KV.md:9

The document states: "version being a string byte array denoting the version of the Rivet Engine"

Question: Is this the Rivet Engine version or a version number for the KV entry itself (for optimistic concurrency control)? This should be clarified since version fields in KV stores are typically used for conflict detection.

6. HIBERNATING_WS.md - Step 9 Formatting

Location: docs/engine/HIBERNATING_WS.md:14

Step 9 has unusual formatting with no introductory text:

9. 
	- If the actor is awoken from any other source, go to step 6.

Recommendation:

9. Once hibernating, one of the following occurs:
	- If the actor is awoken from any other source, go to step 6. We do not send a ToClientWebSocketOpen message in this case

7. ACTOR_LIFECYCLE.md - Empty Message Arrows

Multiple Locations: Lines 40-41, 44-45, 53-54, 64-65, etc.

The Mermaid diagrams contain many unlabeled arrows like:

RWF->>RWS:
RWS->>R:

Loading

Recommendation: Add message labels for clarity, e.g.:

RWF->>RWS: Proxy StartActor
RWS->>R: Send StartActor command

Loading

This applies to multiple diagrams throughout.

8. Missing Context for CLAUDE.md Change

The PR removes:

# When adding a new package to the workspace
deno run -A scripts/cargo/update_workspace.ts

Question: Was this script removed from the codebase? Or is this workflow no longer necessary? Consider explaining in the PR description or commit message.

---

Strengths

✅ Excellent visual documentation - The Mermaid sequence diagrams effectively communicate complex distributed system flows
✅ Edge case coverage - The "Messy Serverless Flow" documents important race conditions and edge cases
✅ Good cross-referencing - Documents reference each other appropriately
✅ Terminology guide - TERMINOLOGY.md provides helpful abbreviation reference
✅ Practical examples - GUARD.md shows concrete routing patterns with headers and paths

---

Recommendations for Future Work

1. Add a README in docs/engine/ explaining the documentation structure and recommended reading order
2. Expand TERMINOLOGY.md with Guard vs Gateway clarification (both terms are used somewhat interchangeably)
3. Consider adding troubleshooting sections to key documents showing common failure modes
4. Add examples to ACTOR_KV.md showing actual usage patterns

---

Verdict

Needs Changes - Please address the critical issue (#1 empty GASOLINE.md) and typos/grammar errors (#2-4) before merging. The documentation quality suggestions can be addressed in follow-up PRs if preferred.

Overall, this is valuable technical documentation that will help developers understand Rivet's architecture. Thank you for taking the time to document these complex systems!

---

Reviewed per repository guidelines in CLAUDE.md

[claude]

PR Review: Documentation Updates

This PR adds comprehensive documentation for the Rivet Engine's actor system and workflow architecture. Overall, this is excellent documentation that will greatly help developers understand the system. Here's my detailed feedback:

Strengths

1. Excellent Visual Documentation: The Mermaid sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md are incredibly helpful for understanding complex distributed system flows.

2. Comprehensive Coverage: The docs cover critical aspects of the system including actor lifecycle, KV storage, hibernating websockets, and serverless flows.

3. Practical Examples: The "Messy Serverless Flow" diagram is particularly valuable as it shows real-world race conditions and edge cases, not just the happy path.

4. Clear Terminology: TERMINOLOGY.md provides essential definitions that help disambiguate concepts like "Runner WF" vs "Actor WF".

Issues & Suggestions

1. Typo in HIBERNATING_WS.md (Line 25)

File: docs/engine/HIBERNATING_WS.md:25

which hiberating requests are still active.

Should be: "hibernating" (missing 'n')

2. Grammar Issue in GUARD.md (Line 36)

File: docs/engine/GUARD.md:36

through is websocket via the runner protocol

Should be: "through its websocket via the runner protocol"

3. Incomplete Sentence in HIBERNATING_WS.md (Line 14)

File: docs/engine/HIBERNATING_WS.md:14

Step 9 has a numbered item that appears incomplete:

9. 
	- If the actor is awoken from any other source, go to step 6...

The "9." should probably be removed since it's immediately followed by bullet points, or the structure should be clarified.

4. Missing Grammar Article in HIBERNATING_WS.md (Line 8)

File: docs/engine/HIBERNATING_WS.md:8

Guard sends the runner a ToClientWebSocketOpen message a via the runner protocol

Should be: "Guard sends the runner a ToClientWebSocketOpen message via the runner protocol" (remove extra "a")

5. TODO Comment in Schema File

File: engine/sdks/schemas/runner-protocol/v3.bare:15

There's a TODO comment:

# TODO: Rename to update_ts
createTs: i64

While the TODO is helpful, it would be good to track this as an issue or address it soon to avoid confusion about the field's actual meaning (is it create timestamp or update timestamp?). The documentation in ACTOR_KV.md:9 states it's a "create timestamp," but the TODO suggests it should be "update timestamp" which would be more accurate for a KV system.

6. Inconsistency in ACTOR_KV.md (Line 32)

File: docs/engine/ACTOR_KV.md:32

- Limit - how maximum returned keys

Should be: "Limit - the maximum number of returned keys" or "Limit - maximum number of returned keys"

7. Minor CLAUDE.md Removal

The removal of the deno run -A scripts/cargo/update_workspace.ts command from CLAUDE.md appears intentional (likely automated now or deprecated). This is fine if the script is no longer needed.

Documentation Quality Suggestions

1. Cross-References

Consider adding more cross-references between documents. For example:

• ACTOR_LIFECYCLE.md could reference ACTOR_KV.md for KV operations
• GUARD.md could link to ACTOR_LIFECYCLE.md for full request flow context

2. Error Handling Documentation

ACTOR_KV.md mentions that operations can return errors, but it would be helpful to document:

• Common error scenarios (e.g., key not found, storage full, etc.)
• Whether errors are retryable
• Error handling best practices

3. Performance Considerations

Consider adding a section about:

• KV operation performance characteristics (latency, throughput)
• Best practices for batch operations vs individual operations
• Limitations (max key/value sizes, max number of keys, etc.)

4. Ordering Guarantees

File: docs/engine/ACTOR_KV.md:68

The docs mention:

Rivet makes no attempt to order or deduplicate the responses to KV requests

This is important! Consider making this more prominent (perhaps in a warning callout) since developers might assume ordering guarantees.

Security & Performance Notes

No security or performance concerns identified in this documentation-only PR. The docs appropriately warn about dangerous operations like Drop which deletes all KV data.

Test Coverage

N/A - This is a documentation-only PR with no code changes (except a minor schema TODO comment).

Overall Assessment

This is high-quality documentation that significantly improves the project's developer experience. The issues identified are minor (mostly typos and grammar). I recommend:

1. Fix the typos and grammar issues listed above
2. Consider whether the createTs → update_ts rename should happen now or be tracked as a separate issue
3. Merge after addressing the typos

Great work on these docs! The sequence diagrams especially will be invaluable for onboarding and debugging.

[claude]

PR Review: Documentation Updates

Summary

This PR adds comprehensive internal documentation for the Rivet Engine architecture, covering actor lifecycle, KV storage, serverless flows, and various subsystems. The documentation is well-structured and provides valuable insight into the system's behavior.

Strengths

1. Clear Structure

• Good separation of concerns with each doc focusing on a specific area
• TERMINOLOGY.md provides helpful context for understanding the other docs
• Logical flow from basic concepts to complex flows

2. Visual Documentation

• Excellent use of Mermaid diagrams for lifecycle flows
• The "Ideal" vs "Messy" serverless flow comparison is particularly helpful for understanding edge cases
• Sequence diagrams clearly show interactions between components

3. Comprehensive Coverage

• Actor KV operations are well-documented with inputs/outputs
• Runner shutdown scenarios cover both self-initiated and Rivet-initiated cases
• Hibernating websockets lifecycle is thorough

Issues & Suggestions

1. Typo in HIBERNATING_WS.md (docs/engine/HIBERNATING_WS.md:25)

hiberating → hibernating

Should be: "which hibernating requests are still active"

2. Grammar issue in ACTOR_KV.md (docs/engine/ACTOR_KV.md:32)

Limit - how maximum returned keys

Should be: "Limit - the maximum number of returned keys" or "Limit - how many keys to return"

3. TODO Comment in Schema (engine/sdks/schemas/runner-protocol/v3.bare:15)

The TODO comment about renaming createTs to update_ts should be addressed:

# TODO: Rename to update_ts
createTs: i64

If this field represents when the key was last updated (not created), the name is misleading. Either:

• Rename it now to update_ts if appropriate
• Remove the TODO and clarify that it's intentionally createTs
• Add a separate update_ts field if both are needed

According to ACTOR_KV.md:9, it's described as "create timestamp", which conflicts with the TODO suggesting it should be "update_ts".

4. Missing Cross-References

Several docs reference each other, but not all connections are made:

• GUARD.md references HIBERNATING_WS.md ✓
• HIBERNATING_WS.md references GUARD.md ✓
• GASOLINE.md mentions location but could link to TERMINOLOGY.md for term definitions
• Consider adding "See also:" sections at the end of docs

5. Incomplete Numbered List (docs/engine/HIBERNATING_WS.md:14)

Step 9 has bullet points that should be sub-numbered (9a, 9b, 9c) for clarity:

9. 
	- If the actor is awoken from any other source, go to step 6...
	- If the client sends a websocket message during websocket hibernation, go to step 2
	- If the client closes the websocket, the actor is rewoken...

6. CLAUDE.md Change

The removal of the deno run -A scripts/cargo/update_workspace.ts command should be mentioned in the PR description. If this script is no longer needed, consider:

• Documenting why it was removed
• Ensuring the script file itself is removed if obsolete
• Checking if any CI/CD processes relied on this

7. Path Reference Clarity (docs/engine/GASOLINE.md:3)

Gasoline (at engine/packages/gasoline)

This path doesn't appear to exist in the repository structure. Should verify this path or clarify if it's:

• packages/common/gasoline/ (based on CLAUDE.md architecture section)
• A future location
• Needs updating

8. Metadata Naming Consistency (docs/engine/ACTOR_KV.md:9)

The doc states metadata includes "create timestamp" but based on the TODO in v3.bare, this might actually track update time. Clarify the semantic meaning:

• Is this when the key was first created?
• Is this when the value was last updated?
• Do we need both timestamps?

Minor Suggestions

9. Add Version Info to KV Metadata

The docs mention "version being a string byte array denoting the version of the Rivet Engine" (ACTOR_KV.md:9). Consider documenting:

• What format this version takes (semver? git hash?)
• Why the engine version is stored with each key
• Whether this is used for migration/compatibility checks

10. Error Handling Details

ACTOR_KV.md:64 mentions errors include a "message string" but doesn't specify:

• Error codes or categories
• Retry behavior
• Whether errors are transient or permanent

11. Concurrency Semantics

ACTOR_KV.md:68 states "Rivet makes no attempt to order or deduplicate the responses" but doesn't mention:

• What happens with concurrent writes to the same key
• Last-write-wins semantics
• Any consistency guarantees

Security Considerations

No security issues identified. The KV operations are scoped to individual actors (private storage), which provides good isolation.

Performance Considerations

1. KV Batch Operations: Good that Get, Put, and Delete support lists of keys for batching
2. Drop Operation: Correctly warns about caution, though could benefit from noting this might be expensive for large stores
3. List Operation: No mention of pagination for very large key sets beyond the limit parameter

Test Coverage

This PR is documentation-only, so test coverage doesn't apply directly. However, consider:

• Adding example code snippets to docs showing API usage
• Creating integration tests that validate the documented flows
• Ensuring the Mermaid diagrams render correctly in your documentation viewer

Recommendations

High Priority:

1. Fix the typo: "hiberating" → "hibernating"
2. Fix the grammar: "how maximum" → "maximum number of" or "how many"
3. Resolve the TODO comment about createTs vs update_ts
4. Verify and correct the Gasoline path reference

Medium Priority:
5. Improve the numbered list formatting in HIBERNATING_WS.md step 9
6. Add cross-references between related documents
7. Document the reason for removing the update_workspace.ts command

Low Priority:
8. Add more details about KV error handling and concurrency semantics
9. Consider adding code examples to make the docs more actionable

Conclusion

This is valuable documentation that will help developers understand the Rivet Engine architecture. The Mermaid diagrams are particularly helpful. With the minor fixes suggested above, this will be excellent internal documentation.

Approved with suggested changes! 🎉

[claude]

PR Review: Documentation Updates

Summary

This PR adds comprehensive internal documentation for the Rivet Engine architecture, covering actor lifecycle, KV storage, serverless flows, websocket hibernation, and more. Overall, this is excellent documentation that will help developers understand the complex interactions between various components.

Positive Aspects

✅ Excellent visual aids: The Mermaid sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md are particularly helpful for understanding complex flows

✅ Comprehensive coverage: Documents cover key architectural components (Guard, Gasoline, Pegboard interactions)

✅ Clear structure: Documents are well-organized with appropriate sections and hierarchy

✅ Practical examples: The "Messy Serverless Flow" diagram is excellent - showing edge cases and race conditions is very valuable

Issues & Recommendations

1. Typo in HIBERNATING_WS.md:25

Location: docs/engine/HIBERNATING_WS.md:25

Issue: "hiberating" should be "hibernating"

-When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hiberating requests are still active.
+When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hibernating requests are still active.

2. Grammar issue in ACTOR_KV.md:32

Location: docs/engine/ACTOR_KV.md:32

Issue: "how maximum returned keys" is unclear

-	- Limit - how maximum returned keys
+	- Limit - maximum number of returned keys

3. Incomplete step in HIBERNATING_WS.md:14

Location: docs/engine/HIBERNATING_WS.md:14

Issue: Step 9 starts a numbered list but doesn't have a number

-9. 
-	- If the actor is awoken from any other source, go to step 6. We do not send a ToClientWebSocketOpen message in this case
+9. Handle wake scenarios:
+	- If the actor is awoken from any other source, go to step 6. We do not send a ToClientWebSocketOpen message in this case

4. Schema comment needs clarification

Location: engine/sdks/schemas/runner-protocol/v3.bare:15

Issue: The TODO comment about renaming createTs to update_ts could be confusing

Recommendation: If this is truly a create timestamp (as the metadata description states "create timestamp of the key"), the TODO might be incorrect. If it tracks updates, it should be renamed. Consider clarifying the intent or removing the TODO if it's not actionable.

5. Inconsistent terminology in GUARD.md:36

Location: docs/engine/GUARD.md:36

Issue: "through is websocket" should be "through its websocket"

-The runner sends HTTP responses and websocket messages back to Rivet through is websocket via the runner protocol
+The runner sends HTTP responses and websocket messages back to Rivet through its websocket via the runner protocol

6. Missing context in GASOLINE.md:3

Location: docs/engine/GASOLINE.md:3

Issue: The path reference is slightly ambiguous

-Gasoline (at engine/packages/gasoline) is the durable execution engine running most persistent things on Rivet Engine.
+Gasoline (at `packages/common/gasoline/`) is the durable execution engine running most persistent things on Rivet Engine.

7. CLAUDE.md change needs verification

Location: CLAUDE.md:43-45

Issue: Removed reference to deno run -A scripts/cargo/update_workspace.ts

Question: Was this script removed or is this guidance no longer needed? If the script still exists, developers might need to know about it.

Documentation Quality Suggestions

Add cross-references

Consider adding a top-level docs/engine/README.md that indexes all these documents and shows how they relate to each other. For example:

• Start with TERMINOLOGY.md
• Then GASOLINE.md for understanding the workflow engine
• Then GUARD.md for the routing layer
• Then ACTOR_LIFECYCLE.md for the main flow
• etc.

Expand GASOLINE.md

The GASOLINE.md document is quite brief compared to others. Consider adding:

• Example workflow scenarios
• How workflows relate to Actor WF and Runner WF specifically
• Retry and replay semantics
• When to use signals vs messages

Add error handling documentation

While ACTOR_KV.md mentions errors, consider documenting:

• Common error scenarios across all operations
• Error propagation between components
• Retry policies and timeout behaviors

Security & Performance Considerations

✅ No security concerns identified - These are internal documentation files

✅ No performance impact - Documentation only

Test Coverage

Not applicable for documentation-only changes, but consider:

• Adding inline code examples that could be turned into integration tests
• Documenting test scenarios alongside the flows

Conclusion

This is high-quality documentation that significantly improves the codebase's maintainability. The main issues are minor typos and grammatical errors. I recommend:

1. Fix the typos identified above
2. Clarify the TODO in the BARE schema
3. Consider adding a top-level index document
4. Merge after addressing typos

Great work on documenting these complex interactions! 🎉

[claude]

PR Review: Documentation Updates

Thank you for these documentation additions! This is a valuable contribution that will help developers understand the Rivet Engine architecture.

Strengths

✅ Comprehensive Coverage: The documentation covers critical components including actor lifecycle, KV storage, Guard routing, hibernating websockets, and serverless flows.

✅ Visual Diagrams: The Mermaid sequence diagrams are excellent for visualizing complex workflows.

✅ Clear Structure: Each document is well-organized with logical sections and headings.

Issues Found

1. Typo in HIBERNATING_WS.md (Line 25)

"hiberating" should be "hibernating"

2. Grammar Issue in ACTOR_KV.md (Line 32)

"Limit - how maximum returned keys" should be "the maximum number of returned keys"

3. Incomplete Sentence in HIBERNATING_WS.md (Line 8)

Extra "a" in "message a via" - should be "message via"

4. Grammar Issue in GUARD.md (Line 36)

"through is websocket" should be "through its websocket"

5. Commented Out Code in SERVERLESS.md (Lines 68-83)

Consider removing or adding a comment explaining why it's kept

Suggestions for Improvement

1. Cross-References: Add more explicit links between related documents
2. GASOLINE.md: Expand with code examples and more detail on replay mechanism
3. Error Handling: Add error codes and common failure scenarios to ACTOR_KV.md
4. Security: Consider documenting authentication, rate limiting, and data isolation
5. Consistency: Ensure consistent terminology usage throughout

Overall Assessment

This is a solid documentation contribution. The diagrams are particularly valuable. Once the minor typos are fixed, this will be ready to merge.

Recommendation: Approve with minor changes requested (fix typos/grammar).

[claude]

Documentation Review

This PR adds comprehensive documentation for the Rivet Engine architecture. Overall, this is excellent work that will significantly help developers understand the system. Here's my detailed feedback:

Strengths ✅

1. Well-structured documentation - Each document focuses on a specific aspect of the system with clear sections
2. Excellent use of Mermaid diagrams - The sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md are particularly valuable for understanding complex flows
3. Clear terminology definitions - TERMINOLOGY.md provides essential context for newcomers
4. Cross-references - Good use of references between docs (e.g., GUARD.md → HIBERNATING_WS.md)

Issues to Address 🔧

ACTOR_KV.md

• Line 32: Typo - "how maximum returned keys" should be "the maximum number of returned keys"
• Line 9: Consider clarifying "version being a string byte array" - is this actually a byte array representation of a string, or just metadata? The wording is slightly confusing

HIBERNATING_WS.md

• Line 8: Extra "a" - "message a via" should be "message via"
• Line 25: Typo - "hiberating" should be "hibernating"
• Step 9: The list item appears incomplete - there's a numbered item with sub-bullets but the flow could be clearer. Consider reformatting this section

GASOLINE.md

• Line 3: Path reference "engine/packages/gasoline" - should verify this matches the actual codebase structure. Based on the CLAUDE.md conventions, this should be "packages/common/gasoline/" (as mentioned in the Architecture section)

GUARD.md

• Line 36: Typo - "through is websocket" should be "through its websocket"

v3.bare schema change

• Good catch on the TODO comment for renaming createTs to update_ts. However, this reveals a potential inconsistency:

  • The field name createTs suggests creation time
  • The TODO suggests renaming to update_ts which implies modification time
  • The ACTOR_KV.md documentation (line 9) calls it "create timestamp"

  Question: Is this field actually tracking when the key was created or when it was last updated? This should be clarified before renaming, as the semantics matter for KV operations.

Documentation Quality Improvements 📚

1. SERVERLESS.md: The "Messy Serverless Flow" is excellent for showing edge cases, but consider adding a brief intro paragraph explaining why this flow exists and what scenarios trigger it

2. ACTOR_LIFECYCLE.md: Consider adding brief annotations explaining what "critical" sections represent in the Mermaid syntax for readers unfamiliar with it

3. Cross-referencing: Consider adding a main INDEX.md or README.md in docs/engine/ that links to all these documents with brief descriptions

4. RUNNER_SHUTDOWN.md: Very concise and clear. No issues here.

Code Change Review

CLAUDE.md change (removing update_workspace.ts reference):

• ✅ Appropriate removal if the script is no longer needed
• Consider whether this script should be removed from the repository entirely, or if it's just not needed in the standard workflow

Security & Performance

• ✅ No security concerns - this is documentation only
• ✅ No performance impact
• ✅ No test coverage needed for documentation

Recommendations

1. Fix the typos mentioned above
2. Clarify the KV metadata timestamp semantics before merging
3. Verify the Gasoline path reference
4. Consider adding a docs/engine/README.md index file
5. After addressing the TODO in v3.bare, update ACTOR_KV.md documentation accordingly

Overall Assessment

This is high-quality documentation that follows good technical writing practices. The issues are minor and mostly cosmetic. The content is accurate and will be very valuable for onboarding and reference. ⭐

Recommended action: Request minor revisions for typos and clarifications, then approve.

[claude]

PR Review: Documentation Updates

Great work on documenting the Rivet Engine architecture! This documentation will be very valuable for understanding the complex interactions between components. Here's my feedback:

✅ Strengths

1. Comprehensive Coverage: The documentation covers key architectural components (actors, runners, serverless, Guard, Gasoline) with good detail
2. Visual Aids: The Mermaid sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md are excellent for understanding complex flows
3. Cross-references: Good use of cross-references between documents (e.g., "see GUARD.md", "see HIBERNATING_WS.md")
4. Practical Examples: The "Messy Serverless Flow" diagram is particularly valuable as it shows real-world edge cases

📝 Documentation Issues

1. ACTOR_KV.md - Minor clarity issues

• Line 32: Typo - "how maximum returned keys" should be "the maximum number of returned keys"
• Line 9: The metadata description says "create timestamp of the key" but the schema shows createTs represents when the value was set (not the key). Consider clarifying this is the "value set timestamp" or "last update timestamp"
• The schema change adds a TODO comment about renaming createTs to update_ts, which aligns with this confusion

2. HIBERNATING_WS.md - Typo

• Line 25: "hiberating" should be "hibernating"

3. GASOLINE.md - Path inconsistency

• Line 3: States Gasoline is at "engine/packages/gasoline"
• This should be verified - based on the Rivet monorepo structure mentioned in CLAUDE.md, it's likely at packages/common/gasoline/ or similar
• Recommendation: Use a relative path from the repo root or verify the actual location

4. GUARD.md - Minor grammar

• Line 36: "through is websocket" should be "through its websocket"

5. TERMINOLOGY.md - Consistency

• Good addition! Consider adding these terms that appear in other docs but aren't defined:
  • UDB (Universal Database) - mentioned in HIBERNATING_WS.md
  • NATS - mentioned in CLAUDE.md architecture section
  • RivetKit - mentioned in HIBERNATING_WS.md and ACTOR_KV.md

6. Numbered List Formatting (HIBERNATING_WS.md, RUNNER_SHUTDOWN.md)

• HIBERNATING_WS.md line 14: Step 9 has sub-bullets which might be clearer as 9a, 9b, 9c or labeled with their conditions
• The current format with bullets under step 9 works but could be more scannable

🔧 Schema Change (v3.bare)

The TODO comment addition on line 15 is good:

# TODO: Rename to update_ts
createTs: i64

Recommendation: Since you're already touching this area, consider:

1. Creating a follow-up issue/task to actually rename this field (breaking change, needs coordination)
2. Updating ACTOR_KV.md to mention that createTs is actually the "update timestamp" or "last modified timestamp" to match the TODO

🎯 CLAUDE.md Change

Line 43-45 removal:

-# When adding a new package to the workspace
-deno run -A scripts/cargo/update_workspace.ts

✅ This is fine if the script is no longer needed or has been replaced. However:

• Verify that the script file still exists in the repo
• If it does exist but is deprecated, consider adding a comment about what replaced it
• If developers might still look for this command, consider leaving a note about the change

🔒 Security Considerations

No security concerns - this is documentation only.

🧪 Testing

Not applicable for documentation changes, but consider:

• Verifying that all Mermaid diagrams render correctly in your documentation viewer
• Checking all cross-references resolve correctly

📊 Overall Assessment

This is a solid documentation PR that will significantly help developers understand the Rivet Engine architecture. The issues identified are minor and mostly cosmetic.

Recommendation: ✅ Approve with minor fixes suggested above

Action Items

• Fix typos: "how maximum" → "the maximum number of", "hiberating" → "hibernating", "is websocket" → "its websocket"
• Verify and correct Gasoline path in GASOLINE.md
• Consider adding UDB, NATS, and RivetKit to TERMINOLOGY.md
• Clarify the createTs vs update_ts naming in ACTOR_KV.md or wait for schema rename

[claude]

PR Review: Documentation Update

Summary

This PR adds comprehensive documentation for the Rivet Engine's architecture and core concepts. Overall, this is an excellent contribution that will significantly help developers understand the system. The documentation is well-structured with clear explanations and helpful sequence diagrams.

Strengths

✅ Excellent use of Mermaid diagrams - The sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md provide clear visual representations of complex flows

✅ Cross-referencing - Good use of cross-references between docs (e.g., GUARD.md references HIBERNATING_WS.md)

✅ Practical organization - Separating "Ideal" and "Messy" serverless flows helps readers understand both the happy path and edge cases

✅ Implementation details - Including details like request IDs in KV operations (ACTOR_KV.md:68) and the lack of ordering guarantees

Issues & Suggestions

Documentation Quality

ACTOR_KV.md:32 - Typo/grammar issue:

- Limit - how maximum returned keys
+ Limit - maximum number of returned keys

ACTOR_KV.md:9 - Clarity issue with metadata description:
The statement "version and create timestamp of the key" is slightly misleading - the metadata is associated with the value, not the key itself. Consider:

- Every set KV value contains metadata which includes the version and create timestamp of the key
+ Every set KV value contains metadata which includes the version and creation timestamp

HIBERNATING_WS.md:8 - Minor typo:

- Guard sends the runner a ToClientWebSocketOpen message a via the runner protocol
+ Guard sends the runner a ToClientWebSocketOpen message via the runner protocol

HIBERNATING_WS.md:25 - Spelling error:

- it contains information about which hiberating requests are still active
+ it contains information about which hibernating requests are still active

HIBERNATING_WS.md:14 - The step numbering is inconsistent. Step 9 has bullet points but doesn't clearly indicate what triggers each scenario. Consider restructuring for clarity.

GASOLINE.md:6 - The explanation could be clearer:

- Workflows - Similar to the concept of actors (not Rivet Actors) which can sleep (be removed from memory) when not in use
+ Workflows - Similar to the actor pattern (distinct from Rivet Actors) which can sleep (be removed from memory) when not in use

Code Issue

engine/sdks/schemas/runner-protocol/v3.bare:15 - The TODO comment is noted:

# TODO: Rename to update_ts
createTs: i64

This should probably be addressed in a follow-up PR for consistency with the timestamp naming convention mentioned in CLAUDE.md (using past tense verbs with _at suffix).

Missing Information

1. ACTOR_KV.md - Consider adding:

   • Size limits for keys and values
   • Performance characteristics of different operations
   • Example use cases
   • How to handle the case when a key doesn't exist in Get operation (currently only mentioned briefly on line 22)

2. TERMINOLOGY.md - Missing definitions that appear in other docs:

   • UDB (Universal Database) - mentioned in HIBERNATING_WS.md
   • What "Bump" means in the serverless context
   • Workflow vs Worker distinction

3. HIBERNATING_WS.md - The keepalive mechanism mentioned on line 21 could benefit from:

   • Keepalive interval details
   • What happens if keepalive fails

4. RUNNER_SHUTDOWN.md - Missing information:

   • What is the "runner lost threshold" mentioned in both scenarios?
   • How long is the grace period?
   • What happens to in-flight requests during shutdown?

CLAUDE.md Change

CLAUDE.md:43 - The removal of the update_workspace.ts script reference is good for cleanup, but ensure this script is either:

• No longer needed (confirm with team)
• Replaced by another mechanism
• Documented elsewhere if still relevant

Architecture & Design

No architectural concerns - this is documentation only and doesn't introduce code changes.

Security

No security concerns for this documentation-only PR.

Test Coverage

Not applicable - documentation changes don't require tests.

Recommendations

1. High Priority: Fix the typos and grammar issues listed above
2. Medium Priority: Address the inconsistent step numbering in HIBERNATING_WS.md
3. Low Priority: Consider expanding the documentation with the missing information suggested above in future PRs
4. Future Work: Create a follow-up PR to address the TODO comment in v3.bare for the timestamp field naming

Overall Assessment

This is a valuable addition to the codebase. The documentation is comprehensive and well-written. With the minor corrections suggested above, this will be an excellent reference for developers working on or with the Rivet Engine.

Recommendation: Approve with minor revisions for typos.

[claude]

PR Review: Documentation Updates

This PR adds comprehensive documentation for Rivet Engine's core components and workflows. Overall, this is a valuable addition to the codebase.

Strengths

1. Comprehensive coverage of critical components (actor lifecycle, KV storage, serverless flows, Guard routing)
2. Excellent use of Mermaid sequence diagrams
3. Well-organized structure with clear sections
4. Good implementation details and protocol specifics

Documentation Quality Issues Found

ACTOR_KV.md

• Line 32: Typo - "how maximum returned keys" should be "the maximum number of returned keys"
• Line 9: Clarify if "create timestamp" means first created or last updated (TODO in v3.bare suggests update_ts)

HIBERNATING_WS.md

• Line 25: Typo - "hiberating" should be "hibernating"
• Line 14: Item 9 appears incomplete

GUARD.md

• Line 36: Grammar - "through is websocket" should be "through its websocket"

SERVERLESS.md

• Lines 68-83: Consider removing commented-out section if not needed

GASOLINE.md

• Line 3: Verify path "engine/packages/gasoline" is correct

TERMINOLOGY.md

• Consider adding more terms (UDB, Pegboard, etc.)

Code Changes

• CLAUDE.md: Removing outdated Deno script reference is appropriate
• v3.bare: TODO comment is good; create follow-up issue for createTs to update_ts rename

Overall Assessment

Quality: 4/5 - High-quality with minor improvements needed
Completeness: 5/5 - Covers all major components and edge cases

Recommendations

1. Fix typos mentioned above
2. Add cross-links between related docs
3. Create docs/engine/README.md index
4. Verify Gasoline path reference
5. Create issue for createTs rename

Security, Performance, Testing

• No security concerns (documentation only)
• No performance impact (documentation only)
• No test coverage needed (documentation only)

Great work documenting these complex systems!

[claude]

PR Review: Documentation Updates

This PR adds comprehensive documentation for several critical Rivet Engine components. Overall, this is excellent documentation that will greatly help developers understand the system architecture. Below is my detailed review:

Strengths

1. Comprehensive Coverage: The documentation covers key areas - actor lifecycle, KV storage, serverless flows, websocket hibernation, and runner shutdown
2. Visual Documentation: Excellent use of Mermaid diagrams to illustrate complex flows (actor lifecycle, serverless scenarios)
3. Clear Structure: Each document is well-organized with appropriate headers and sections
4. Cross-References: Good use of cross-references between documents (e.g., GUARD.md referencing HIBERNATING_WS.md)
5. Practical Context: The "Messy Serverless Flow" diagram is particularly valuable as it shows real-world edge cases

Issues & Suggestions

1. Typo in HIBERNATING_WS.md:25

Issue: "hiberating" should be "hibernating"

When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hiberating requests are still active.

2. Grammar Issue in ACTOR_KV.md:32

Issue: "how maximum returned keys" should be "the maximum number of returned keys"

- Limit - how maximum returned keys

3. Inconsistent Empty Line in HIBERNATING_WS.md:14

Issue: Line 14 has a numbered list item (9.) with no content, just sub-bullets. Consider either adding context or restructuring:

9. 
	- If the actor is awoken from any other source, go to step 6...

Suggestion:

9. The following events can occur during hibernation:
	- If the actor is awoken from any other source, go to step 6...

4. Grammar Issue in GUARD.md:36

Issue: "through is websocket" should be "through its websocket"

The runner sends HTTP responses and websocket messages back to Rivet through is websocket via the runner protocol

5. Missing Context in GASOLINE.md:3

Issue: The path reference could be more precise. The documentation says "at engine/packages/gasoline" but based on typical Rust workspace structures, this might be:

• packages/common/gasoline/ (more likely based on CLAUDE.md architecture section)

Suggestion: Verify and update the path to match the actual location in the codebase

6. TODO Comment in runner-protocol/v3.bare

Issue: There's a TODO comment added:

# TODO: Rename to update_ts
createTs: i64

This TODO should either be:

• Addressed in this PR (rename the field)
• Tracked in a separate issue
• Removed if not actionable

Since this appears to be a protocol definition that may affect backwards compatibility, it's worth discussing whether this rename should happen now or be tracked separately.

7. TERMINOLOGY.md Consistency

Suggestion: The terminology doc defines abbreviations (WF, WS) but these could be more explicit:

• "Runner WF" → "Runner Workflow (Runner WF)"
• "Runner WS" → "Runner WebSocket (Runner WS)"

This helps readers who encounter the abbreviations first.

8. Missing Details in ACTOR_KV.md:9

Clarification Needed: The documentation states "version being a string byte array denoting the version of the Rivet Engine" but doesn't explain:

• Format of the version string
• Purpose of tracking the engine version with KV entries
• Whether this is used for migration/compatibility

Questions

1. ACTOR_KV.md Request Ordering: Line 68 states "Rivet makes no attempt to order or deduplicate the responses to KV requests" - is this intentional for performance reasons? Should there be a warning about potential race conditions?

2. SERVERLESS.md Commented Code: Lines 68-83 have commented out Mermaid code. Is this intentional to keep the diagram simpler, or should this section be removed entirely?

3. RUNNER_SHUTDOWN.md Threshold: What is the "runner lost threshold" mentioned in lines 9 and 16? This could use a brief explanation or cross-reference.

Minor Observations

1. CLAUDE.md Change: The removal of the update_workspace.ts command is good cleanup (3 lines deleted)
2. Formatting Consistency: All docs use lowercase for log messages per project conventions
3. Documentation Location: All docs are appropriately placed in docs/engine/

Overall Assessment

Quality: High - This documentation significantly improves the codebase's maintainability
Issues Found: Minor (typos, grammar, one TODO)
Recommendation: Approve with minor corrections

The documentation additions are valuable and well-structured. The issues identified are primarily cosmetic (typos/grammar) and easily fixed. The TODO in the protocol definition deserves discussion but doesn't block this PR.

Great work documenting these complex systems! 👍

[claude]

PR Review: Documentation Updates

This PR adds comprehensive documentation for the Rivet Engine architecture. Overall, this is an excellent contribution that significantly improves the project's documentation. The content is clear, well-structured, and includes helpful diagrams.

Strengths

1. Comprehensive Coverage: The documentation covers critical aspects of the system including actor lifecycle, KV storage, Guard/Gateway, hibernating websockets, runner shutdown, and serverless flows.

2. Visual Documentation: The Mermaid sequence diagrams are excellent for understanding complex flows. The "Messy Serverless Flow" diagram is particularly valuable as it documents edge cases.

3. Clear Structure: Each document is focused on a specific topic and cross-references related documentation appropriately.

4. Terminology Guide: The TERMINOLOGY.md file is a great addition for onboarding new developers.

Issues & Suggestions

1. Typo in HIBERNATING_WS.md:25

• Location: docs/engine/HIBERNATING_WS.md:25
• Issue: "hiberating" should be "hibernating"
• Current: which hiberating requests are still active
• Should be: which hibernating requests are still active

2. Inconsistent Wording in ACTOR_KV.md:32

• Location: docs/engine/ACTOR_KV.md:32
• Issue: "how maximum returned keys" is grammatically incorrect
• Should be: "maximum number of returned keys" or "how many keys to return"

3. Schema Documentation Gap

• Location: engine/sdks/schemas/runner-protocol/v3.bare:15
• Issue: The TODO comment about renaming createTs to update_ts suggests a documentation mismatch
• Impact: The ACTOR_KV.md documentation refers to this field as "create timestamp" (line 9), but the TODO suggests it should represent an update timestamp. This semantic difference is important for developers.
• Recommendation: Either update the documentation to clarify that this timestamp is updated on writes, or resolve the TODO by renaming the field to match its actual semantics.

4. Incomplete Section in HIBERNATING_WS.md:14

• Location: docs/engine/HIBERNATING_WS.md:14
• Issue: Step 9 has an incomplete bullet point (just the number "9." with a blank line)
• Current: The step starts at line 14 but the content begins at line 15
• Note: This might be intentional formatting, but it reads oddly

5. Minor: CLAUDE.md Removal

• Location: CLAUDE.md:43
• Change: Removed the note about deno run -A scripts/cargo/update_workspace.ts
• Question: Was this script removed or is this command no longer needed? Consider documenting why this was removed for future reference.

6. GASOLINE.md:3 - Path Reference

• Location: docs/engine/GASOLINE.md:3
• Issue: References path as "engine/packages/gasoline" but the workspace structure should be verified
• Recommendation: Ensure this path is accurate relative to the repository root

Documentation Quality Observations

Strong Points:

• The serverless flow diagrams clearly show both ideal and edge-case scenarios
• Cross-references between documents (e.g., GUARD.md referencing HIBERNATING_WS.md)
• Clear separation of concerns between different architectural components

Suggestions for Future Improvements:

• Consider adding a top-level index document linking to all engine docs
• Add examples or code snippets for the KV operations
• Include error scenarios and recovery patterns in the lifecycle diagrams

Security & Performance

No security concerns identified. This is purely documentation.

Test Coverage

N/A - Documentation only change.

Conclusion

This is a valuable contribution that will significantly help developers understand the Rivet Engine architecture. The only blockers are the minor typos and the semantic clarification needed for the KV metadata timestamp field.

Recommendation: Approve after addressing typos and clarifying the createTs vs update_ts semantics.

[graphite-app]

Merge activity

• Nov 21, 2:40 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Nov 21, 2:42 AM UTC: CI is running for this pull request on a draft pull request (#3515) due to your merge queue CI optimization settings.
• Nov 21, 2:43 AM UTC: Merged by the Graphite merge queue via draft PR: #3515.