@contractspec/integration.workflow-devkit 0.1.2 → 0.1.4

package/README.md

@@ -19,6 +19,17 @@ Workflow DevKit compiler and runtime bridges for ContractSpec `WorkflowSpec`.
 - `@contractspec/integration.workflow-devkit/agent-adapter`
 - `@contractspec/integration.workflow-devkit/next`
 
+## Workflow vs step boundary
+
+Workflow DevKit code runs across two different execution contexts:
+
+- Workflow functions (`"use workflow"`) orchestrate control flow and must stay deterministic.
+- Step functions (`"use step"`) perform the actual Node.js work.
+
+This matches the Workflow docs: workflow functions do not have full Node.js access, while step functions do. Keep Node.js core modules, SDK clients, database access, and other side effects inside `use step` helpers. The workflow function itself should only compose Workflow primitives and call step helpers.
+
+For `WorkflowSpec` authoring in Workflow-hosted apps, import the safe authoring API from `@contractspec/lib.contracts-spec/workflow/spec`, not the broad `@contractspec/lib.contracts-spec/workflow` barrel.
+
 ## Next.js example
 
 ```ts
@@ -52,6 +63,8 @@ import { onboardingWorkflow } from "./onboarding.workflow";
 export async function runOnboarding(input: Record<string, unknown>, bridge: WorkflowDevkitRuntimeBridge) {
   "use workflow";
 
+  // Keep this function deterministic. Node.js work belongs in `use step`
+  // helpers that your bridge dispatches to.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: onboardingWorkflow,
     initialData: input,

package/dist/agent-adapter.js

@@ -1,80 +1,2 @@
 // @bun
-// src/agent-adapter.ts
-class InMemoryWorkflowDevkitCheckpointStore {
-  envelopes = new Map;
-  async delete(sessionId) {
-    this.envelopes.delete(sessionId);
-  }
-  async load(sessionId) {
-    return this.envelopes.get(sessionId) ?? null;
-  }
-  async save(envelope) {
-    this.envelopes.set(envelope.sessionId, envelope);
-  }
-}
-
-class InMemoryWorkflowDevkitSuspensionStore {
-  states = new Map;
-  async clear(sessionId) {
-    this.states.delete(sessionId);
-  }
-  async get(sessionId) {
-    return this.states.get(sessionId) ?? null;
-  }
-  async set(sessionId, state) {
-    this.states.set(sessionId, state);
-  }
-}
-function createWorkflowDevkitAgentRuntimeAdapterBundle(options = {}) {
-  const checkpointStore = options.checkpointStore ?? new InMemoryWorkflowDevkitCheckpointStore;
-  const suspensionStore = options.suspensionStore ?? new InMemoryWorkflowDevkitSuspensionStore;
-  const resolveSessionToken = options.resolveSessionToken ?? defaultWorkflowDevkitAgentToken;
-  return {
-    key: "workflow-devkit",
-    checkpoint: {
-      delete(sessionId) {
-        return checkpointStore.delete(sessionId);
-      },
-      load(sessionId) {
-        return checkpointStore.load(sessionId);
-      },
-      save(envelope) {
-        return checkpointStore.save(envelope);
-      }
-    },
-    suspendResume: {
-      async resume(params) {
-        await suspensionStore.set(params.sessionId, {
-          input: params.input,
-          metadata: params.metadata,
-          reason: "resumed",
-          resumedAt: new Date,
-          suspendedAt: new Date
-        });
-        if (options.workflowApi) {
-          await options.workflowApi.resumeHook(resolveSessionToken(params.sessionId), {
-            input: params.input,
-            metadata: params.metadata,
-            sessionId: params.sessionId
-          });
-        }
-      },
-      async suspend(params) {
-        await suspensionStore.set(params.sessionId, {
-          metadata: params.metadata,
-          reason: params.reason,
-          suspendedAt: new Date
-        });
-      }
-    }
-  };
-}
-function defaultWorkflowDevkitAgentToken(sessionId) {
-  return `agent-session:${sessionId}`;
-}
-export {
-  defaultWorkflowDevkitAgentToken,
-  createWorkflowDevkitAgentRuntimeAdapterBundle,
-  InMemoryWorkflowDevkitSuspensionStore,
-  InMemoryWorkflowDevkitCheckpointStore
-};
+class x{envelopes=new Map;async delete(b){this.envelopes.delete(b)}async load(b){return this.envelopes.get(b)??null}async save(b){this.envelopes.set(b.sessionId,b)}}class z{states=new Map;async clear(b){this.states.delete(b)}async get(b){return this.states.get(b)??null}async set(b,j){this.states.set(b,j)}}function C(b={}){let j=b.checkpointStore??new x,q=b.suspensionStore??new z,A=b.resolveSessionToken??B;return{key:"workflow-devkit",checkpoint:{delete(g){return j.delete(g)},load(g){return j.load(g)},save(g){return j.save(g)}},suspendResume:{async resume(g){if(await q.set(g.sessionId,{input:g.input,metadata:g.metadata,reason:"resumed",resumedAt:new Date,suspendedAt:new Date}),b.workflowApi)await b.workflowApi.resumeHook(A(g.sessionId),{input:g.input,metadata:g.metadata,sessionId:g.sessionId})},async suspend(g){await q.set(g.sessionId,{metadata:g.metadata,reason:g.reason,suspendedAt:new Date})}}}}function B(b){return`agent-session:${b}`}export{B as defaultWorkflowDevkitAgentToken,C as createWorkflowDevkitAgentRuntimeAdapterBundle,z as InMemoryWorkflowDevkitSuspensionStore,x as InMemoryWorkflowDevkitCheckpointStore};

package/dist/browser/agent-adapter.js

@@ -1,79 +1 @@
-// src/agent-adapter.ts
-class InMemoryWorkflowDevkitCheckpointStore {
-  envelopes = new Map;
-  async delete(sessionId) {
-    this.envelopes.delete(sessionId);
-  }
-  async load(sessionId) {
-    return this.envelopes.get(sessionId) ?? null;
-  }
-  async save(envelope) {
-    this.envelopes.set(envelope.sessionId, envelope);
-  }
-}
-
-class InMemoryWorkflowDevkitSuspensionStore {
-  states = new Map;
-  async clear(sessionId) {
-    this.states.delete(sessionId);
-  }
-  async get(sessionId) {
-    return this.states.get(sessionId) ?? null;
-  }
-  async set(sessionId, state) {
-    this.states.set(sessionId, state);
-  }
-}
-function createWorkflowDevkitAgentRuntimeAdapterBundle(options = {}) {
-  const checkpointStore = options.checkpointStore ?? new InMemoryWorkflowDevkitCheckpointStore;
-  const suspensionStore = options.suspensionStore ?? new InMemoryWorkflowDevkitSuspensionStore;
-  const resolveSessionToken = options.resolveSessionToken ?? defaultWorkflowDevkitAgentToken;
-  return {
-    key: "workflow-devkit",
-    checkpoint: {
-      delete(sessionId) {
-        return checkpointStore.delete(sessionId);
-      },
-      load(sessionId) {
-        return checkpointStore.load(sessionId);
-      },
-      save(envelope) {
-        return checkpointStore.save(envelope);
-      }
-    },
-    suspendResume: {
-      async resume(params) {
-        await suspensionStore.set(params.sessionId, {
-          input: params.input,
-          metadata: params.metadata,
-          reason: "resumed",
-          resumedAt: new Date,
-          suspendedAt: new Date
-        });
-        if (options.workflowApi) {
-          await options.workflowApi.resumeHook(resolveSessionToken(params.sessionId), {
-            input: params.input,
-            metadata: params.metadata,
-            sessionId: params.sessionId
-          });
-        }
-      },
-      async suspend(params) {
-        await suspensionStore.set(params.sessionId, {
-          metadata: params.metadata,
-          reason: params.reason,
-          suspendedAt: new Date
-        });
-      }
-    }
-  };
-}
-function defaultWorkflowDevkitAgentToken(sessionId) {
-  return `agent-session:${sessionId}`;
-}
-export {
-  defaultWorkflowDevkitAgentToken,
-  createWorkflowDevkitAgentRuntimeAdapterBundle,
-  InMemoryWorkflowDevkitSuspensionStore,
-  InMemoryWorkflowDevkitCheckpointStore
-};
+class x{envelopes=new Map;async delete(b){this.envelopes.delete(b)}async load(b){return this.envelopes.get(b)??null}async save(b){this.envelopes.set(b.sessionId,b)}}class z{states=new Map;async clear(b){this.states.delete(b)}async get(b){return this.states.get(b)??null}async set(b,j){this.states.set(b,j)}}function C(b={}){let j=b.checkpointStore??new x,q=b.suspensionStore??new z,A=b.resolveSessionToken??B;return{key:"workflow-devkit",checkpoint:{delete(g){return j.delete(g)},load(g){return j.load(g)},save(g){return j.save(g)}},suspendResume:{async resume(g){if(await q.set(g.sessionId,{input:g.input,metadata:g.metadata,reason:"resumed",resumedAt:new Date,suspendedAt:new Date}),b.workflowApi)await b.workflowApi.resumeHook(A(g.sessionId),{input:g.input,metadata:g.metadata,sessionId:g.sessionId})},async suspend(g){await q.set(g.sessionId,{metadata:g.metadata,reason:g.reason,suspendedAt:new Date})}}}}function B(b){return`agent-session:${b}`}export{B as defaultWorkflowDevkitAgentToken,C as createWorkflowDevkitAgentRuntimeAdapterBundle,z as InMemoryWorkflowDevkitSuspensionStore,x as InMemoryWorkflowDevkitCheckpointStore};

package/dist/browser/chat-routes.js

@@ -1,100 +1 @@
-// src/chat-routes.ts
-import { createUIMessageStreamResponse } from "ai";
-import { getRun, resumeHook, start } from "workflow/api";
-var WORKFLOW_RUN_ID_HEADER = "x-workflow-run-id";
-var WORKFLOW_STREAM_TAIL_INDEX_HEADER = "x-workflow-stream-tail-index";
-function createWorkflowDevkitStartRoute(options) {
-  const workflowApi = options.workflowApi ?? { start };
-  return async (request) => {
-    const body = await request.json();
-    const args = await options.buildArgs(body, request);
-    const run = await workflowApi.start(options.workflow, args);
-    if (options.createResponse) {
-      return options.createResponse({ body, run });
-    }
-    if (!run.readable) {
-      return new Response(JSON.stringify({ runId: run.runId }), {
-        headers: {
-          "Content-Type": "application/json",
-          [WORKFLOW_RUN_ID_HEADER]: run.runId
-        }
-      });
-    }
-    return createUIMessageStreamResponse({
-      headers: {
-        [WORKFLOW_RUN_ID_HEADER]: run.runId
-      },
-      stream: run.readable
-    });
-  };
-}
-function createWorkflowDevkitFollowUpRoute(options) {
-  const workflowApi = options.workflowApi ?? { resumeHook };
-  return async (request, context) => {
-    const runId = context.params.runId ?? context.params.id;
-    if (!runId) {
-      return new Response(JSON.stringify({ error: "Missing run id" }), {
-        status: 400
-      });
-    }
-    const body = await request.json();
-    const token = options.resolveToken({ body, request, runId });
-    const payload = options.buildPayload ? await options.buildPayload(body, request) : body;
-    await workflowApi.resumeHook(token, payload);
-    return new Response(JSON.stringify({ ok: true }), {
-      headers: {
-        "Content-Type": "application/json",
-        [WORKFLOW_RUN_ID_HEADER]: runId
-      }
-    });
-  };
-}
-function createWorkflowDevkitStreamRoute(options = {}) {
-  const workflowApi = options.workflowApi ?? { getRun };
-  return async (request, context) => {
-    const runId = context.params.runId ?? context.params.id;
-    if (!runId) {
-      return new Response(JSON.stringify({ error: "Missing run id" }), {
-        status: 400
-      });
-    }
-    const run = workflowApi.getRun(runId);
-    if (!run) {
-      return new Response(JSON.stringify({ error: "Workflow run not found" }), {
-        status: 404
-      });
-    }
-    const startIndex = readStartIndex(request.url);
-    const readable = run.getReadable ? run.getReadable({ startIndex }) : run.readable;
-    if (!readable) {
-      return new Response(JSON.stringify({ error: "Run has no readable stream" }), {
-        status: 404
-      });
-    }
-    const tailIndex = await readable.getTailIndex?.();
-    return createUIMessageStreamResponse({
-      headers: {
-        ...tailIndex !== undefined ? {
-          [WORKFLOW_STREAM_TAIL_INDEX_HEADER]: String(tailIndex)
-        } : {}
-      },
-      stream: readable
-    });
-  };
-}
-function readStartIndex(url) {
-  const parsed = new URL(url);
-  const rawStartIndex = parsed.searchParams.get("startIndex");
-  if (!rawStartIndex) {
-    return;
-  }
-  const parsedStartIndex = Number(rawStartIndex);
-  return Number.isFinite(parsedStartIndex) ? parsedStartIndex : undefined;
-}
-export {
-  createWorkflowDevkitStreamRoute,
-  createWorkflowDevkitStartRoute,
-  createWorkflowDevkitFollowUpRoute,
-  WORKFLOW_STREAM_TAIL_INDEX_HEADER,
-  WORKFLOW_RUN_ID_HEADER
-};
+import{createUIMessageStreamResponse as V}from"ai";import{getRun as Y,resumeHook as Z,start as $}from"workflow/api";var P="x-workflow-run-id",F="x-workflow-stream-tail-index";function X(j){let C=j.workflowApi??{start:$};return async(v)=>{let z=await v.json(),B=await j.buildArgs(z,v),h=await C.start(j.workflow,B);if(j.createResponse)return j.createResponse({body:z,run:h});if(!h.readable)return new Response(JSON.stringify({runId:h.runId}),{headers:{"Content-Type":"application/json",[P]:h.runId}});return V({headers:{[P]:h.runId},stream:h.readable})}}function m(j){let C=j.workflowApi??{resumeHook:Z};return async(v,z)=>{let B=z.params.runId??z.params.id;if(!B)return new Response(JSON.stringify({error:"Missing run id"}),{status:400});let h=await v.json(),J=j.resolveToken({body:h,request:v,runId:B}),G=j.buildPayload?await j.buildPayload(h,v):h;return await C.resumeHook(J,G),new Response(JSON.stringify({ok:!0}),{headers:{"Content-Type":"application/json",[P]:B}})}}function D(j={}){let C=j.workflowApi??{getRun:Y};return async(v,z)=>{let B=z.params.runId??z.params.id;if(!B)return new Response(JSON.stringify({error:"Missing run id"}),{status:400});let h=C.getRun(B);if(!h)return new Response(JSON.stringify({error:"Workflow run not found"}),{status:404});let J=H(v.url),G=h.getReadable?h.getReadable({startIndex:J}):h.readable;if(!G)return new Response(JSON.stringify({error:"Run has no readable stream"}),{status:404});let Q=await G.getTailIndex?.();return V({headers:{...Q!==void 0?{[F]:String(Q)}:{}},stream:G})}}function H(j){let v=new URL(j).searchParams.get("startIndex");if(!v)return;let z=Number(v);return Number.isFinite(z)?z:void 0}export{D as createWorkflowDevkitStreamRoute,X as createWorkflowDevkitStartRoute,m as createWorkflowDevkitFollowUpRoute,F as WORKFLOW_STREAM_TAIL_INDEX_HEADER,P as WORKFLOW_RUN_ID_HEADER};

package/dist/browser/compiler.js

@@ -1,117 +1,7 @@
-// src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
-function inferWorkflowDevkitBehavior(step) {
-  return step.runtime?.workflowDevkit?.behavior ?? step.type;
-}
-function resolveWorkflowDevkitEntryStepId(spec) {
-  const entryStepId = spec.definition.entryStepId ?? spec.definition.steps[0]?.id;
-  if (!entryStepId) {
-    throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} does not define an entry step.`);
-  }
-  return entryStepId;
-}
-function resolveWorkflowDevkitRunIdentity(spec, runIdentity) {
-  if (runIdentity) {
-    return runIdentity;
-  }
-  const strategy = spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version";
-  const prefix = spec.runtime?.workflowDevkit?.runIdentity?.prefix;
-  const baseIdentity = strategy === "meta-key-version" ? `${spec.meta.key}.v${spec.meta.version}` : `${spec.meta.key}.v${spec.meta.version}`;
-  return prefix ? `${prefix}:${baseIdentity}` : baseIdentity;
-}
-function resolveWorkflowDevkitWaitToken(spec, step, runIdentity) {
-  const runtime = step.runtime?.workflowDevkit;
-  if (!runtime) {
-    return;
-  }
-  const explicitToken = runtime.hookWait?.token ?? runtime.webhookWait?.token ?? runtime.approvalWait?.token ?? runtime.streamSession?.followUpToken;
-  if (explicitToken) {
-    return explicitToken;
-  }
-  const tokenStrategy = spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic";
-  const prefix = spec.runtime?.workflowDevkit?.hookTokens?.prefix ?? spec.meta.key;
-  const stableStepId = sanitizeIdentifier(step.id);
-  if (tokenStrategy === "session-scoped") {
-    const resolvedRunIdentity = sanitizeIdentifier(resolveWorkflowDevkitRunIdentity(spec, runIdentity));
-    return `${prefix}:${resolvedRunIdentity}:${stableStepId}`;
-  }
-  if (tokenStrategy === "step-scoped") {
-    return `${prefix}:v${spec.meta.version}:${stableStepId}`;
-  }
-  return `${prefix}:${stableStepId}`;
-}
-function resolveWorkflowDevkitNextStepId(spec, step, data, input, output) {
-  const transitions = spec.definition.transitions.filter((transition) => transition.from === step.id);
-  for (const transition of transitions) {
-    if (evaluateExpression(transition.condition, {
-      data,
-      input,
-      output
-    })) {
-      return transition.to;
-    }
-  }
-  return null;
-}
-function mergeWorkflowDevkitData(current, input, output) {
-  const next = { ...current };
-  if (isRecord(input)) {
-    Object.assign(next, input);
-  }
-  if (isRecord(output)) {
-    Object.assign(next, output);
-  }
-  return next;
-}
-function sanitizeIdentifier(value) {
-  return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
-}
-function isRecord(value) {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
+import{evaluateExpression as Y}from"@contractspec/lib.contracts-spec/workflow/expression";function Q(j){return j.runtime?.workflowDevkit?.behavior??j.type}function U(j){let q=j.definition.entryStepId??j.definition.steps[0]?.id;if(!q)throw Error(`Workflow ${j.meta.key}.v${j.meta.version} does not define an entry step.`);return q}function Z(j,q){if(q)return q;let C=j.runtime?.workflowDevkit?.runIdentity?.strategy??"meta-key-version",A=j.runtime?.workflowDevkit?.runIdentity?.prefix,J=C==="meta-key-version"?`${j.meta.key}.v${j.meta.version}`:`${j.meta.key}.v${j.meta.version}`;return A?`${A}:${J}`:J}function V(j,q,C){let A=q.runtime?.workflowDevkit;if(!A)return;let J=A.hookWait?.token??A.webhookWait?.token??A.approvalWait?.token??A.streamSession?.followUpToken;if(J)return J;let L=j.runtime?.workflowDevkit?.hookTokens?.strategy??"deterministic",H=j.runtime?.workflowDevkit?.hookTokens?.prefix??j.meta.key,M=K(q.id);if(L==="session-scoped"){let X=K(Z(j,C));return`${H}:${X}:${M}`}if(L==="step-scoped")return`${H}:v${j.meta.version}:${M}`;return`${H}:${M}`}function h(j,q,C,A,J){let L=j.definition.transitions.filter((H)=>H.from===q.id);for(let H of L)if(Y(H.condition,{data:C,input:A,output:J}))return H.to;return null}function D(j,q,C){let A={...j};if(O(q))Object.assign(A,q);if(O(C))Object.assign(A,C);return A}function K(j){return j.replace(/[^a-zA-Z0-9_-]+/g,"-")}function O(j){return j!=null&&typeof j==="object"&&!Array.isArray(j)}function _(j){return{entryStepId:U(j),hostTarget:j.runtime?.workflowDevkit?.hostTarget??"generic",hookTokenStrategy:j.runtime?.workflowDevkit?.hookTokens?.strategy??"deterministic",integrationMode:j.runtime?.workflowDevkit?.integrationMode??"manual",runIdentityStrategy:j.runtime?.workflowDevkit?.runIdentity?.strategy??"meta-key-version",specKey:j.meta.key,specVersion:j.meta.version,steps:j.definition.steps.map((q)=>({behavior:Q(q),id:q.id,label:q.label,operationRef:q.action?.operation?`${q.action.operation.key}.v${q.action.operation.version}`:void 0,runtime:q.runtime?.workflowDevkit,transitions:j.definition.transitions.filter((C)=>C.from===q.id).map((C)=>({condition:C.condition,to:C.to})),type:q.type,waitToken:V(j,q)}))}}function z(j,q){let C=_(j),A=q.workflowFunctionName??`${K(q.exportName)}WorkflowDevkit`;return{genericBootstrap:$(q.exportName,A),manifest:JSON.stringify(C,null,2),nextFollowUpRoute:G(A),nextStartRoute:E(A),nextStreamRoute:B(),workflowModule:P(q.exportName,q.specImportPath,A)}}function $(j,q){return`import { ${q} } from "./${K(j)}.workflow-devkit";
 
-// src/compiler.ts
-function compileWorkflowSpecToWorkflowDevkit(spec) {
-  return {
-    entryStepId: resolveWorkflowDevkitEntryStepId(spec),
-    hostTarget: spec.runtime?.workflowDevkit?.hostTarget ?? "generic",
-    hookTokenStrategy: spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic",
-    integrationMode: spec.runtime?.workflowDevkit?.integrationMode ?? "manual",
-    runIdentityStrategy: spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version",
-    specKey: spec.meta.key,
-    specVersion: spec.meta.version,
-    steps: spec.definition.steps.map((step) => ({
-      behavior: inferWorkflowDevkitBehavior(step),
-      id: step.id,
-      label: step.label,
-      operationRef: step.action?.operation ? `${step.action.operation.key}.v${step.action.operation.version}` : undefined,
-      runtime: step.runtime?.workflowDevkit,
-      transitions: spec.definition.transitions.filter((transition) => transition.from === step.id).map((transition) => ({
-        condition: transition.condition,
-        to: transition.to
-      })),
-      type: step.type,
-      waitToken: resolveWorkflowDevkitWaitToken(spec, step)
-    }))
-  };
-}
-function generateWorkflowDevkitArtifacts(spec, options) {
-  const compilation = compileWorkflowSpecToWorkflowDevkit(spec);
-  const workflowFunctionName = options.workflowFunctionName ?? `${sanitizeIdentifier(options.exportName)}WorkflowDevkit`;
-  return {
-    genericBootstrap: createGenericBootstrapTemplate(options.exportName, workflowFunctionName),
-    manifest: JSON.stringify(compilation, null, 2),
-    nextFollowUpRoute: createFollowUpRouteTemplate(workflowFunctionName),
-    nextStartRoute: createStartRouteTemplate(workflowFunctionName),
-    nextStreamRoute: createStreamRouteTemplate(),
-    workflowModule: createWorkflowModuleTemplate(options.exportName, options.specImportPath, workflowFunctionName)
-  };
-}
-function createGenericBootstrapTemplate(exportName, workflowFunctionName) {
-  return `import { ${workflowFunctionName} } from "./${sanitizeIdentifier(exportName)}.workflow-devkit";
-
-export const ${sanitizeIdentifier(exportName)}WorkflowDevkitBootstrap = {
-  workflow: ${workflowFunctionName},
+export const ${K(j)}WorkflowDevkitBootstrap = {
+  workflow: ${q},
   createBridge() {
     return {
       executeAutomationStep: async () => {
@@ -120,46 +10,37 @@ export const ${sanitizeIdentifier(exportName)}WorkflowDevkitBootstrap = {
     };
   },
 };
-`;
-}
-function createStartRouteTemplate(workflowFunctionName) {
-  return `import { createWorkflowDevkitStartRoute } from "@contractspec/integration.workflow-devkit";
-import { ${workflowFunctionName} } from "./workflow";
+`}function E(j){return`import { createWorkflowDevkitStartRoute } from "@contractspec/integration.workflow-devkit";
+import { ${j} } from "./workflow";
 
 export const POST = createWorkflowDevkitStartRoute({
-  workflow: ${workflowFunctionName},
+  workflow: ${j},
   async buildArgs(body) {
     return [body];
   },
 });
-`;
-}
-function createFollowUpRouteTemplate(workflowFunctionName) {
-  return `import { createWorkflowDevkitFollowUpRoute } from "@contractspec/integration.workflow-devkit";
+`}function G(j){return`import { createWorkflowDevkitFollowUpRoute } from "@contractspec/integration.workflow-devkit";
 
 export const POST = createWorkflowDevkitFollowUpRoute({
   resolveToken({ runId }) {
-    return \`${workflowFunctionName}:\${runId}\`;
+    return \`${j}:\${runId}\`;
   },
 });
-`;
-}
-function createStreamRouteTemplate() {
-  return `import { createWorkflowDevkitStreamRoute } from "@contractspec/integration.workflow-devkit";
+`}function B(){return`import { createWorkflowDevkitStreamRoute } from "@contractspec/integration.workflow-devkit";
 
 export const GET = createWorkflowDevkitStreamRoute();
-`;
-}
-function createWorkflowModuleTemplate(exportName, specImportPath, workflowFunctionName) {
-  return `import { createHook, createWebhook, sleep } from "workflow";
+`}function P(j,q,C){return`import { createHook, createWebhook, sleep } from "workflow";
 import { runWorkflowSpecWithWorkflowDevkit } from "@contractspec/integration.workflow-devkit";
-import { ${exportName} } from "${specImportPath}";
+import { ${j} } from "${q}";
 
-export async function ${workflowFunctionName}(input = {}, bridge = {}) {
+export async function ${C}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
-    spec: ${exportName},
+    spec: ${j},
     initialData: input,
     bridge,
     primitives: {
@@ -169,9 +50,4 @@ export async function ${workflowFunctionName}(input = {}, bridge = {}) {
     },
   });
 }
-`;
-}
-export {
-  generateWorkflowDevkitArtifacts,
-  compileWorkflowSpecToWorkflowDevkit
-};
+`}export{z as generateWorkflowDevkitArtifacts,_ as compileWorkflowSpecToWorkflowDevkit};

package/dist/browser/helpers.js

@@ -1,80 +1 @@
-// src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
-function inferWorkflowDevkitBehavior(step) {
-  return step.runtime?.workflowDevkit?.behavior ?? step.type;
-}
-function resolveWorkflowDevkitEntryStepId(spec) {
-  const entryStepId = spec.definition.entryStepId ?? spec.definition.steps[0]?.id;
-  if (!entryStepId) {
-    throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} does not define an entry step.`);
-  }
-  return entryStepId;
-}
-function resolveWorkflowDevkitRunIdentity(spec, runIdentity) {
-  if (runIdentity) {
-    return runIdentity;
-  }
-  const strategy = spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version";
-  const prefix = spec.runtime?.workflowDevkit?.runIdentity?.prefix;
-  const baseIdentity = strategy === "meta-key-version" ? `${spec.meta.key}.v${spec.meta.version}` : `${spec.meta.key}.v${spec.meta.version}`;
-  return prefix ? `${prefix}:${baseIdentity}` : baseIdentity;
-}
-function resolveWorkflowDevkitWaitToken(spec, step, runIdentity) {
-  const runtime = step.runtime?.workflowDevkit;
-  if (!runtime) {
-    return;
-  }
-  const explicitToken = runtime.hookWait?.token ?? runtime.webhookWait?.token ?? runtime.approvalWait?.token ?? runtime.streamSession?.followUpToken;
-  if (explicitToken) {
-    return explicitToken;
-  }
-  const tokenStrategy = spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic";
-  const prefix = spec.runtime?.workflowDevkit?.hookTokens?.prefix ?? spec.meta.key;
-  const stableStepId = sanitizeIdentifier(step.id);
-  if (tokenStrategy === "session-scoped") {
-    const resolvedRunIdentity = sanitizeIdentifier(resolveWorkflowDevkitRunIdentity(spec, runIdentity));
-    return `${prefix}:${resolvedRunIdentity}:${stableStepId}`;
-  }
-  if (tokenStrategy === "step-scoped") {
-    return `${prefix}:v${spec.meta.version}:${stableStepId}`;
-  }
-  return `${prefix}:${stableStepId}`;
-}
-function resolveWorkflowDevkitNextStepId(spec, step, data, input, output) {
-  const transitions = spec.definition.transitions.filter((transition) => transition.from === step.id);
-  for (const transition of transitions) {
-    if (evaluateExpression(transition.condition, {
-      data,
-      input,
-      output
-    })) {
-      return transition.to;
-    }
-  }
-  return null;
-}
-function mergeWorkflowDevkitData(current, input, output) {
-  const next = { ...current };
-  if (isRecord(input)) {
-    Object.assign(next, input);
-  }
-  if (isRecord(output)) {
-    Object.assign(next, output);
-  }
-  return next;
-}
-function sanitizeIdentifier(value) {
-  return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
-}
-function isRecord(value) {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
-export {
-  sanitizeIdentifier,
-  resolveWorkflowDevkitWaitToken,
-  resolveWorkflowDevkitRunIdentity,
-  resolveWorkflowDevkitNextStepId,
-  resolveWorkflowDevkitEntryStepId,
-  mergeWorkflowDevkitData,
-  inferWorkflowDevkitBehavior
-};
+import{evaluateExpression as L}from"@contractspec/lib.contracts-spec/workflow/expression";function O(h){return h.runtime?.workflowDevkit?.behavior??h.type}function P(h){let q=h.definition.entryStepId??h.definition.steps[0]?.id;if(!q)throw Error(`Workflow ${h.meta.key}.v${h.meta.version} does not define an entry step.`);return q}function M(h,q){if(q)return q;let A=h.runtime?.workflowDevkit?.runIdentity?.strategy??"meta-key-version",j=h.runtime?.workflowDevkit?.runIdentity?.prefix,C=A==="meta-key-version"?`${h.meta.key}.v${h.meta.version}`:`${h.meta.key}.v${h.meta.version}`;return j?`${j}:${C}`:C}function Q(h,q,A){let j=q.runtime?.workflowDevkit;if(!j)return;let C=j.hookWait?.token??j.webhookWait?.token??j.approvalWait?.token??j.streamSession?.followUpToken;if(C)return C;let F=h.runtime?.workflowDevkit?.hookTokens?.strategy??"deterministic",B=h.runtime?.workflowDevkit?.hookTokens?.prefix??h.meta.key,G=H(q.id);if(F==="session-scoped"){let K=H(M(h,A));return`${B}:${K}:${G}`}if(F==="step-scoped")return`${B}:v${h.meta.version}:${G}`;return`${B}:${G}`}function U(h,q,A,j,C){let F=h.definition.transitions.filter((B)=>B.from===q.id);for(let B of F)if(L(B.condition,{data:A,input:j,output:C}))return B.to;return null}function V(h,q,A){let j={...h};if(J(q))Object.assign(j,q);if(J(A))Object.assign(j,A);return j}function H(h){return h.replace(/[^a-zA-Z0-9_-]+/g,"-")}function J(h){return h!=null&&typeof h==="object"&&!Array.isArray(h)}export{H as sanitizeIdentifier,Q as resolveWorkflowDevkitWaitToken,M as resolveWorkflowDevkitRunIdentity,U as resolveWorkflowDevkitNextStepId,P as resolveWorkflowDevkitEntryStepId,V as mergeWorkflowDevkitData,O as inferWorkflowDevkitBehavior};