@nanobpm/workflow 0.8.0 → 0.8.2

package/README.md

@@ -1,6 +1,6 @@
 # @nanobpm/workflow
 
-Code-first durable orchestration for [nanobpmn](https://github.com/Magikcraft/nano-bpm)
+Code-first durable orchestration for [nanobpmn](https://nanobpm.io)
 (**ADR 0044**). Author durable workflows as ordinary async code; the SDK derives
 the executable BPMN model, the job types, and the message/correlation wiring, and
 hosts a generic worker. No diagram, no task-type wiring, no correlation plumbing

package/dist/client.d.ts

@@ -26,23 +26,23 @@ export interface NanoSdkClient {
     createDeployment(input: {
         resources: File[];
         [k: string]: unknown;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     createProcessInstance(input: {
         processDefinitionId: string;
         variables?: JsonObject;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     correlateMessage(input: {
         name: string;
         correlationKey: string;
         variables?: JsonObject;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     getProcessInstance(input: {
         processInstanceKey: string;
     }, consistency: {
         consistency: {
             waitUpToMs: number;
         };
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
 /** Config for a nano-sdk job worker (the subset the Worker runtime sets). */

package/dist/client.js

@@ -3,11 +3,57 @@
 // deploys it (with diagram interchange), starts instances, and correlates
 // signals; the low-level job protocol used by the Worker runtime is the SDK's
 // own job worker, reached through the exposed `sdk` client.
-import { createCamundaClient } from "@nanobpm/nano-sdk";
+import { createCamundaClient, JobActionReceiptSymbol, ProcessDefinitionId, ProcessInstanceKey } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function errorCause(e) {
+    return isRecord(e) ? e.cause : undefined;
+}
+function errorCode(e) {
+    return isRecord(e) ? e.code : undefined;
+}
+function errorMessage(e) {
+    return isRecord(e) && typeof e.message === "string" ? e.message : String(e);
+}
+function errorStatus(e) {
+    if (!isRecord(e))
+        return undefined;
+    if (typeof e.status === "number")
+        return e.status;
+    const response = e.response;
+    return isRecord(response) && typeof response.status === "number" ? response.status : undefined;
+}
+function isJson(v) {
+    if (v === null)
+        return true;
+    switch (typeof v) {
+        case "boolean":
+        case "number":
+        case "string":
+            return true;
+        case "object":
+            if (Array.isArray(v))
+                return v.every(isJson);
+            return Object.values(v).every(isJson);
+        default:
+            return false;
+    }
+}
+function toJsonObject(v) {
+    if (!isRecord(v))
+        throw new Error("SDK response was not an object");
+    const result = {};
+    for (const [key, value] of Object.entries(v)) {
+        if (isJson(value))
+            result[key] = value;
+    }
+    return result;
+}
 /** Render a workflow (either surface) to its executable BPMN model. */
 export function toBpmn(wf) {
     assertWorkflowIds(wf);
@@ -37,8 +83,8 @@ export async function toDeployableBpmn(wf, opts = {}) {
         // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
         // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
         // problem and must surface rather than silently deploy an uninspectable model.
-        const cause = e?.cause;
-        if (cause?.code !== "ERR_MODULE_NOT_FOUND")
+        const cause = errorCause(e);
+        if (errorCode(cause) !== "ERR_MODULE_NOT_FOUND")
             throw e;
         if (!warnedNoLayout) {
             warnedNoLayout = true;
@@ -65,9 +111,8 @@ export class WorkflowError extends Error {
 function asWorkflowError(e, what) {
     if (e instanceof WorkflowError)
         return e;
-    const err = e;
-    const status = err?.status ?? err?.response?.status;
-    return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+    const status = errorStatus(e);
+    return new WorkflowError(`${what} failed: ${errorMessage(e)}`, status);
 }
 export class WorkflowClient {
     /** The underlying nano-sdk client, exposed so the Worker runtime and app
@@ -83,13 +128,42 @@ export class WorkflowClient {
         }
         if (!opts?.baseUrl)
             throw new Error("WorkflowClient needs a baseUrl or a client");
-        this.sdk = createCamundaClient({
+        const raw = createCamundaClient({
             config: {
                 CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
                 ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
                 CAMUNDA_TRANSPORT: opts.transport ?? "auto",
             },
         });
+        this.sdk = {
+            createDeployment: (input) => raw.createDeployment(input),
+            createProcessInstance: (input) => raw.createProcessInstance({
+                ...input,
+                processDefinitionId: ProcessDefinitionId.assumeExists(input.processDefinitionId),
+            }),
+            correlateMessage: (input) => raw.correlateMessage(input),
+            getProcessInstance: (input, consistency) => raw.getProcessInstance({
+                processInstanceKey: ProcessInstanceKey.assumeExists(input.processInstanceKey),
+            }, consistency),
+            createJobWorker: (cfg) => {
+                const worker = raw.createJobWorker({
+                    ...cfg,
+                    jobHandler: async (job) => {
+                        await cfg.jobHandler(job);
+                        return JobActionReceiptSymbol;
+                    },
+                });
+                return {
+                    start: () => {
+                        void worker.start();
+                    },
+                    stop: () => worker.stop(),
+                    stopGracefully: async (opts) => {
+                        await worker.stopGracefully(opts);
+                    },
+                };
+            },
+        };
     }
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
@@ -102,7 +176,7 @@ export class WorkflowClient {
         const xml = await toDeployableBpmn(wf, opts);
         const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
         try {
-            return (await this.sdk.createDeployment({ resources: [file] }));
+            return toJsonObject(await this.sdk.createDeployment({ resources: [file] }));
         }
         catch (e) {
             throw asWorkflowError(e, "deploy");
@@ -116,7 +190,7 @@ export class WorkflowClient {
     async start(wf, input = {}) {
         const variables = wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
         try {
-            return (await this.sdk.createProcessInstance({
+            return toJsonObject(await this.sdk.createProcessInstance({
                 processDefinitionId: wf.id,
                 variables,
             }));
@@ -140,7 +214,7 @@ export class WorkflowClient {
             throw new WorkflowError(`unknown signal "${signalName}" on flow "${flow.id}" — declared signals: ${signals.length ? signals.map((s) => `"${s}"`).join(", ") : "(none)"}`);
         }
         try {
-            return (await this.sdk.correlateMessage({
+            return toJsonObject(await this.sdk.correlateMessage({
                 name: messageName(flow.id, signalName),
                 correlationKey,
                 variables,
@@ -154,7 +228,7 @@ export class WorkflowClient {
      *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     async getInstance(processInstanceKey) {
         try {
-            return (await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
+            return toJsonObject(await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
         }
         catch {
             return null;

package/dist/declarative.d.ts

@@ -3,18 +3,18 @@ import type { Envelope } from "./envelope.js";
 /** The TS payload type of a contract's input envelope (untyped fallback). */
 type InPayload<Ct> = Ct extends {
     in: Envelope;
-} ? Ct["in"]["type"] : JsonObject;
+} ? Ct["in"]["type"] & JsonObject : JsonObject;
 /** The TS payload type of a contract's output envelope (untyped fallback). */
 type OutPayload<Ct> = Ct extends {
     out: Envelope;
-} ? Ct["out"]["type"] : JsonObject;
+} ? Ct["out"]["type"] & JsonObject : JsonObject;
 /** The input payload type of step `K` under contracts `C`. */
 type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
 /** The output payload type of step `K` under contracts `C`. */
 type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : JsonObject;
 /** A typed handler for a `run` step: its job variables and result are resolved
  *  from the flow contracts by the step name. */
-type TypedHandler<V, R> = (job: {
+type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
     jobKey: string;
     processInstanceKey: string;
     elementId: string;

package/dist/declarative.js

@@ -41,6 +41,17 @@ import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTi
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
 const RESERVED_PREFIXES = /^(Gw_|Loop_|Sub_|Msg_|f_)/;
+const TIMER_START_KEYS = ["cycle", "after", "at"];
+function timerStartValue(spec, key) {
+    switch (key) {
+        case "cycle":
+            return "cycle" in spec ? spec.cycle : undefined;
+        case "after":
+            return "after" in spec ? spec.after : undefined;
+        case "at":
+            return "at" in spec ? spec.at : undefined;
+    }
+}
 function claimName(ctx, id, name) {
     assertIdent("step name", name);
     if (name === "Start" || name === "End" || name === id) {
@@ -106,12 +117,12 @@ function makeBuilder(id, out, ctx, isRoot = false) {
         },
         timer(name, opts) {
             claimName(ctx, id, name);
-            const hasAfter = typeof opts?.after === "string";
-            const hasAt = typeof opts?.at === "string";
+            const hasAfter = "after" in opts && typeof opts.after === "string";
+            const hasAt = "at" in opts && typeof opts.at === "string";
             if (hasAfter === hasAt) {
                 throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
             }
-            if (hasAfter) {
+            if ("after" in opts) {
                 const after = opts.after.trim();
                 assertTimerDuration(`timer("${name}") after`, after);
                 out.push({ kind: "timer", name, after });
@@ -131,16 +142,16 @@ function makeBuilder(id, out, ctx, isRoot = false) {
                 throw new Error(`startOn() must be the first statement in flow "${id}"`);
             if (ctx.startTimer)
                 throw new Error(`startOn() may be called only once in flow "${id}"`);
-            const set = ["cycle", "after", "at"].filter((k) => typeof spec?.[k] === "string");
-            if (set.length !== 1) {
+            const setCount = TIMER_START_KEYS.filter((key) => typeof timerStartValue(spec, key) === "string").length;
+            if (setCount !== 1) {
                 throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
             }
-            if (spec.cycle !== undefined) {
+            if ("cycle" in spec) {
                 const cycle = spec.cycle.trim();
                 assertTimerCycle(`startOn cycle`, cycle);
                 ctx.startTimer = { cycle };
             }
-            else if (spec.after !== undefined) {
+            else if ("after" in spec) {
                 const after = spec.after.trim();
                 assertTimerDuration(`startOn after`, after);
                 ctx.startTimer = { after };
@@ -156,10 +167,16 @@ function makeBuilder(id, out, ctx, isRoot = false) {
             if (typeof subject !== "string" || subject.trim() === "") {
                 throw new Error(`switch() needs a non-empty subject expression`);
             }
-            const entries = Object.entries(cases).filter(([k]) => k !== "default");
-            if (entries.length === 0)
+            const caseNodes = [];
+            for (const [value, fn] of Object.entries(cases)) {
+                if (value === "default")
+                    continue;
+                if (typeof fn !== "function")
+                    throw new Error(`switch("${subject}") cases must be blocks (b) => {…}`);
+                caseNodes.push({ value, body: child(fn, false) });
+            }
+            if (caseNodes.length === 0)
                 throw new Error(`switch("${subject}") needs at least one case`);
-            const caseNodes = entries.map(([value, fn]) => ({ value, body: child(fn, false) }));
             const def = cases.default ? child(cases.default, false) : undefined;
             out.push({ kind: "switch", subject, cases: caseNodes, default: def });
             return b;
@@ -274,14 +291,22 @@ export function defineFlow(id, second, third) {
         throw new Error(`defineFlow("${id}"): the contracts argument must be an object`);
     }
     const contracts = typeof second === "function" ? {} : second;
-    const build = (typeof second === "function" ? second : third);
-    if (typeof build !== "function") {
+    if (typeof second !== "function" && typeof third !== "function") {
         throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
     }
     const steps = [];
     const handlers = {};
     const ctx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-    build(makeBuilder(id, steps, ctx, true));
+    if (typeof second === "function") {
+        second(makeBuilder(id, steps, ctx, true));
+    }
+    else {
+        const build = third;
+        if (typeof build !== "function") {
+            throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
+        }
+        build(makeBuilder(id, steps, ctx, true));
+    }
     if (steps.length === 0)
         throw new Error(`flow "${id}" declared no steps`);
     const flow = { kind: "declarative", id, steps, handlers };
@@ -341,6 +366,16 @@ export function externalJobTypes(flow) {
     });
     return types;
 }
+function requireTimerAt(node) {
+    if (node.at === undefined)
+        throw new Error(`timer event is missing its { at } value`);
+    return node.at;
+}
+function requireStartAt(timer) {
+    if (timer.at === undefined)
+        throw new Error(`timer start is missing its { at } value`);
+    return timer.at;
+}
 class Compiler {
     flow;
     nodes = [];
@@ -429,7 +464,7 @@ class Compiler {
         const id = node.name;
         const body = node.after !== undefined
             ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
-            : `        <bpmn:timeDate>${escapeXml(node.at)}</bpmn:timeDate>\n`;
+            : `        <bpmn:timeDate>${escapeXml(requireTimerAt(node))}</bpmn:timeDate>\n`;
         this.nodes.push({
             id,
             scope: this.currentScope(),
@@ -660,7 +695,7 @@ class Compiler {
             ? `<bpmn:timeCycle>${escapeXml(t.cycle)}</bpmn:timeCycle>`
             : t.after !== undefined
                 ? `<bpmn:timeDuration>${escapeXml(t.after)}</bpmn:timeDuration>`
-                : `<bpmn:timeDate>${escapeXml(t.at)}</bpmn:timeDate>`;
+                : `<bpmn:timeDate>${escapeXml(requireStartAt(t))}</bpmn:timeDate>`;
         return (`    <bpmn:startEvent id="Start">\n` +
             `      ${outgoingOnly(outg)}\n` +
             `      <bpmn:timerEventDefinition>\n` +

package/dist/envelope.js

@@ -29,6 +29,15 @@ const SCALARS = new Set([
     "boolean",
     "datetime",
 ]);
+class EnvelopeDef {
+    name;
+    fields;
+    type;
+    constructor(name, fields) {
+        this.name = name;
+        this.fields = fields;
+    }
+}
 function normaliseField(name, spec) {
     if (spec === null || (typeof spec !== "string" && typeof spec !== "object")) {
         throw new Error(`envelope field "${name}": must be a scalar type or a { type, optional?, list? } object`);
@@ -56,7 +65,5 @@ export function envelope(name, fields) {
         throw new Error(`envelope "${name}" declares no fields`);
     for (const f of list)
         assertIdent("envelope field name", f.name);
-    // `type` is phantom: never read at runtime; the cast keeps the value shape
-    // minimal while the declared type carries the inference.
-    return { name, fields: list, type: undefined };
+    return new EnvelopeDef(name, list);
 }

package/dist/imperative.js

@@ -55,6 +55,17 @@ export function imperativeToBpmn(wf) {
         `</bpmn:definitions>\n`);
 }
 const SUSPEND = Symbol("nanobpm.workflow.suspend");
+class SuspendError extends Error {
+    [SUSPEND];
+    constructor(key, result) {
+        super("nanobpm.workflow suspend");
+        this[SUSPEND] = { key, result };
+    }
+}
+function assertReplayValue(_value, _name) {
+    // The journal value was recorded from the same ordinal/name run call on an
+    // earlier pass; TypeScript cannot express that cross-replay invariant.
+}
 /**
  * Replay the orchestration function against a journal. Returns `{ done: true }`
  * if the function ran to completion, or the frontier step (the one un-recorded
@@ -70,12 +81,13 @@ export async function replayOnce(wf, input, journal) {
         async run(name, fn) {
             const key = `${++ordinal}:${name}`;
             if (Object.prototype.hasOwnProperty.call(journal, key)) {
-                return journal[key]; // replay: return recorded value, no side effect
+                const value = journal[key];
+                assertReplayValue(value, name);
+                return value; // replay: return recorded value, no side effect
             }
-            const result = ((await fn()) ?? null); // frontier: the ONE real side effect this turn
-            const carrier = new Error("nanobpm.workflow suspend");
-            carrier[SUSPEND] = { key, result };
-            throw carrier;
+            const result = (await fn()) ?? null; // frontier: the ONE real side effect this turn
+            assertReplayValue(result, name);
+            throw new SuspendError(key, result);
         },
     };
     try {
@@ -83,9 +95,8 @@ export async function replayOnce(wf, input, journal) {
         return { done: true };
     }
     catch (e) {
-        const s = e[SUSPEND];
-        if (s)
-            return { done: false, frontier: s };
+        if (e instanceof SuspendError)
+            return { done: false, frontier: e[SUSPEND] };
         throw e; // a genuine error in the orchestration or a handler
     }
 }

package/dist/layout.js

@@ -16,6 +16,9 @@
 // stays authoritative. Re-run layout whenever the flow changes rather than
 // hand-editing the generated diagram.
 import { declarativeToBpmn } from "./declarative.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 /**
  * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
  * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
@@ -36,7 +39,7 @@ export async function layoutBpmn(bpmnXml) {
         // genuinely cannot be resolved. A different failure (the package is present
         // but fails to load — syntax, a broken transitive dep, a runtime throw at
         // import time) must surface as-is so it isn't masked as a missing dependency.
-        if (cause?.code !== "ERR_MODULE_NOT_FOUND") {
+        if (!isRecord(cause) || cause.code !== "ERR_MODULE_NOT_FOUND") {
             throw cause;
         }
         throw new Error('layoutBpmn requires the optional peer dependency "bpmn-auto-layout". ' +

package/dist/types.d.ts

@@ -34,7 +34,9 @@ export interface StepContract {
  *  untyped `JsonObject`. */
 export type FlowContracts = Record<string, StepContract>;
 /** Handler for a declarative `run` step: does real work, returns variables. */
-export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
+export type StepHandler<V extends JsonObject = JsonObject, R extends JsonObject = JsonObject> = {
+    bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
+}["bivarianceHack"];
 /** A node in a declarative flow tree. Leaf activities carry optional data
  *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
  *  combinators carry nested `FlowNode[]` bodies. */

package/dist/worker.js

@@ -17,6 +17,9 @@ import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
 import { walkNodes } from "./declarative.js";
 import { jobType } from "./xml.js";
+function isJsonObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 export class Worker {
     client;
     name;
@@ -47,13 +50,16 @@ export class Worker {
             this.addRoute(wf.orchestrateType, {
                 workflowId: wf.id,
                 handle: async (job) => {
-                    const input = job.variables.input ?? {};
-                    const journal = job.variables.journal ?? {};
+                    const input = isJsonObject(job.variables.input) ? job.variables.input : {};
+                    const journal = isJsonObject(job.variables.journal) ? job.variables.journal : {};
                     const step = await replayOnce(wf, input, journal);
-                    if (step.done)
-                        return { variables: { wfDone: true }, step: "__done" };
+                    if (step.done) {
+                        const variables = { wfDone: true };
+                        return { variables, step: "__done" };
+                    }
                     const next = { ...journal, [step.frontier.key]: step.frontier.result };
-                    return { variables: { journal: next, wfDone: false }, step: step.frontier.key };
+                    const variables = { journal: next, wfDone: false };
+                    return { variables, step: step.frontier.key };
                 },
             });
         }
@@ -76,7 +82,10 @@ export class Worker {
                 }
                 this.addRoute(jobType(wf.id, s.name), {
                     workflowId: wf.id,
-                    handle: async (job) => ({ variables: ((await handler(job)) ?? {}) }),
+                    handle: async (job) => {
+                        const variables = (await handler(job)) ?? {};
+                        return { variables };
+                    },
                 });
             });
         }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jwulf/nano-ide.git",
+    "url": "git+https://github.com/nanobpm/nano-ide.git",
     "directory": "packages/workflow"
   },
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@nanobpm/nano-sdk": "^1.2.3"
+    "@nanobpm/nano-sdk": "^1.2.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/client.ts

@@ -4,13 +4,60 @@
 // signals; the low-level job protocol used by the Worker runtime is the SDK's
 // own job worker, reached through the exposed `sdk` client.
 
-import { createCamundaClient } from "@nanobpm/nano-sdk";
+import { createCamundaClient, JobActionReceiptSymbol, ProcessDefinitionId, ProcessInstanceKey } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
-import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
+import type { DeclarativeFlow, DeployResult, Job, Json, JsonObject, StartResult, Workflow } from "./types.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function errorCause(e: unknown): unknown {
+  return isRecord(e) ? e.cause : undefined;
+}
+
+function errorCode(e: unknown): unknown {
+  return isRecord(e) ? e.code : undefined;
+}
+
+function errorMessage(e: unknown): string {
+  return isRecord(e) && typeof e.message === "string" ? e.message : String(e);
+}
+
+function errorStatus(e: unknown): number | undefined {
+  if (!isRecord(e)) return undefined;
+  if (typeof e.status === "number") return e.status;
+  const response = e.response;
+  return isRecord(response) && typeof response.status === "number" ? response.status : undefined;
+}
+
+function isJson(v: unknown): v is Json {
+  if (v === null) return true;
+  switch (typeof v) {
+    case "boolean":
+    case "number":
+    case "string":
+      return true;
+    case "object":
+      if (Array.isArray(v)) return v.every(isJson);
+      return Object.values(v).every(isJson);
+    default:
+      return false;
+  }
+}
+
+function toJsonObject(v: unknown): JsonObject {
+  if (!isRecord(v)) throw new Error("SDK response was not an object");
+  const result: JsonObject = {};
+  for (const [key, value] of Object.entries(v)) {
+    if (isJson(value)) result[key] = value;
+  }
+  return result;
+}
+
 /** Render a workflow (either surface) to its executable BPMN model. */
 export function toBpmn(wf: Workflow): string {
   assertWorkflowIds(wf);
@@ -43,8 +90,8 @@ export async function toDeployableBpmn(
     // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
     // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
     // problem and must surface rather than silently deploy an uninspectable model.
-    const cause = (e as { cause?: NodeJS.ErrnoException })?.cause;
-    if (cause?.code !== "ERR_MODULE_NOT_FOUND") throw e;
+    const cause = errorCause(e);
+    if (errorCode(cause) !== "ERR_MODULE_NOT_FOUND") throw e;
     if (!warnedNoLayout) {
       warnedNoLayout = true;
       console.warn(
@@ -69,20 +116,20 @@ export interface NanoSdkClient {
   createDeployment(
     input: { resources: File[]; [k: string]: unknown },
     options?: unknown,
-  ): Promise<Record<string, unknown>>;
+  ): Promise<unknown>;
   createProcessInstance(
     input: { processDefinitionId: string; variables?: JsonObject },
     options?: unknown,
-  ): Promise<Record<string, unknown>>;
+  ): Promise<unknown>;
   correlateMessage(
     input: { name: string; correlationKey: string; variables?: JsonObject },
     options?: unknown,
-  ): Promise<Record<string, unknown>>;
+  ): Promise<unknown>;
   getProcessInstance(
     input: { processInstanceKey: string },
     consistency: { consistency: { waitUpToMs: number } },
     options?: unknown,
-  ): Promise<Record<string, unknown>>;
+  ): Promise<unknown>;
   createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
 
@@ -156,9 +203,8 @@ export class WorkflowError extends Error {
  *  HTTP status when the SDK attached one. */
 function asWorkflowError(e: unknown, what: string): WorkflowError {
   if (e instanceof WorkflowError) return e;
-  const err = e as { message?: string; status?: number; response?: { status?: number } };
-  const status = err?.status ?? err?.response?.status;
-  return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+  const status = errorStatus(e);
+  return new WorkflowError(`${what} failed: ${errorMessage(e)}`, status);
 }
 
 export class WorkflowClient {
@@ -175,13 +221,49 @@ export class WorkflowClient {
       return;
     }
     if (!opts?.baseUrl) throw new Error("WorkflowClient needs a baseUrl or a client");
-    this.sdk = createCamundaClient({
+    const raw = createCamundaClient({
       config: {
         CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
         ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
         CAMUNDA_TRANSPORT: opts.transport ?? "auto",
       },
-    }) as unknown as NanoSdkClient;
+    });
+    this.sdk = {
+      createDeployment: (input) => raw.createDeployment(input),
+      createProcessInstance: (input) =>
+        raw.createProcessInstance(
+          {
+            ...input,
+            processDefinitionId: ProcessDefinitionId.assumeExists(input.processDefinitionId),
+          },
+        ),
+      correlateMessage: (input) => raw.correlateMessage(input),
+      getProcessInstance: (input, consistency) =>
+        raw.getProcessInstance(
+          {
+            processInstanceKey: ProcessInstanceKey.assumeExists(input.processInstanceKey),
+          },
+          consistency,
+        ),
+      createJobWorker: (cfg) => {
+        const worker = raw.createJobWorker({
+          ...cfg,
+          jobHandler: async (job) => {
+            await cfg.jobHandler(job);
+            return JobActionReceiptSymbol;
+          },
+        });
+        return {
+          start: () => {
+            void worker.start();
+          },
+          stop: () => worker.stop(),
+          stopGracefully: async (opts) => {
+            await worker.stopGracefully(opts);
+          },
+        };
+      },
+    };
   }
 
   /**
@@ -195,7 +277,7 @@ export class WorkflowClient {
     const xml = await toDeployableBpmn(wf, opts);
     const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
     try {
-      return (await this.sdk.createDeployment({ resources: [file] })) as DeployResult;
+      return toJsonObject(await this.sdk.createDeployment({ resources: [file] }));
     } catch (e) {
       throw asWorkflowError(e, "deploy");
     }
@@ -210,10 +292,10 @@ export class WorkflowClient {
     const variables: JsonObject =
       wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
     try {
-      return (await this.sdk.createProcessInstance({
+      return toJsonObject(await this.sdk.createProcessInstance({
         processDefinitionId: wf.id,
         variables,
-      })) as StartResult;
+      }));
     } catch (e) {
       throw asWorkflowError(e, "start");
     }
@@ -242,11 +324,11 @@ export class WorkflowClient {
       );
     }
     try {
-      return (await this.sdk.correlateMessage({
+      return toJsonObject(await this.sdk.correlateMessage({
         name: messageName(flow.id, signalName),
         correlationKey,
         variables,
-      })) as JsonObject;
+      }));
     } catch (e) {
       throw asWorkflowError(e, `signal "${signalName}"`);
     }
@@ -256,10 +338,10 @@ export class WorkflowClient {
    *  zero-wait consistency; returns null when the instance is not (yet) visible. */
   async getInstance(processInstanceKey: string): Promise<JsonObject | null> {
     try {
-      return (await this.sdk.getProcessInstance(
+      return toJsonObject(await this.sdk.getProcessInstance(
         { processInstanceKey },
         { consistency: { waitUpToMs: 0 } },
-      )) as JsonObject;
+      ));
     } catch {
       return null;
     }

package/src/declarative.ts

@@ -54,9 +54,9 @@ import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTi
 // --- Authoring surface -------------------------------------------------------
 
 /** The TS payload type of a contract's input envelope (untyped fallback). */
-type InPayload<Ct> = Ct extends { in: Envelope } ? Ct["in"]["type"] : JsonObject;
+type InPayload<Ct> = Ct extends { in: Envelope } ? Ct["in"]["type"] & JsonObject : JsonObject;
 /** The TS payload type of a contract's output envelope (untyped fallback). */
-type OutPayload<Ct> = Ct extends { out: Envelope } ? Ct["out"]["type"] : JsonObject;
+type OutPayload<Ct> = Ct extends { out: Envelope } ? Ct["out"]["type"] & JsonObject : JsonObject;
 /** The input payload type of step `K` under contracts `C`. */
 type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
 /** The output payload type of step `K` under contracts `C`. */
@@ -64,7 +64,7 @@ type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : Json
 
 /** A typed handler for a `run` step: its job variables and result are resolved
  *  from the flow contracts by the step name. */
-type TypedHandler<V, R> = (job: {
+type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
   jobKey: string;
   processInstanceKey: string;
   elementId: string;
@@ -209,6 +209,21 @@ interface BuilderCtx {
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
 const RESERVED_PREFIXES = /^(Gw_|Loop_|Sub_|Msg_|f_)/;
+const TIMER_START_KEYS = ["cycle", "after", "at"] as const;
+
+function timerStartValue(
+  spec: { cycle: string } | { after: string } | { at: string },
+  key: (typeof TIMER_START_KEYS)[number],
+): string | undefined {
+  switch (key) {
+    case "cycle":
+      return "cycle" in spec ? spec.cycle : undefined;
+    case "after":
+      return "after" in spec ? spec.after : undefined;
+    case "at":
+      return "at" in spec ? spec.at : undefined;
+  }
+}
 
 function claimName(ctx: BuilderCtx, id: string, name: string): void {
   assertIdent("step name", name);
@@ -255,81 +270,88 @@ function makeBuilder<C extends object>(
     fn(makeBuilder<C>(id, body, { ...ctx, loopDepth: 0 }));
     return body;
   };
-  const b = {
-    run(name: string, handler: StepHandler): FlowBuilder<C> {
+  const b: FlowBuilder<C> = {
+    run<K extends string>(
+      name: K,
+      handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>,
+    ): FlowBuilder<C> {
       claimName(ctx, id, name);
       if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
       ctx.handlers[name] = handler;
       out.push({ kind: "run", name, envelopes: contractEnvelopes(ctx, name) });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     task(name: string, opts?: { jobType?: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
       const override = opts?.jobType;
       if (override !== undefined) assertJobType("task jobType", override);
       out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name), jobType: override });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     signal(name: string, opts: { correlationKey: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
       if (!opts || !opts.correlationKey) throw new Error(`signal("${name}") needs { correlationKey }`);
       assertIdent("correlationKey", opts.correlationKey);
       out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
-    timer(name: string, opts: { after?: string; at?: string }): FlowBuilder<C> {
+    timer(name: string, opts: { after: string } | { at: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
-      const hasAfter = typeof opts?.after === "string";
-      const hasAt = typeof opts?.at === "string";
+      const hasAfter = "after" in opts && typeof opts.after === "string";
+      const hasAt = "at" in opts && typeof opts.at === "string";
       if (hasAfter === hasAt) {
         throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
       }
-      if (hasAfter) {
-        const after = (opts.after as string).trim();
+      if ("after" in opts) {
+        const after = opts.after.trim();
         assertTimerDuration(`timer("${name}") after`, after);
         out.push({ kind: "timer", name, after });
       } else {
-        const at = (opts.at as string).trim();
+        const at = opts.at.trim();
         assertTimerDate(`timer("${name}") at`, at);
         out.push({ kind: "timer", name, at });
       }
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
-    startOn(spec: { cycle?: string; after?: string; at?: string }): FlowBuilder<C> {
+    startOn(spec: { cycle: string } | { after: string } | { at: string }): FlowBuilder<C> {
       if (!isRoot) {
         throw new Error(`startOn() is only valid at the top level of flow "${id}" (not inside switch/branch/loop)`);
       }
       if (out.length !== 0) throw new Error(`startOn() must be the first statement in flow "${id}"`);
       if (ctx.startTimer) throw new Error(`startOn() may be called only once in flow "${id}"`);
-      const set = (["cycle", "after", "at"] as const).filter((k) => typeof spec?.[k] === "string");
-      if (set.length !== 1) {
+      const setCount = TIMER_START_KEYS.filter((key) => typeof timerStartValue(spec, key) === "string").length;
+      if (setCount !== 1) {
         throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
       }
-      if (spec.cycle !== undefined) {
+      if ("cycle" in spec) {
         const cycle = spec.cycle.trim();
         assertTimerCycle(`startOn cycle`, cycle);
         ctx.startTimer = { cycle };
-      } else if (spec.after !== undefined) {
+      } else if ("after" in spec) {
         const after = spec.after.trim();
         assertTimerDuration(`startOn after`, after);
         ctx.startTimer = { after };
       } else {
-        const at = (spec.at as string).trim();
+        const at = spec.at.trim();
         assertTimerDate(`startOn at`, at);
         ctx.startTimer = { at };
       }
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     switch(subject: string, cases: Record<string, Block<C>> & { default?: Block<C> }): FlowBuilder<C> {
       if (typeof subject !== "string" || subject.trim() === "") {
         throw new Error(`switch() needs a non-empty subject expression`);
       }
-      const entries = Object.entries(cases).filter(([k]) => k !== "default") as [string, Block<C>][];
-      if (entries.length === 0) throw new Error(`switch("${subject}") needs at least one case`);
-      const caseNodes: SwitchCase[] = entries.map(([value, fn]) => ({ value, body: child(fn, false) }));
+      const caseNodes: SwitchCase[] = [];
+      for (const [value, fn] of Object.entries(cases)) {
+        if (value === "default") continue;
+        if (typeof fn !== "function") throw new Error(`switch("${subject}") cases must be blocks (b) => {…}`);
+        caseNodes.push({ value, body: child(fn, false) });
+      }
+      if (caseNodes.length === 0) throw new Error(`switch("${subject}") needs at least one case`);
       const def = cases.default ? child(cases.default, false) : undefined;
       out.push({ kind: "switch", subject, cases: caseNodes, default: def });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     branch(condition: string, arms: { then: Block<C>; else?: Block<C> }): FlowBuilder<C> {
       if (typeof condition !== "string" || condition.trim() === "") {
@@ -342,12 +364,12 @@ function makeBuilder<C extends object>(
         then: child(arms.then, false),
         else: arms.else ? child(arms.else, false) : undefined,
       });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     loop(body: Block<C>): FlowBuilder<C> {
       if (typeof body !== "function") throw new Error(`loop() needs a body function`);
       out.push({ kind: "loop", body: child(body, true) });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     parallel(branches: Block<C>[]): FlowBuilder<C> {
       if (!Array.isArray(branches) || branches.length < 2) {
@@ -361,7 +383,7 @@ function makeBuilder<C extends object>(
       // loop. Scope branches (loopDepth resets to 0) so cross-boundary
       // break/continue is rejected at build time, matching forEach.
       out.push({ kind: "parallel", branches: branches.map((fn) => childScoped(fn)) });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     forEach(
       collection: string,
@@ -422,20 +444,20 @@ function makeBuilder<C extends object>(
         throw new Error(`forEach("${itemVar}") outputElement needs an outputCollection to collect into`);
       }
       out.push(node);
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     break(): FlowBuilder<C> {
       if (ctx.loopDepth === 0) throw new Error(`break() is only valid inside a loop`);
       out.push({ kind: "break" });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     continue(): FlowBuilder<C> {
       if (ctx.loopDepth === 0) throw new Error(`continue() is only valid inside a loop`);
       out.push({ kind: "continue" });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
   };
-  return b as unknown as FlowBuilder<C>;
+  return b;
 }
 
 /**
@@ -459,14 +481,21 @@ export function defineFlow(
     throw new Error(`defineFlow("${id}"): the contracts argument must be an object`);
   }
   const contracts: FlowContracts = typeof second === "function" ? {} : second;
-  const build = (typeof second === "function" ? second : third) as (w: FlowBuilder<FlowContracts>) => void;
-  if (typeof build !== "function") {
+  if (typeof second !== "function" && typeof third !== "function") {
     throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
   }
   const steps: FlowNode[] = [];
   const handlers: Record<string, StepHandler> = {};
   const ctx: BuilderCtx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-  build(makeBuilder<FlowContracts>(id, steps, ctx, true));
+  if (typeof second === "function") {
+    second(makeBuilder(id, steps, ctx, true));
+  } else {
+    const build = third;
+    if (typeof build !== "function") {
+      throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
+    }
+    build(makeBuilder<FlowContracts>(id, steps, ctx, true));
+  }
   if (steps.length === 0) throw new Error(`flow "${id}" declared no steps`);
   const flow: DeclarativeFlow = { kind: "declarative", id, steps, handlers };
   if (ctx.startTimer) flow.startTimer = ctx.startTimer;
@@ -522,6 +551,16 @@ export function externalJobTypes(flow: DeclarativeFlow): string[] {
   return types;
 }
 
+function requireTimerAt(node: { at?: string }): string {
+  if (node.at === undefined) throw new Error(`timer event is missing its { at } value`);
+  return node.at;
+}
+
+function requireStartAt(timer: TimerStart): string {
+  if (timer.at === undefined) throw new Error(`timer start is missing its { at } value`);
+  return timer.at;
+}
+
 // --- Model emitter (two-phase graph compiler) --------------------------------
 
 interface RenderNode {
@@ -645,7 +684,7 @@ class Compiler {
     const body =
       node.after !== undefined
         ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
-        : `        <bpmn:timeDate>${escapeXml(node.at as string)}</bpmn:timeDate>\n`;
+        : `        <bpmn:timeDate>${escapeXml(requireTimerAt(node))}</bpmn:timeDate>\n`;
     this.nodes.push({
       id,
       scope: this.currentScope(),
@@ -888,7 +927,7 @@ class Compiler {
         ? `<bpmn:timeCycle>${escapeXml(t.cycle)}</bpmn:timeCycle>`
         : t.after !== undefined
           ? `<bpmn:timeDuration>${escapeXml(t.after)}</bpmn:timeDuration>`
-          : `<bpmn:timeDate>${escapeXml(t.at as string)}</bpmn:timeDate>`;
+          : `<bpmn:timeDate>${escapeXml(requireStartAt(t))}</bpmn:timeDate>`;
     return (
       `    <bpmn:startEvent id="Start">\n` +
       `      ${outgoingOnly(outg)}\n` +

package/src/envelope.ts

@@ -93,6 +93,15 @@ const SCALARS: ReadonlySet<string> = new Set([
   "datetime",
 ]);
 
+class EnvelopeDef<S extends Record<string, FieldSpec>> implements Envelope<S> {
+  readonly type!: EnvelopeType<S>;
+
+  constructor(
+    readonly name: string,
+    readonly fields: EnvelopeField[],
+  ) {}
+}
+
 function normaliseField(name: string, spec: FieldSpec): EnvelopeField {
   if (spec === null || (typeof spec !== "string" && typeof spec !== "object")) {
     throw new Error(`envelope field "${name}": must be a scalar type or a { type, optional?, list? } object`);
@@ -124,7 +133,5 @@ export function envelope<const S extends Record<string, FieldSpec>>(
   const list = Object.entries(fields).map(([k, v]) => normaliseField(k, v));
   if (list.length === 0) throw new Error(`envelope "${name}" declares no fields`);
   for (const f of list) assertIdent("envelope field name", f.name);
-  // `type` is phantom: never read at runtime; the cast keeps the value shape
-  // minimal while the declared type carries the inference.
-  return { name, fields: list, type: undefined as unknown as EnvelopeType<S> };
+  return new EnvelopeDef(name, list);
 }

package/src/imperative.ts

@@ -64,8 +64,19 @@ export function imperativeToBpmn(wf: ImperativeWorkflow): string {
 export type Journal = Record<string, Json>;
 
 const SUSPEND = Symbol("nanobpm.workflow.suspend");
-interface SuspendCarrier {
-  [SUSPEND]?: { key: string; result: Json };
+
+class SuspendError extends Error {
+  readonly [SUSPEND]: { key: string; result: Json };
+
+  constructor(key: string, result: Json) {
+    super("nanobpm.workflow suspend");
+    this[SUSPEND] = { key, result };
+  }
+}
+
+function assertReplayValue<T extends Json>(_value: Json, _name: string): asserts _value is T {
+  // The journal value was recorded from the same ordinal/name run call on an
+  // earlier pass; TypeScript cannot express that cross-replay invariant.
 }
 
 /** Outcome of a single replay pass. */
@@ -92,20 +103,20 @@ export async function replayOnce(
     async run<T extends Json = Json>(name: string, fn: () => Promise<T> | T): Promise<T> {
       const key = `${++ordinal}:${name}`;
       if (Object.prototype.hasOwnProperty.call(journal, key)) {
-        return journal[key] as T; // replay: return recorded value, no side effect
+        const value = journal[key];
+        assertReplayValue<T>(value, name);
+        return value; // replay: return recorded value, no side effect
       }
-      const result = ((await fn()) ?? null) as T; // frontier: the ONE real side effect this turn
-      const carrier = new Error("nanobpm.workflow suspend") as Error & SuspendCarrier;
-      carrier[SUSPEND] = { key, result };
-      throw carrier;
+      const result = (await fn()) ?? null; // frontier: the ONE real side effect this turn
+      assertReplayValue<T>(result, name);
+      throw new SuspendError(key, result);
     },
   };
   try {
     await wf.orchestrate(ctx);
     return { done: true };
   } catch (e) {
-    const s = (e as SuspendCarrier)[SUSPEND];
-    if (s) return { done: false, frontier: s };
+    if (e instanceof SuspendError) return { done: false, frontier: e[SUSPEND] };
     throw e; // a genuine error in the orchestration or a handler
   }
 }

package/src/layout.ts

@@ -19,6 +19,10 @@
 import type { DeclarativeFlow } from "./types.js";
 import { declarativeToBpmn } from "./declarative.js";
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /**
  * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
  * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
@@ -38,7 +42,7 @@ export async function layoutBpmn(bpmnXml: string): Promise<string> {
     // genuinely cannot be resolved. A different failure (the package is present
     // but fails to load — syntax, a broken transitive dep, a runtime throw at
     // import time) must surface as-is so it isn't masked as a missing dependency.
-    if ((cause as NodeJS.ErrnoException | undefined)?.code !== "ERR_MODULE_NOT_FOUND") {
+    if (!isRecord(cause) || cause.code !== "ERR_MODULE_NOT_FOUND") {
       throw cause;
     }
     throw new Error(

package/src/types.ts

@@ -45,7 +45,12 @@ export interface StepContract {
 export type FlowContracts = Record<string, StepContract>;
 
 /** Handler for a declarative `run` step: does real work, returns variables. */
-export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
+export type StepHandler<
+  V extends JsonObject = JsonObject,
+  R extends JsonObject = JsonObject,
+> = {
+  bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
+}["bivarianceHack"];
 
 /** A node in a declarative flow tree. Leaf activities carry optional data
  *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural

package/src/worker.ts

@@ -70,6 +70,10 @@ export type WorkerOptions =
 
 type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
 
+function isJsonObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 export class Worker {
   private readonly client: WorkflowClient;
   private readonly name: string;
@@ -101,12 +105,16 @@ export class Worker {
       this.addRoute(wf.orchestrateType, {
         workflowId: wf.id,
         handle: async (job) => {
-          const input = (job.variables.input as JsonObject) ?? {};
-          const journal = (job.variables.journal as JsonObject) ?? {};
+          const input = isJsonObject(job.variables.input) ? job.variables.input : {};
+          const journal = isJsonObject(job.variables.journal) ? job.variables.journal : {};
           const step = await replayOnce(wf, input, journal);
-          if (step.done) return { variables: { wfDone: true } as JsonObject, step: "__done" };
+          if (step.done) {
+            const variables: JsonObject = { wfDone: true };
+            return { variables, step: "__done" };
+          }
           const next = { ...journal, [step.frontier.key]: step.frontier.result };
-          return { variables: { journal: next, wfDone: false } as JsonObject, step: step.frontier.key };
+          const variables: JsonObject = { journal: next, wfDone: false };
+          return { variables, step: step.frontier.key };
         },
       });
     } else {
@@ -129,7 +137,10 @@ export class Worker {
         }
         this.addRoute(jobType(wf.id, s.name), {
           workflowId: wf.id,
-          handle: async (job) => ({ variables: ((await handler(job)) ?? {}) as JsonObject }),
+          handle: async (job) => {
+            const variables: JsonObject = (await handler(job)) ?? {};
+            return { variables };
+          },
         });
       });
     }