fix(ups): formalize subjects

[MasterPtato]

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

[MasterPtato]

This change is part of the following stack:

• chore: deploy patch #4324
  • chore: flatten runtime config #4326
    • fix(api): make actor destroy wait for ack #4327
      • fix(udb): add txn tagging #4328
        • chore: bump rivetkit protocol version #4329
          • fix(ups): formalize subjects #4334 ◀
            • fix(api): properly dedup name list responses #4337
              • fix(pb): clear actor reschedule ts on alloc #4338

_{Change managed by git-spice.}

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Mar 2, 2026 at 8:52 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Mar 2, 2026 at 8:51 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Mar 2, 2026 at 8:42 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 2, 2026 at 8:39 pm
ladle	❌ Build Failed (View Logs)	Web	Mar 2, 2026 at 8:38 pm

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4334

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4334

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4334

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4334

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4334

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4334

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4334

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4334

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4334

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4334

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4334

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4334

commit: f076166

[claude]

PR Review: fix(ups): formalize subjects

Overall this is a clean, well-scoped refactor. The Subject trait is a natural improvement over passing raw &strs everywhere, and the MsgSubject struct is a nice way to defer string formatting while keeping type safety.

---

Issues

1. root() is unused dead code

subject.rs:5

The comment says "Used for metrics" but nothing calls it anywhere in the codebase. As an associated function (not &self), it also cannot be used with trait objects (dyn Subject). Either wire it up to the metrics code or remove it until it is actually needed.

2. subject_cow is computed unconditionally but only used in the local path

pubsub.rs:165

For MsgSubject on the non-local path, this means two separate String allocations per publish: one from subject_cow (unused in that branch) and one inside publish_with_backoff. The subject_cow computation could be deferred into the if use_local branch, or publish_with_backoff could accept a Cow<str> directly to share it.

3. Missing impl Subject for String

There are implementations for &str and &String but not for owned String. Callers with owned subjects must borrow at the call site (&my_string), which may not be obvious. This matters since M::subject() returns String, not &str. If Subject is intended as a general-purpose API, String should be covered too.

4. subscribe_opt still uses a manual format string

message.rs:201

The publish path uses the new typed MsgSubject, but subscribe still constructs a raw string via format!. Functionally equivalent, but the inconsistency is confusing. If MsgSubject is the canonical way to express this subject, subscribe should use it too (or at minimum share a helper).

5. Unrelated file in PR

.claude/skills/git-spice-merge-my-stack/SKILL.md has nothing to do with UPS subject formalization and should be in a separate commit.

---

Minor Notes

• The error handling improvement in message() -- propagating spawn failures as WorkflowError::PublishMessage instead of silently logging -- is a genuine improvement, though spawn only fails on runtime shutdown so the practical impact is minimal.
• MsgSubject::root() calls M::subject() which allocates a String each time. If this is ever wired to metrics on a hot path, the allocation will add up.
• Copy could be derived for MsgSubject since it contains only &str and PhantomData, avoiding the need for explicit Clone in the publish loop.