fix(rivetkit): decode bridge errors with actor: null

[abcxff]

Fixes RVT-6296

[railway-app]

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

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	May 13, 2026 at 8:14 pm
frontend-cloud	🕒 Building (View Logs)	Web	May 13, 2026 at 8:13 pm
frontend-inspector	🕒 Building (View Logs)	Web	May 13, 2026 at 8:13 pm
website	❌ Build Failed (View Logs)	Web	May 13, 2026 at 5:14 pm
mcp-hub	✅ Success (View Logs)	Web	May 13, 2026 at 5:13 pm
ladle	❌ Build Failed (View Logs)	Web	May 13, 2026 at 5:13 pm

[abcxff]

• [slop]fix(workflow-engine): only commit step state after success #5010 : 2 dependent PRs (#5050 , #5052 )
• fix(rivetkit): bind methods through createWriteThroughProxy #4987
• fix(rivetkit): decode bridge errors with actor: null #5056 👈 (View in Graphite)
• fix: wasm-pack build #5048
• main

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

[claude]

PR Review: fix(rivetkit): decode bridge errors with actor: null

Overview

This PR fixes a bug (RVT-6296) where bridge error payloads containing actor: null silently failed to decode, returning undefined instead of a structured RivetError. Root cause: JSON serialization from the NAPI/Rust side can produce null for an absent actor field, but isActorSpecifier(null) returns false, causing the entire payload to be rejected.

---

Changes

1. Validation guard in decodeBridgeRivetErrorPayload

// Before
if (payload.actor !== undefined && !isActorSpecifier(payload.actor)) {
// After
if (payload.actor !== undefined && payload.actor !== null && !isActorSpecifier(payload.actor)) {

Correct. Allows null to pass validation as "no actor specified," consistent with how isActorSpecifier itself treats null.

2. Null coercion in decodeBridgeRivetError

// Before
actor: payload.actor,
// After
actor: payload.actor ?? undefined,

Correct. RivetErrorOptions.actor is typed as ActorSpecifier | undefined, not ActorSpecifier | null. The ?? normalizes the runtime null into the expected TS type.

---

Issues

Missing regression test. The existing rivet-error.test.ts round-trip only covers a fully-populated actor specifier. There is no test for a bridge payload where actor is explicitly null, so a future regression here would go undetected. Suggested addition:

test("decodes bridge payload with actor: null", () => {
    const raw = `${BRIDGE_RIVET_ERROR_PREFIX}${JSON.stringify({
        group: "actor",
        code: "internal_error",
        message: "fail",
        actor: null,
    })}`;
    const decoded = decodeBridgeRivetError(raw);
    expect(decoded).toBeInstanceOf(RivetError);
    expect(decoded?.actor).toBeUndefined();
});

---

Minor observations

• BridgeRivetErrorPayload types actor as ActorSpecifier | undefined, not including null. The JSON.parse(...) as BridgeRivetErrorPayload cast is therefore a lie at runtime. Pre-existing issue, out of scope here, but worth tightening the type if the payload schema is revisited.
• encodeBridgeRivetError omits actor when it is undefined (standard JSON.stringify behavior), so null payloads can only originate from the NAPI/Rust bridge. The fix is correctly placed at the decode boundary.

---

Summary

The fix is minimal, correct, and well-targeted. Both changes are necessary and consistent with the project's null-vs-undefined conventions. The only missing piece is a regression test for the actor: null path.

[linear]

RVT-6296

[abcxff]

Merge activity

• May 13, 8:11 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 13, 8:14 PM UTC: Graphite rebased this pull request as part of a merge.
• May 13, 8:14 PM UTC: @abcxff merged this pull request with Graphite.