docs(actors): explain backward compatibility

[NathanFlurry]

• Explain how to version public actor actions, queues, and events through client and worker version skew.
• Add a checked v1/v2 example and connect API compatibility to worker upgrades and stored-data migrations.
• Add an API compatibility check to the Actors production checklist and correct completable queue guidance.

[railway-app]

🚅 Deployed to the rivet-pr-5844 environment in rivet-frontend

Service	Status	Web	Updated
frontend-cloud	😴 Sleeping (View Logs)	Web	Oct 6, 2026 at 12:55 am UTC
frontend-inspector	😴 Sleeping (View Logs)	Web	Oct 6, 2026 at 12:55 am UTC
kitchen-sink	😴 Sleeping (View Logs)	Web	Oct 6, 2026 at 12:53 am UTC
ladle	✅ Success (View Logs)	Web	Oct 6, 2026 at 12:48 am UTC
mcp-hub	✅ Success (View Logs)	Web	Oct 6, 2026 at 12:46 am UTC
website	❌ Build Failed (View Logs)	Web	Oct 6, 2026 at 12:46 am UTC

[claude]

Review: docs(actors): explain backward compatibility

Docs-only change plus one example. It reads well and follows the CLAUDE.md terminology rules: "Rivet Actor" is capitalized, there are no em dashes, and the sidebar is updated. I have a few suggestions.

Content and accuracy

• The queue correction in queues.mdx and production-checklist.mdx is a behavior claim. It now says completable messages stay stored until complete() and can be redelivered. queue.rs has a complete_message_by_id removal path, which fits that claim. Please still confirm that redelivery happens for an in-process failure, not only after an actor restart. queues.mdx says "after an actor restart" while backward-compatibility.mdx says "can deliver them again". Using the same wording in both places would avoid confusion.
• The "New client, old actor" row says to wait for old workers to drain before making v2 calls. Clients usually cannot observe drain status. Add a practical hint, such as gating v2 calls on a deployed-version signal or a feature flag. Otherwise the advice is hard to act on.
• The example broadcasts both v1.changed and v2.changed on every message. That is fine for a demo. A one-line comment saying that broadcasting both versions keeps old subscribers working would tie the example to the "Expand the actor" step.
• The prose says "decode each body using its corresponding schema" and advises runtime validation of public inputs. The example only relies on the queue message typing and shows no explicit validation. Either say that the schemas validate, or add an example.

Conventions

• The example imports zod directly. Check that it resolves for examples/docs/*, matches other docs examples, and is typechecked in CI.
• Confirm the /actors/docs/actions#nested-actions anchor exists.
• Run the docs checks if the skill: true frontmatter feeds generated artifacts.

Tests
Nothing is executable here apart from the example. A typecheck of versioned-api.ts in CI would cover it.

No security or performance concerns.