opaque() — Workflow-side handles for non-serializable step-side values

[TooTallNate]

opaque() — Workflow-side handles for non-serializable step-side values

Summary

This RFC proposes a new Workflow SDK primitive, opaque(factory), that lets workflow code construct handles to values that don't yet exist — values whose actual instantiation happens later, on the step side, when the handle is passed into a step. The factory closure runs in the step bundle, can use full Node.js, and produces a value whose return type is allowed to be non-serializable (DB connections, AI SDK model instances, NestJS @Injectable() providers, file handles, …).

The workflow VM never executes the factory and never observes the materialized value — it only forwards the handle. Existing closure-variable plumbing is reused for the factory's serializable inputs; existing WORKFLOW_USE_STEP-style globals and registries are reused for the factory's per-bundle dispatch.

This is a new primitive, not a change to existing semantics. It composes with "use step" rather than replacing it.

Motivation

Workflow today has a strict invariant: anything that crosses the workflow→step boundary must be serializable. This is correct and load-bearing — it's what makes step input/output reproducible across replays, encryptable at rest, and durable.

But there's a recurring class of values that should exist on the step side and should be parameterized by workflow-side data, yet have no useful serialized representation. Today, supporting them requires hand-written wrapper hacks. Three concrete examples:

Example 1 — AI SDK model providers (status quo)

packages/ai/src/providers/google.ts literally is:

export function google(...args: Parameters<typeof googleProvider>) {
  return async () => {
    'use step';
    return googleProvider(...args);
  };
}

The user's workflow code calls google('gemini-2.5-flash') and receives a thunk. They thread the thunk into DurableAgent, which is hand-coded to know it received a thunk and to call it on the step side. The "type" is () => Promise<LanguageModel> rather than LanguageModel, leaking the implementation detail to every consumer. Every new provider re-implements the same shape.

Example 2 — NestJS @Injectable() tools (#1865)

The user wants to write:

@Injectable()
class ReadFileTool {
  constructor(private readonly fileContentService: FileContentService) {}

  createTool(context) {
    return tool({
      execute: async (input) => {
        'use step';
        return this.fileContentService.readFileContent(input, context);
      },
    });
  }
}

#1935 fixed the lexical-this capture so this compiles correctly, but the runtime requirement — that the ReadFileTool instance survive the workflow→step boundary — forces the user to either (a) write WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE for every Nest provider used as a tool host (often impossible, since those instances hold DB connections, request-scoped state, etc.) or (b) write a ModuleRef bridge by hand. What they actually want is "on the step side, give me whatever Nest's container would hand me right now."

Example 3 — request-scoped resources

A workflow needs a pg.Client per step invocation: not durable, not serializable, but parameterized by a connection string from the workflow context. Today the user writes a step that opens the connection inside its body and threads results back as serializable scalars. That works for one-call patterns but breaks down when the resource needs to be passed to multiple cooperating steps as a single logical session.

The proposal

User-facing API

import { opaque, type Opaque } from 'workflow';

export async function myWorkflow() {
  'use workflow';

  const apiKey = process.env.OPENAI_API_KEY;       // serializable
  const userId = await getUserIdStep();            // serializable, recorded as event

  // `model` is `Opaque<LanguageModel>` in the workflow VM.
  const model: Opaque<LanguageModel> = opaque(() => {
    return openai('gpt-4o', { apiKey, userId }); // runs on step side, not in workflow VM
  });

  // The opaque token can be passed around freely in workflow code.
  // It cannot be unwrapped here — the type system enforces this.
  await runAgent(model);
}

// On the step side, the parameter type is `LanguageModel`, not `Opaque<LanguageModel>`.
async function runAgent(model: LanguageModel) {
  'use step';
  const result = await streamText({ model, prompt: '…' });
  return result.text;
}

The compiler:

1. Lifts the factory body to module scope and registers it under a stable ID (same shape as 'use step' hoisting today).
2. Replaces the opaque(() => …) call site with a workflow-bundle handle constructor: __createOpaque(opaqueId, () => ({ apiKey, userId })). The factory body is not included in the workflow bundle — same DCE pass that already strips step bodies from the workflow bundle covers this for free.
3. In step bundles, registers the factory under Symbol.for("@workflow/core//registeredOpaques") (mirroring registeredSteps).

The runtime:

1. Workflow VM: __createOpaque returns a sentinel object { __opaqueId, __closureVarsFn }. Calling it has no side effects, no event log entry, no replay risk.
2. Serialization: a new Opaque reducer on the workflow side reads __opaqueId and the materialized closure vars, emits { opaqueId, closureVars }. A matching reviver on the step side looks up the factory by opaqueId, calls it with the closure vars in scope, and substitutes the materialized value.
3. The step body sees the materialized value as a normal argument.

Type story

// Nominal type — cannot be assigned from a plain T.
declare const opaqueBrand: unique symbol;
export type Opaque<T> = { readonly [opaqueBrand]: T };

export function opaque<T>(factory: () => T | Promise<T>): Opaque<T>;

A step function declared as (model: LanguageModel) => Promise<string> accepts both LanguageModel (from non-workflow code) and Opaque<LanguageModel> (from workflow code) as its argument, because the runtime substitutes the materialized value at the deserialization boundary. Concrete typing of this — likely via a mapped type that recurses over the args list — is a follow-up; the basic shape is "the workflow VM holds Opaque<T>, the step body sees T."

Compiler changes (@workflow/swc-plugin)

This reuses existing infrastructure rather than adding a parallel path:

	'use step' arrow (today)	opaque(() => ...) (proposed)
Detection	directive prologue inside arrow body	callee === opaque (imported from workflow)
Hoisting	yes, into _anonymousStep<N> at module scope	yes, into _opaque<N> at module scope
Closure-var collection	ClosureVariableCollector over the body	same
Workflow-bundle replacement	globalThis[Symbol.for("WORKFLOW_USE_STEP")](id, closureFn)	globalThis[Symbol.for("WORKFLOW_CREATE_OPAQUE")](id, closureFn)
Step-bundle registration	inline IIFE on Symbol.for("@workflow/core//registeredSteps")	inline IIFE on Symbol.for("@workflow/core//registeredOpaques")
Manifest entry	steps map	new opaques map
DCE for body in workflow bundle	already covered	already covered

Runtime changes (@workflow/core)

Two new pieces:

// packages/core/src/private.ts
const RegisteredOpaquesKey = Symbol.for('@workflow/core//registeredOpaques');
const registeredOpaques: Map<string, (closureVars: any) => unknown>;
export function getOpaqueFactory(opaqueId: string): ((closureVars: any) => unknown) | undefined;

// packages/core/src/symbols.ts
export const WORKFLOW_CREATE_OPAQUE = Symbol.for('WORKFLOW_CREATE_OPAQUE');

Plus a reducer/reviver pair that mirrors getStepFunctionReducer / getStepFunctionReviver exactly — same closureVars propagation, same property-presence-vs-truthiness handling.

The workflow-VM-side createOpaque is implemented in core and registered on vmGlobalThis[WORKFLOW_CREATE_OPAQUE] next to useStep/createHook/sleep. It returns a sentinel and never invokes the factory.

Worked examples

AI SDK provider — what it'd look like after migration

// packages/ai/src/providers/google.ts (proposed)
import { opaque } from 'workflow';
import { google as googleProvider } from '@ai-sdk/google';
export function google(...args: Parameters<typeof googleProvider>) {
  return opaque(() => googleProvider(...args));
}

DurableAgent no longer needs to know about thunks. Its model argument's type is LanguageModel, full stop, and any Opaque<LanguageModel> flows in transparently.

NestJS — what @workflow/nest could ship

// packages/nest/src/inject-provider.ts
import { opaque } from 'workflow';
import { ModuleRef } from '@nestjs/core';

declare const moduleRef: ModuleRef; // resolved from a process-global Nest container

export function injectProvider<T>(token: Type<T>): Opaque<T> {
  return opaque(() => moduleRef.get(token, { strict: false }));
}

User code:

async function myWorkflow() {
  'use workflow';
  const tools = injectProvider(ReadFileTool);  // Opaque<ReadFileTool>
  await runAgent(tools);                       // step side sees a real ReadFileTool
}

The @nestjs/core import never enters the workflow bundle (factory body lives in the step bundle); the provider instance is never serialized.

Replay determinism

The factory body executes in the step environment with full Node.js access — it is not seeded, frozen-time, or otherwise constrained. This is the same posture as 'use step' bodies, but there's a subtle difference worth calling out: an opaque(...) call site in workflow code looks like an ordinary expression (it returns synchronously, it's not awaited), so users may not realize the factory body is non-deterministic.

The actual determinism guarantee is: the handle's identity in the workflow event log is fully determined by (opaqueId, materialized closure vars) — both of which are deterministic on the workflow side. Whatever the factory does with that input on the step side is the user's responsibility, in the same way that 'use step' body content is.

We will document this with a recommended pattern: use opaque() for resource construction, not for state. If you need determinism over the value itself, return it from a regular 'use step' instead.

Identity and caching

Each opaque(...) call site, evaluated once in the workflow VM, produces a new handle. Each handle, when crossed into a step bundle, is materialized fresh — there's no cross-step memoization. Within a single step invocation, if the same handle is destructured multiple times, the materialization is cached for that step's lifetime (so two Opaque<DbClient> arguments backed by the same handle don't open two connections).

The workflow VM never sees the materialized value, so handle equality is defined as object identity of the sentinel — a === b is true iff they came from the same opaque(...) evaluation. Two separate opaque(() => x) calls produce distinct handles even if the factory bodies look identical.

Lifecycle and cleanup

A Opaque<T> materialized inside a step is alive for that step's invocation only. The step bundle does not retain materialized values across steps — each step that receives the handle gets its own materialization.

If the factory needs cleanup (closing a DB connection, releasing a file handle), the factory can return an object whose method gets called by the step body, or we can extend the API with an explicit disposable form in a follow-up:

opaque({
  create: () => connectToDb(connectionString),
  dispose: (db) => db.close(),
})

Out of scope for v1.

Boundary rules

These rules are enforced by the runtime; violations throw with a clear error message:

1. Workflow VM cannot unwrap. There is no await opaque(...) or .value accessor. The handle is opaque to the workflow.
2. Opaque values cannot flow workflow → client. If a workflow returns an Opaque<T> (or includes one in its return value), the run fails with a serialization error explaining the constraint. The client bundle has no factory map.
3. Opaque values cannot close over other opaque values (in v1). Closure variables must be plain serializable. We can lift this in a follow-up via recursive resolution at the reducer level.
4. The factory must not access arguments/this — there is no enclosing function to inherit from once hoisted. Same constraint as nested step bodies (and the SWC plugin emits the same diagnostics).

Open questions

1. Naming. opaque() is descriptive but generic. Alternatives: lazy(), deferred(), forStep(), stepValue(), bindRef(). forStep(() => google('gemini-2.5-flash')) reads especially well at use sites.

2. Migration of existing AI provider thunks. Do we keep the current () => Promise<LanguageModel> public API and use opaque() internally, or do we make Opaque<LanguageModel> the new public shape? The latter is a breaking change for any user who has hand-written a custom provider.

3. Disposable form for v1? opaque({ create, dispose }) covers a lot of real use cases (DB clients, file handles) and is a one-line addition. Argument for shipping it now: deferring it lets users build patterns around the simple form that are awkward to retrofit.

4. First-class observability. Should each materialization be visible in the run timeline (similar to step_* events)? Argument for: makes "why did my step receive a stale model?" debuggable. Argument against: high-volume cases (per-step DB client materialization) would flood the event log. Likely answer: opt-in via a third argument or a separate observableOpaque(...) helper.

5. Recursive Opaque composition. v1 forbids it. Is there a real use case that justifies lifting this? The natural shape would be opaque(() => ({ db: opaqueDb, agent: opaqueAgent })) — solvable by recursive resolution in the reviver, but the closure-var serializer would need to know not to evaluate the inner __closureVarsFn early.

6. Relationship to "use step" factory functions. Should we eventually reframe 'use step' arrows that return non-serializable values as desugaring to opaque(...)? The mental model would be cleaner — 'use step' always returns a serializable value, full stop — but it's a substantial rework of existing code.

7. Step input encryption. The closure variables of an opaque(...) flow through the same encryption path as step arguments today. Is there ever a case where the factory itself (not its inputs) needs to be encrypted? I don't think so — the factory body lives in the step bundle and is identified by its registered ID, not transmitted over the wire — but worth confirming.

Implementation phases

Phase 1 — Core primitive. SWC plugin transformation, WORKFLOW_CREATE_OPAQUE global, registeredOpaques registry, reducer/reviver pair, manifest field, end-to-end test that round-trips a non-serializable handle through a step.

Phase 2 — Diagnostics. Compile-time check that opaque(...) argument is a function literal (not an arbitrary expression). Runtime errors for the boundary rules above with span pointers back to source. TypeScript type for Opaque<T> and the helper that maps step argument types.

Phase 3 — AI provider migration. Convert packages/ai/src/providers/* to use opaque() internally; expose Opaque<LanguageModel> as the new public type alongside (or replacing) the thunk shape.

Phase 4 — @workflow/nest integration. Ship injectProvider(token) helper backed by ModuleRef. Documents the Nest end-to-end story (#1865).

Phase 5 (optional) — Disposable form. opaque({ create, dispose }).

Prior art

• React Server Components has the closest analog: a "server reference" is a sentinel that materializes only when a server action runs, with closure variables flowing through the boundary as serialized arguments.
• Temporal calls a similar pattern "activity stubs," though their model differs in important ways (the stub is the call site, not the value).
• This is not a fundamentally novel idea — it's the natural generalization of the thunk pattern we already use in packages/ai/src/providers/.

---

Refs: #1865, #1935.