feat: decode binary/protobuf payloads with messageType (LOE)

[rossnelson]

Summary

LOE prototype for browser-side decode of System Nexus payloads, where the gRPC envelope (SignalWithStartWorkflowExecutionRequest, future WaitForExternalWorkflow…, StandaloneActivity…, etc.) arrives in workflow history as a single Payload with metadata.encoding = binary/protobuf and metadata.messageType naming a fully-qualified temporal.api.* type.

Adds a Phase 1.5 dispatch in parseRawPayloadToJSON:

encoding === 'binary/protobuf' && metadata.messageType
  → @temporalio/proto: lookupType(messageType).decode(bytes).toObject()
  → recursively decode any nested {metadata, data} Payloads in the result
  → return as if it had been encoding 'json/plain' all along

Every existing renderer (event card, JSON view, compact row, copy/export) inherits the typed view for free. Adding the next system Nexus operation costs zero code — @temporalio/proto already ships every workflowservice message.

Demo

Repro harness lives in temporalio/nexus-endpoint (sibling repo): pinned temporal server + sdk-python spk/signal-with-start test that produces a real SignalWithStartWorkflowExecutionRequest in workflow history.

Before — what every renderer saw before this patch for nexusOperationScheduledEventAttributes.input:

{
  "metadata": {
    "encoding":    "binary/protobuf",
    "messageType": "temporal.api.workflowservice.v1.SignalWithStartWorkflowExecutionRequest"
  },
  "data": "CgdkZWZhdWx0EhhzeXN0ZW0tbmV4… (1068 base64 chars)"
}

After — same render path, no other changes:

{
  "namespace":     "default",
  "workflowId":    "system-nexus-workflow-id",
  "workflowType":  { "name": "EchoWorkflow" },
  "taskQueue":     { "name": "969f0ffd-…" },
  "input":         { "payloads": [ { "driver_claim": { … }, "driver_name": "test-driver" } ] },
  "signalName":    "test-signal",
  "signalInput":   { "payloads": [ { "driver_claim": { … }, "driver_name": "test-driver" } ] },
  "memo":          { "fields": { "memo-key": { "driver_claim": { … }, "driver_name": "test-driver" } } },
  "userMetadata":  { "summary": { … }, "details": { … } },
  …
}

Note the inner Payloads (the user's signal args, memo, etc.) are also decoded — the recursive pass in this PR feeds nested {metadata, data} nodes back through parseRawPayloadToJSON, so the existing JSON-decode path handles them transparently.

Visible UI surfaces (verified live)

• Event detail panel — Input / Result typed JSON
• Compact event row in the events table — same shape inline
• "Copy as JSON" / export — same shape

Open questions for review

1. CSP — second commit relaxes script-src to add 'unsafe-eval', because protobufjs builds per-message decoders via Function(). Two paths:
   • Keep this commit (accept unsafe-eval in production)
   • Drop this commit and migrate to @bufbuild/protobuf (no eval, smaller, ESM-native; ~2 days)
2. Bundle size — @temporalio/proto is already a dep but only used as types today. Worth a pnpm build before/after to see the runtime delta. If meaningful, switch to dynamic await import('@temporalio/proto') inside the decode helper.
3. ./atob landmine — the local atob does UTF-8 decoding via decodeURIComponent, which corrupts raw protobuf bytes. The patch uses globalThis.atob directly. Worth either documenting that on ./atob.ts or extracting a rawBase64ToUint8Array helper for future binary work.
4. UX — should we render Nexus operations as their inner type (e.g. "Signal With Start" as a first-class event row) rather than "Nexus Operation Scheduled" with a typed Input panel? Notion doc is silent. Worth a designer pass.

What this isn't

• A production-ready feature. It's an LOE prototype. Drafting to share the working approach.
• Anything beyond binary/protobuf payloads. Other encodings unchanged.
• A Nexus presentation refactor. The event card still says "Nexus Operation Scheduled".

Test plan

• pnpm test src/lib/utilities/decode-payload.test.ts -- --run — 27/27 passing (added 2)
• pnpm check — 0 errors, 84 pre-existing warnings
• pnpm lint — 0 errors, 210 pre-existing warnings
• End-to-end: real workflow with SignalWithStartWorkflowExecutionRequest + nested external-storage payloads decoded in browser, screenshots in conversation
• pnpm build size comparison — TODO before promoting beyond LOE

Notion

System Nexus Endpoint — the page's outstanding "UI" question is whether the browser can decode without a proto library. Answer: yes, it already can; this PR shows how.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
holocene	Ready	Preview, Comment	May 4, 2026 5:48pm