bunqueue 2.8.49 → 2.8.50

package/dist/client/workflow/waitFor.js

@@ -12,6 +12,7 @@ import { hasSignal } from './storeSignals';
 import { clock } from './clock';
 /** Largest delay setTimeout accepts before wrapping (2**31-1 ms, ~24.8 days) */
 export const MAX_TIMER_MS = 2_147_483_647;
+const TIMEOUT_ENQUEUE_RETRY_MS = 5_000;
 /**
  * Arm the timer that re-enters a parked node once its wait budget elapses.
  *
@@ -21,31 +22,41 @@ export const MAX_TIMER_MS = 2_147_483_647;
  * (test/repro-workflow-timeout-overflow.test.ts).
  */
 export function scheduleTimeoutCheck(deps, execId, workflowName, nodeIdx, ms) {
-    const delay = Math.min(Math.max(ms, 0), MAX_TIMER_MS);
-    // Replacing a live timer for the same execution — re-entering a waitFor node used
-    // to leak the previous one, which then fired against a node the run had left.
-    const previous = deps.timers.get(execId);
-    if (previous)
-        clock().clearTimeout(previous);
-    const timer = clock().setTimeout(() => {
-        deps.timers.delete(execId);
-        const jobData = { executionId: execId, workflowName, nodeIndex: nodeIdx };
-        deps.queue.add('wf:step', jobData).catch(() => {
-            /* Queue may be closed */
-        });
-    }, delay);
-    // A parked approval gate is a NORMAL steady state, and the clamp above makes this
-    // timer up to ~24.8 days long. Without unref a process whose only remaining work is
-    // a parked run never exits, even after close(): the event loop stays alive holding a
-    // timer for a signal that may never come. unref keeps the timer fully functional
-    // while the process has other work, and stops it from being the reason to stay up.
-    // `clearTimers()` covers the explicit-shutdown path. This does NOT, on its own, let
-    // a parked engine's process exit: measured, a child that omits `close()` hangs with
-    // or without this line, because the embedded queue and worker pin the process
-    // independently. It is defence in depth for the timer itself, no more, and the
-    // earlier version of this comment claimed the stronger property.
-    timer.unref?.();
-    deps.timers.set(execId, timer);
+    const arm = (requestedDelay) => {
+        const delay = Math.min(Math.max(requestedDelay, 0), MAX_TIMER_MS);
+        // Replacing a live timer for the same execution — re-entering a waitFor node used
+        // to leak the previous one, which then fired against a node the run had left.
+        const previous = deps.timers.get(execId);
+        if (previous)
+            clock().clearTimeout(previous);
+        const timer = clock().setTimeout(() => {
+            const jobData = { executionId: execId, workflowName, nodeIndex: nodeIdx };
+            const published = () => {
+                // Keep the handle in the map while add() is pending. signal() and close() use
+                // deletion as cancellation; a late rejection must not resurrect their timer.
+                if (deps.timers.get(execId) === timer)
+                    deps.timers.delete(execId);
+            };
+            const failed = () => {
+                if (deps.timers.get(execId) !== timer)
+                    return;
+                arm(TIMEOUT_ENQUEUE_RETRY_MS);
+            };
+            try {
+                deps.queue
+                    .add('wf:step', jobData)
+                    .then(published, failed);
+            }
+            catch {
+                failed();
+            }
+        }, delay);
+        // A parked approval gate is a normal steady state. unref keeps its timer
+        // functional without making it the reason the process remains alive.
+        timer.unref?.();
+        deps.timers.set(execId, timer);
+    };
+    arm(ms);
 }
 /**
  * Cancel every armed wait timer. Called on engine shutdown: `unref` alone lets a
@@ -86,13 +97,15 @@ export async function runWaitFor(deps, exec, node, idx, wf) {
                 return;
             }
             deps.emitter?.emitSignal('signal:timeout', exec.id, exec.workflowName, node.event);
+            const timeoutReason = `Signal "${node.event}" timed out after ${node.timeout}ms`;
             exec.steps[waitKey] = {
                 status: 'failed',
                 startedAt: waitingSince,
                 completedAt: clock().now(),
-                error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
+                error: timeoutReason,
             };
             exec.state = 'failed';
+            exec.failureReason = timeoutReason;
             // Unguarded on purpose, same reasoning as the failure write in `executor.ts`. Disk
             // still says `waiting`, which `listRecoverable()` covers, so `recoverWaiting`
             // recomputes the remaining time, re-enqueues, and the gate times out again rather

package/dist/client/workflow/workflow.d.ts

@@ -5,67 +5,24 @@
  * Supports type-safe step chaining: each .step() narrows the return type
  * so subsequent steps can access previous results without casting.
  */
-import type { WorkflowNode, StepOptions, StepContext, BranchCondition, LoopCondition, ForEachItemsExtractor, TypedStepHandler } from './types';
-/**
- * Reject a workflow whose step names collide with the `name:index` namespace a loop
- * reserves for its iterations.
- *
- * A step literally called `process:0` next to a forEach called `process` is a real
- * collision, and both possible silent outcomes are corruption: the loop overwrites
- * the user's step, or — once iterations are memoised — the loop mistakes the user's
- * record for its own completed work and skips the iteration entirely. Neither can be
- * detected at runtime, so it has to be refused at registration.
- */
-/**
- * Two `waitFor` nodes on the SAME event cannot both gate.
- *
- * `exec.signals` is a permanent record keyed by event name and a wait is satisfied by
- * the key being present, so nothing marks a signal as consumed and nothing ties a
- * delivery to the gate that was waiting for it. A run shaped `waitFor('approve')`,
- * pay, `waitFor('approve')` is therefore walked end to end by ONE
- * `signal(id, 'approve')`: the second gate never pauses, because the key is already
- * there. A four-eyes control silently degrades to a one-eye control, and no state,
- * event or log records that a gate was skipped
- * (`test/repro-workflow-gate-and-schema.test.ts`).
- *
- * Refused at registration rather than fixed at runtime: consuming the signal would
- * change what `ctx.signals` means for every workflow already written, and a
- * build-time error cannot be missed, while a runtime one shows up when the money is
- * already moving. Distinct event names per gate are the correct shape and cost
- * nothing.
- */
-/**
- * Why an event name cannot be used as a gate, or `null` if it can.
- *
- * `__proto__` is refused because assignment to that name writes an object's PROTOTYPE
- * instead of creating an own key, so `SignalCoordinator.record()` stored the payload
- * nowhere: the gate never saw its own signal, re-parked, expired, and the unwind
- * reversed work the approver had authorised
- * (`test/repro-workflow-proto-gate-signal.test.ts`). Making it work instead would mean
- * reconciling the storage codec, which deliberately renames `__proto__` to `__proto_`
- * as its own pollution defence, so the gate would be stored under a different name
- * than it was signalled with. A gate with two spellings is not a gate.
- *
- * An empty or non-string name is refused for the plainer reason that nobody can
- * signal it, and two of them would be opened by one signal.
- */
-export declare function unusableEventName(event: unknown): string | null;
-export declare function assertNoDuplicateWaitFor(wf: {
-    name: string;
-    nodes: readonly {
-        type: string;
-        event?: string;
-    }[];
-}): void;
-export declare function assertNoIndexCollision(wf: {
-    name: string;
-    getStepNames(): string[];
-    getIndexedStepNames(): string[];
-}): void;
+import type { WorkflowNode, StepOptions, StepContext, BranchCondition, SubWorkflowOptions, LoopCondition, ForEachItemsExtractor, TypedStepHandler } from './types';
+export { assertNoDuplicateWaitFor, assertNoIndexCollision, unusableEventName, } from './workflowValidation';
 export declare class Workflow<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
     readonly name: string;
+    /**
+     * Explicit semantic revision. Bump it when handler or condition behavior changes
+     * incompatibly without changing the graph shape.
+     */
+    readonly revision: string;
     readonly nodes: WorkflowNode[];
-    constructor(name: string);
+    private sealed;
+    private sealedHash?;
+    constructor(name: string, options?: {
+        revision?: string | number;
+    });
+    /** Freeze this definition and return its durable structural identity. */
+    seal(): string;
+    private assertMutable;
     /** Add a step to the workflow — return type accumulates into TSteps */
     step<TName extends string, TResult>(name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps & Record<TName, Awaited<TResult>>>): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Add a branch point — call .path() after this to define paths */
@@ -75,7 +32,7 @@ export declare class Workflow<TInput = unknown, TSteps extends Record<string, un
     /** Run multiple steps in parallel — accumulated types from sub-builder merge into TSteps */
     parallel<TNewSteps extends Record<string, unknown>>(builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, TSteps & TNewSteps>): Workflow<TInput, TSteps & TNewSteps>;
     /** Call another registered workflow as a step */
-    subWorkflow<TName extends string>(name: TName, inputMapper: (ctx: StepContext<TInput, TSteps>) => unknown): Workflow<TInput, TSteps & Record<`sub:${TName}`, Record<string, unknown>>>;
+    subWorkflow<TName extends string>(name: TName, inputMapper: (ctx: StepContext<TInput, TSteps>) => unknown, options?: SubWorkflowOptions): Workflow<TInput, TSteps & Record<`sub:${TName}`, Record<string, unknown>>>;
     /** Wait for an external signal before continuing */
     waitFor(event: string, options?: {
         timeout?: number;

package/dist/client/workflow/workflow.js

@@ -5,152 +5,36 @@
  * Supports type-safe step chaining: each .step() narrows the return type
  * so subsequent steps can access previous results without casting.
  */
-/**
- * Extract the step definitions from a sub-builder, refusing anything else.
- *
- * Branch paths, parallel groups and loop bodies all execute inline inside a single
- * `wf:step` job, so they can only host plain steps — a `waitFor` there has no node
- * index to park at, a nested `branch` has no dispatcher. These used to be filtered
- * out silently, which turned an approval gate written inside a path into a no-op the
- * run sailed straight through (test/repro-workflow-guide-claims.test.ts). Failing at
- * build time is the only safe answer: the alternative is skipping a human approval
- * and reporting success.
- */
-function onlySteps(sub, where, label) {
-    const rejected = sub.nodes.filter((n) => n.type !== 'step');
-    if (rejected.length > 0) {
-        const kinds = [...new Set(rejected.map((n) => n.type))].join(', ');
-        const which = label ? ` (path "${label}")` : '';
-        throw new Error(`${where} accepts step() nodes only${which}, but received: ${kinds}. ` +
-            `Move those nodes to the top level of the workflow, or extract them into a ` +
-            `separate workflow and call it with subWorkflow().`);
-    }
-    return sub.nodes
-        .filter((n) => n.type === 'step')
-        .map((n) => n.def);
-}
-/**
- * Reject a workflow whose step names collide with the `name:index` namespace a loop
- * reserves for its iterations.
- *
- * A step literally called `process:0` next to a forEach called `process` is a real
- * collision, and both possible silent outcomes are corruption: the loop overwrites
- * the user's step, or — once iterations are memoised — the loop mistakes the user's
- * record for its own completed work and skips the iteration entirely. Neither can be
- * detected at runtime, so it has to be refused at registration.
- */
-/**
- * Two `waitFor` nodes on the SAME event cannot both gate.
- *
- * `exec.signals` is a permanent record keyed by event name and a wait is satisfied by
- * the key being present, so nothing marks a signal as consumed and nothing ties a
- * delivery to the gate that was waiting for it. A run shaped `waitFor('approve')`,
- * pay, `waitFor('approve')` is therefore walked end to end by ONE
- * `signal(id, 'approve')`: the second gate never pauses, because the key is already
- * there. A four-eyes control silently degrades to a one-eye control, and no state,
- * event or log records that a gate was skipped
- * (`test/repro-workflow-gate-and-schema.test.ts`).
- *
- * Refused at registration rather than fixed at runtime: consuming the signal would
- * change what `ctx.signals` means for every workflow already written, and a
- * build-time error cannot be missed, while a runtime one shows up when the money is
- * already moving. Distinct event names per gate are the correct shape and cost
- * nothing.
- */
-/**
- * Why an event name cannot be used as a gate, or `null` if it can.
- *
- * `__proto__` is refused because assignment to that name writes an object's PROTOTYPE
- * instead of creating an own key, so `SignalCoordinator.record()` stored the payload
- * nowhere: the gate never saw its own signal, re-parked, expired, and the unwind
- * reversed work the approver had authorised
- * (`test/repro-workflow-proto-gate-signal.test.ts`). Making it work instead would mean
- * reconciling the storage codec, which deliberately renames `__proto__` to `__proto_`
- * as its own pollution defence, so the gate would be stored under a different name
- * than it was signalled with. A gate with two spellings is not a gate.
- *
- * An empty or non-string name is refused for the plainer reason that nobody can
- * signal it, and two of them would be opened by one signal.
- */
-export function unusableEventName(event) {
-    if (typeof event !== 'string' || event.length === 0)
-        return 'with no event name';
-    if (event === '__proto__') {
-        return 'named "__proto__", which cannot be stored as a signal key and would never receive its signal';
-    }
-    return null;
-}
-export function assertNoDuplicateWaitFor(wf) {
-    const seen = new Set();
-    for (const node of wf.nodes) {
-        if (node.type !== 'waitFor')
-            continue;
-        // Skipping a nameless gate here would reopen the very bypass this function
-        // exists to close: two `waitFor(undefined)` nodes registered cleanly and one
-        // `signal(id, undefined)` walked both. Not theoretical either, since
-        // `noUncheckedIndexedAccess` is off: `.waitFor(gates.manager)` on a
-        // `Record<string, string>` with a missing key types as `string`, is `undefined` at
-        // runtime, and compiles. A gate nobody can name is a gate nobody can open, so it
-        // is refused outright rather than ignored.
-        const bad = unusableEventName(node.event);
-        if (bad !== null)
-            throw new Error(`Workflow "${wf.name}" has a waitFor gate ${bad}`);
-        // Narrowed by the guard above: `unusableEventName` returns null only for a
-        // non-empty string.
-        const event = node.event;
-        if (seen.has(event)) {
-            throw new Error(`Workflow "${wf.name}" waits for the event "${event}" more than once. ` +
-                `One signal would open every one of those gates, because a delivered signal ` +
-                `is never consumed. Give each gate its own event name.`);
-        }
-        seen.add(event);
-    }
-}
-export function assertNoIndexCollision(wf) {
-    const generators = wf.getIndexedStepNames();
-    if (generators.length === 0)
-        return;
-    for (const declared of wf.getStepNames()) {
-        for (const base of generators) {
-            if (declared !== base && new RegExp(`^${escapeRe(base)}:\\d+$`).test(declared)) {
-                throw new Error(`Step "${declared}" in "${wf.name}" collides with the per-iteration names ` +
-                    `reserved by the loop step "${base}" ("${base}:0", "${base}:1", ...). ` +
-                    `Rename one of them.`);
-            }
-        }
-    }
-}
-function escapeRe(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * `retry` is the number of ATTEMPTS, not the number of extra tries: the retry loop is
- * `for (attempt = 1; attempt <= def.retry; attempt++)`.
- *
- * `retry: 0` therefore never executed the body at all, and the code after the loop read
- * `exec.steps[def.name].startedAt` on a record that was never written, so the run's
- * `failureReason` became `undefined is not an object (...)`: a TypeError where an operator
- * looks for what went wrong. In a RESUMED loop the memo path restores the bare record, so
- * `startedAt` resolves and a `failed` record is written for a handler that was never
- * called, which the unwind then reverses: a rollback of a side effect that never happened
- * (`test/repro-workflow-retry-zero.test.ts`).
- *
- * Refused where it is written rather than coerced to 1. A workflow asking for zero
- * attempts is asking for something the engine cannot do, and quietly running the step
- * once would be a different thing from what was written.
- */
-function assertUsableRetry(step, retry) {
-    if (retry === undefined)
-        return;
-    if (!Number.isInteger(retry) || retry < 1) {
-        throw new Error(`Step "${step}" declares retry: ${retry}. retry is the number of attempts, so it must be an integer of 1 or more (1 means a single attempt with no retry).`);
-    }
-}
+import { assertPositiveDuration, assertUsableIterations, assertUsableRetry, assertUsableTimeout, onlySteps, } from './workflowValidation';
+import { sealWorkflowDefinition } from './workflowDefinition';
+import { indexedStepNames, stepNames } from './workflowIntrospection';
+export { assertNoDuplicateWaitFor, assertNoIndexCollision, unusableEventName, } from './workflowValidation';
 export class Workflow {
     name;
+    /**
+     * Explicit semantic revision. Bump it when handler or condition behavior changes
+     * incompatibly without changing the graph shape.
+     */
+    revision;
     nodes = [];
-    constructor(name) {
+    sealed = false;
+    sealedHash;
+    constructor(name, options = {}) {
         this.name = name;
+        this.revision = String(options.revision ?? '1');
+    }
+    /** Freeze this definition and return its durable structural identity. */
+    seal() {
+        if (!this.sealedHash) {
+            this.sealedHash = sealWorkflowDefinition(this);
+            this.sealed = true;
+        }
+        return this.sealedHash;
+    }
+    assertMutable() {
+        if (this.sealed) {
+            throw new Error(`Workflow "${this.name}" definition is sealed after registration`);
+        }
     }
     /** Add a step to the workflow — return type accumulates into TSteps */
     step(name, handler, 
@@ -159,7 +43,9 @@ export class Workflow {
     // omit, so `ctx.steps.charge` inside charge's own rollback was a type error while
     // working perfectly at run time.
     options) {
+        this.assertMutable();
         assertUsableRetry(name, options?.retry);
+        assertUsableTimeout(`Step "${name}"`, options?.timeout);
         this.nodes.push({
             type: 'step',
             def: {
@@ -176,6 +62,7 @@ export class Workflow {
     }
     /** Add a branch point — call .path() after this to define paths */
     branch(condition) {
+        this.assertMutable();
         this.nodes.push({
             type: 'branch',
             def: { condition: condition, paths: new Map() },
@@ -184,10 +71,14 @@ export class Workflow {
     }
     /** Define a branch path (must follow a .branch() call) */
     path(name, builder) {
+        this.assertMutable();
         const lastNode = this.nodes[this.nodes.length - 1];
         if (lastNode?.type !== 'branch') {
             throw new Error('path() must follow a branch() call');
         }
+        if (lastNode.def.paths.has(name)) {
+            throw new Error(`Branch path "${name}" is already defined`);
+        }
         const sub = new Workflow(`${this.name}:${name}`);
         builder(sub);
         lastNode.def.paths.set(name, onlySteps(sub, 'path()', name));
@@ -195,6 +86,7 @@ export class Workflow {
     }
     /** Run multiple steps in parallel — accumulated types from sub-builder merge into TSteps */
     parallel(builder) {
+        this.assertMutable();
         const sub = new Workflow(`${this.name}:parallel`);
         builder(sub);
         const steps = onlySteps(sub, 'parallel()');
@@ -205,21 +97,30 @@ export class Workflow {
         return this;
     }
     /** Call another registered workflow as a step */
-    subWorkflow(name, inputMapper) {
+    subWorkflow(name, inputMapper, options) {
+        this.assertMutable();
+        assertPositiveDuration(`Sub-workflow "${name}" timeout`, options?.timeout);
+        assertPositiveDuration(`Sub-workflow "${name}" pollInterval`, options?.pollInterval);
         this.nodes.push({
             type: 'subWorkflow',
             name,
             inputMapper: inputMapper,
+            timeout: options?.timeout ?? 300_000,
+            pollInterval: options?.pollInterval ?? 100,
         });
         return this;
     }
     /** Wait for an external signal before continuing */
     waitFor(event, options) {
+        this.assertMutable();
+        assertUsableTimeout(`waitFor("${event}")`, options?.timeout);
         this.nodes.push({ type: 'waitFor', event, timeout: options?.timeout });
         return this;
     }
     /** Repeat steps until condition returns true (checked after each iteration) */
     doUntil(condition, builder, options) {
+        this.assertMutable();
+        assertUsableIterations('doUntil()', options?.maxIterations);
         const sub = new Workflow(`${this.name}:doUntil`);
         builder(sub);
         const steps = onlySteps(sub, 'doUntil()');
@@ -237,6 +138,8 @@ export class Workflow {
     }
     /** Repeat steps while condition returns true (checked before each iteration) */
     doWhile(condition, builder, options) {
+        this.assertMutable();
+        assertUsableIterations('doWhile()', options?.maxIterations);
         const sub = new Workflow(`${this.name}:doWhile`);
         builder(sub);
         const steps = onlySteps(sub, 'doWhile()');
@@ -254,10 +157,13 @@ export class Workflow {
     }
     /** Iterate over items, executing a step for each */
     forEach(items, name, handler, options) {
+        this.assertMutable();
         // `forEach` builds its step definition here rather than going through `step()`, so it
         // needs the same guard: without it, `forEach(..., { retry: 0 })` was accepted and the
         // per-iteration mirror recorded a `failed` record for a handler that never ran.
         assertUsableRetry(name, options?.retry);
+        assertUsableTimeout(`forEach step "${name}"`, options?.timeout);
+        assertUsableIterations('forEach()', options?.maxIterations);
         const step = {
             name,
             handler: handler,
@@ -279,6 +185,7 @@ export class Workflow {
     }
     /** Transform step results into a new value stored under the given name */
     map(name, transform) {
+        this.assertMutable();
         this.nodes.push({
             type: 'map',
             def: { name, transform: transform },
@@ -294,6 +201,7 @@ export class Workflow {
      * for "the welcome email was sent". Declare it explicitly; it is never inferred.
      */
     pivot() {
+        this.assertMutable();
         this.nodes.push({ type: 'pivot' });
         return this;
     }
@@ -302,44 +210,10 @@ export class Workflow {
      * Loop bodies and forEach steps both do; a plain step never does.
      */
     getIndexedStepNames() {
-        const names = [];
-        for (const node of this.nodes) {
-            if (node.type === 'doUntil' || node.type === 'doWhile') {
-                for (const s of node.def.steps)
-                    names.push(s.name);
-            }
-            else if (node.type === 'forEach')
-                names.push(node.def.step.name);
-        }
-        return names;
+        return indexedStepNames(this.nodes);
     }
     /** Get flat list of step names for validation */
     getStepNames() {
-        const names = [];
-        for (const node of this.nodes) {
-            if (node.type === 'step')
-                names.push(node.def.name);
-            else if (node.type === 'branch') {
-                for (const steps of node.def.paths.values()) {
-                    for (const s of steps)
-                        names.push(s.name);
-                }
-            }
-            else if (node.type === 'parallel') {
-                for (const s of node.def.steps)
-                    names.push(s.name);
-            }
-            else if (node.type === 'subWorkflow')
-                names.push(`sub:${node.name}`);
-            else if (node.type === 'doUntil' || node.type === 'doWhile') {
-                for (const s of node.def.steps)
-                    names.push(s.name);
-            }
-            else if (node.type === 'forEach')
-                names.push(node.def.step.name);
-            else if (node.type === 'map')
-                names.push(node.def.name);
-        }
-        return names;
+        return stepNames(this.nodes);
     }
 }

package/dist/client/workflow/workflowDecisions.d.ts

@@ -0,0 +1,11 @@
+/** Durable control-flow decision journal. */
+import type { Execution } from './types';
+/**
+ * Return an already persisted decision, or evaluate and persist it before the caller
+ * performs any effects selected by that decision.
+ */
+export declare function resolveDecision<T>(exec: Execution, key: string, evaluate: () => T | Promise<T>, updateFn: (exec: Execution) => void): Promise<T>;
+export declare function branchDecisionKey(nodeIndex: number): string;
+export declare function forEachItemsDecisionKey(stepName: string): string;
+export declare function loopDecisionKey(kind: 'doUntil' | 'doWhile', firstStepName: string, iteration: number): string;
+export declare function subWorkflowInputDecisionKey(nodeIndex: number): string;

package/dist/client/workflow/workflowDecisions.js

@@ -0,0 +1,27 @@
+/** Durable control-flow decision journal. */
+const hasOwn = (value, key) => Object.hasOwn(value, key);
+/**
+ * Return an already persisted decision, or evaluate and persist it before the caller
+ * performs any effects selected by that decision.
+ */
+export async function resolveDecision(exec, key, evaluate, updateFn) {
+    const decisions = (exec.decisions ??= {});
+    if (hasOwn(decisions, key))
+        return decisions[key];
+    const value = await evaluate();
+    decisions[key] = value;
+    updateFn(exec);
+    return value;
+}
+export function branchDecisionKey(nodeIndex) {
+    return `branch:${nodeIndex}`;
+}
+export function forEachItemsDecisionKey(stepName) {
+    return `forEach:${stepName}:items`;
+}
+export function loopDecisionKey(kind, firstStepName, iteration) {
+    return `${kind}:${firstStepName}:${iteration}`;
+}
+export function subWorkflowInputDecisionKey(nodeIndex) {
+    return `subWorkflow:${nodeIndex}:input`;
+}

package/dist/client/workflow/workflowDefinition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stable workflow-definition identity and sealing.
+ *
+ * Executions persist the hash produced here. It describes the durable graph, while
+ * `revision` lets callers explicitly mark handler/condition changes that cannot be
+ * inferred safely from closures.
+ */
+import type { WorkflowNode } from './types';
+interface WorkflowDefinitionSource {
+    readonly name: string;
+    readonly revision: string;
+    readonly nodes: WorkflowNode[];
+}
+export declare function workflowDefinitionHash(workflow: WorkflowDefinitionSource): string;
+export declare function sealWorkflowDefinition(workflow: WorkflowDefinitionSource): string;
+export {};