feat: US-011 - Drop message from wasm BRIDGE_RIVET_ERROR_SCHEMAS cache key

Author: NathanFlurry

rivetkit-typescript/CLAUDE.md

@@ -144,6 +144,7 @@ Cloudflare Workers forbid `setTimeout`, `fetch`, `connect`, and other async I/O
 - Validate wasm-only serve config constraints before converting to core `ServeConfig` or starting registry side effects.
 - Run `pnpm --filter @rivetkit/rivetkit-wasm run check:package` after wasm package export or files changes to verify the published tarball includes the root entrypoint and wasm artifacts.
 - Build `@rivetkit/rivetkit-wasm` with its package-local pinned `wasm-pack` dependency. Do not use `npx -y wasm-pack`.
+- Intern wasm bridged `RivetErrorSchema` values by `(group, code)` only; live per-error messages must stay on `RivetError.message` instead of expanding the schema cache key.
 - Track wasm websocket callback regions in a map keyed by monotonic region IDs and remove entries on end so repeated callbacks do not retain empty slots.
 
 ## Workflow Context Actor Access Guards

rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs

@@ -30,7 +30,7 @@ use wasm_bindgen_futures::{JsFuture, spawn_local};
 
 const BRIDGE_RIVET_ERROR_PREFIX: &str = "__RIVET_ERROR_JSON__:";
 
-type BridgeRivetErrorSchemaKey = (String, String, String);
+type BridgeRivetErrorSchemaKey = (String, String);
 
 static BRIDGE_RIVET_ERROR_SCHEMAS: LazyLock<
 	SccHashMap<BridgeRivetErrorSchemaKey, &'static RivetErrorSchema>,
@@ -2604,11 +2604,7 @@ fn leak_str(value: String) -> &'static str {
 }
 
 fn bridge_rivet_error_schema(payload: &BridgeRivetErrorPayload) -> &'static RivetErrorSchema {
-	let key = (
-		payload.group.clone(),
-		payload.code.clone(),
-		payload.message.clone(),
-	);
+	let key = (payload.group.clone(), payload.code.clone());
 	match BRIDGE_RIVET_ERROR_SCHEMAS.entry_sync(key) {
 		scc::hash_map::Entry::Occupied(entry) => *entry.get(),
 		scc::hash_map::Entry::Vacant(entry) => {
@@ -2790,6 +2786,15 @@ mod tests {
 			.schema
 	}
 
+	fn transport_message(error: &anyhow::Error) -> String {
+		error
+			.chain()
+			.find_map(|cause| cause.downcast_ref::<RivetTransportError>())
+			.expect("bridge error should carry RivetTransportError")
+			.message()
+			.to_owned()
+	}
+
 	#[test]
 	fn parse_bridge_rivet_error_reuses_interned_schema() {
 		let initial_count = BRIDGE_RIVET_ERROR_SCHEMAS.len();
@@ -2818,6 +2823,18 @@ mod tests {
 			parse_bridge_rivet_error(&different_message).expect("bridge error should decode");
 		let schema = transport_schema(&error) as *const RivetErrorSchema;
 
+		assert_eq!(schema, first_schema);
+		assert_eq!(transport_message(&error), "different default message");
+		assert_eq!(BRIDGE_RIVET_ERROR_SCHEMAS.len(), initial_count + 1);
+
+		let different_code = bridge_reason(
+			"wasm_schema_cache_test",
+			"different_code",
+			"different code message",
+		);
+		let error = parse_bridge_rivet_error(&different_code).expect("bridge error should decode");
+		let schema = transport_schema(&error) as *const RivetErrorSchema;
+
 		assert_ne!(schema, first_schema);
 		assert_eq!(BRIDGE_RIVET_ERROR_SCHEMAS.len(), initial_count + 2);
 	}

scripts/ralph/prd.json

@@ -162,6 +162,73 @@
       "priority": 10,
       "passes": true,
       "notes": "Investigated and documented the Env-bearing cleanup path plus constraints in docs-internal/engine/napi-bridge.md. Implementation deferred until a NAPI integration test can verify TSF drain and reference counts."
+    },
+    {
+      "id": "US-011",
+      "title": "Drop message from wasm BRIDGE_RIVET_ERROR_SCHEMAS cache key",
+      "description": "As an operator running a long-lived wasm worker, I want bridged JS error decoding to intern at most one schema per `(group, code)` so callers whose error messages vary per call (timestamps, request IDs, dynamic context) cannot grow the schema map and `Box::leak` arena unboundedly. The current US-002 fix keys on `(group, code, message)`, which still leaks one schema per unique message and re-introduces the same class of leak the PR is trying to close. The NAPI-side `STRUCTURED_TIMEOUT_SCHEMAS` already keys only on `(&'static str, &'static str)` (`rivetkit-typescript/packages/rivetkit-napi/src/napi_actor_events.rs:96-98`); wasm must match.",
+      "acceptanceCriteria": [
+        "`BridgeRivetErrorSchemaKey` in `rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs:2596` becomes `(String, String)` (or equivalent two-tuple) keyed only on `(group, code)`",
+        "`bridge_rivet_error_schema` (`lib.rs:2599-2618`) inserts the first-seen `default_message` for a given `(group, code)` and reuses that schema for subsequent decodes regardless of payload message",
+        "The actual per-error `message` field continues to flow through `RivetTransportError.message: Some(payload.message)` so callers still see the live message",
+        "Update `parse_bridge_rivet_error_reuses_interned_schema` to assert that varying only the message for the same `(group, code)` reuses the schema (and therefore does NOT increment `BRIDGE_RIVET_ERROR_SCHEMAS.len()`)",
+        "Add a second test (or extend the existing one) that varying `(group, code)` does still allocate a new schema",
+        "`pnpm --filter @rivetkit/rivetkit-wasm run check:package` passes; `cargo test -p rivetkit-wasm` passes",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 11,
+      "passes": true,
+      "notes": "Wasm bridged RivetError schemas now intern by `(group, code)` only while preserving each payload's live message on the transport error. Native `cargo test -p rivetkit-wasm` still hits the pre-existing host-target `wasm_bindgen_futures` compile issue; wasm-target cargo test compilation and package checks pass."
+    },
+    {
+      "id": "US-012",
+      "title": "Bound register_task shutdown drain against shutdown deadline",
+      "description": "As an operator, I want `ctx.registerTask(promise)` not to block actor shutdown indefinitely when the user-supplied JS promise never resolves. `WasmActorContext::register_task` (`rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs:1345-1356`) and the analogous NAPI path route through `ActorContext::register_task` -> `track_shutdown_task`, so a never-resolving promise hangs shutdown drain. This contradicts the new CLAUDE.md rule added in this PR (\"Spawned futures that capture JS callbacks or other heavy resources must have a guaranteed completion path (e.g. a `CancellationToken` whose clones are guaranteed to drop)\").",
+      "acceptanceCriteria": [
+        "`ActorContext::register_task` in `rivetkit-rust/packages/rivetkit-core/src/actor/context.rs:552-587` races the user future against `ctx.shutdown_deadline_token().cancelled()` (or equivalent) so registered tasks unblock shutdown when the grace deadline elapses",
+        "Cancellation cause is logged at `tracing::warn!` with `actor_id` and a stable `reason` field so operators can find hanging registered tasks",
+        "Behavior is identical for the `wasm-runtime` and native `cfg(not(feature = \"wasm-runtime\"))` variants of `register_task`",
+        "Wasm `WasmActorContext::register_task` does not need a separate cancel path because core handles it",
+        "Add a Rust integration test in `rivetkit-rust/packages/rivetkit-core/tests/` that registers a never-completing future, triggers shutdown, and asserts shutdown completes within a bounded deadline rather than hanging",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 12,
+      "passes": false,
+      "notes": ""
+    },
+    {
+      "id": "US-013",
+      "title": "Avoid panic on websocket_callback_regions ID overflow",
+      "description": "As an operator running a long-lived wasm actor with frequent websocket callbacks, I do not want my actor to crash after ~4B handshakes because `next_websocket_callback_region_id` overflows `u32`. The current code (`rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs:1351-1355`) uses `checked_add(1).expect(\"websocket callback region id overflow\")`, which crashes the actor process instead of degrading.",
+      "acceptanceCriteria": [
+        "Either bump `next_websocket_callback_region_id` to `Cell<u64>` (and update the `begin_websocket_callback` return type plus any wasm-bindgen surface that exposes it) so overflow becomes operationally unreachable",
+        "Or implement wraparound that skips IDs already present in `websocket_callback_regions` so reuse is safe while regions are in flight",
+        "Either approach must keep IDs strictly monotonic for IDs currently in the map so no two live regions ever share an ID",
+        "Add a wasm crate test that exercises the wraparound (or large-counter) path to confirm no panic and no ID collision with live regions",
+        "If u32 is preserved, the test seeds `next_websocket_callback_region_id` near `u32::MAX` and verifies wraparound",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 13,
+      "passes": false,
+      "notes": ""
+    },
+    {
+      "id": "US-014",
+      "title": "Document global cache delta in parse_bridge_rivet_error test",
+      "description": "As a future contributor adding tests under `rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs`, I want a comment on `parse_bridge_rivet_error_reuses_interned_schema` (`lib.rs:2715-2737`) explaining that its `BRIDGE_RIVET_ERROR_SCHEMAS.len()` delta assertions only hold because the test owns a unique `(group, code)` namespace (`wasm_schema_cache_test`/`same_payload`). Without the comment, a future test that shares the global cache namespace will silently flip this assertion under parallel `cargo test`.",
+      "acceptanceCriteria": [
+        "Add a one or two line comment immediately above `parse_bridge_rivet_error_reuses_interned_schema` (or above the `initial_count` capture) noting that the test relies on a dedicated `(group, code)` namespace so concurrent tests do not perturb the global `BRIDGE_RIVET_ERROR_SCHEMAS.len()` delta",
+        "Comment names the namespace strings (`wasm_schema_cache_test`, `same_payload`) so future contributors know what to avoid",
+        "If US-011 lands first and changes the cache key shape, update the comment to reflect the new key",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 14,
+      "passes": false,
+      "notes": ""
     }
   ]
 }

scripts/ralph/progress.txt

@@ -10,7 +10,7 @@
 - Wasm `JsValue` callbacks are not Send/Sync; `WasmFunction` uses an unsafe Send/Sync impl because the wasm runtime is single-threaded.
 - Wasm host smoke tests use fake `WasmBindings` in `rivetkit-typescript/packages/rivetkit/tests/wasm-host-smoke.test.ts` to exercise the TypeScript `WasmCoreRuntime` adapter without requiring a built wasm artifact.
 - Wasm bindings that return `Result<_, JsValue>` should map core `anyhow::Error` values with `anyhow_to_js_error`.
-- Wasm bridged RivetError schemas are process-interned with `scc::HashMap` by `(group, code, default_message)` to avoid per-error schema leaks while preserving distinct defaults.
+- Wasm bridged RivetError schemas are process-interned with `scc::HashMap` by `(group, code)` only; live per-error messages stay on `RivetError.message`.
 - Validate wasm-only `ServeConfig` constraints at wasm entrypoints before converting to core `ServeConfig` or starting registry side effects.
 - Runtime-owned promises that must drain during shutdown use core `ActorContext::register_task(...)`, not public `wait_until(...)`, so NAPI and wasm can keep `registerTask` intent distinct.
 - Public HTTP status promotion for bridged errors lives in `rivetkit-core::error::public_error_status_code`; TS native/wasm adapters should not duplicate promotion tables.
@@ -123,3 +123,13 @@ Started: Sat May  2 02:13:32 AM PDT 2026
   - `napi::Ref::unref(env)` cannot be called from receive-loop worker reset paths or arbitrary `Drop` paths because both can lack a valid `Env`.
   - A future implementation should wrap stale refs in a TSF payload that forgets the reference on failed delivery, then unrefs only inside the TSF callback while an `Env` is in scope.
 ---
+## 2026-05-02 03:21:47 PDT - US-011
+- Changed wasm bridged `RivetErrorSchema` interning to key by `(group, code)` only, reusing the first schema default message even when later payload messages vary.
+- Extended the wasm crate cache test so same `(group, code)` with a different live message reuses the schema pointer and does not grow the cache, while a different code still allocates one new schema.
+- Files changed: `rivetkit-typescript/packages/rivetkit-wasm/src/lib.rs`, `rivetkit-typescript/CLAUDE.md`, `scripts/ralph/prd.json`, `scripts/ralph/progress.txt`.
+- Checks: `cargo test -p rivetkit-wasm --target wasm32-unknown-unknown --no-run parse_bridge_rivet_error_reuses_interned_schema`, `pnpm --filter @rivetkit/rivetkit-wasm run check:package`, `pnpm --filter @rivetkit/rivetkit-wasm run check:wasm`, `pnpm --filter @rivetkit/rivetkit-wasm run check-types`.
+- Plain `cargo test -p rivetkit-wasm` still fails on the pre-existing host-target `rivetkit-core` `wasm_bindgen_futures` dependency issue recorded in earlier progress.
+- **Learnings for future iterations:**
+  - Use unique `(group, code)` namespaces when asserting `BRIDGE_RIVET_ERROR_SCHEMAS.len()` deltas because the intern map is process-global.
+  - Schema defaults are only the first-seen fallback for a `(group, code)`; callers should assert live bridged messages through `RivetTransportError.message()`.
+---