@voyant-travel/workflows-orchestrator 0.107.10

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { registerRunAbort, signalRunAbort, unregisterRunAbort, } from "./abort-registry.js";
+export { type ConcurrencyRunHooks, createInProcessConcurrencyCoordinator, type InProcessConcurrencyCoordinator, type RuntimeConcurrencyPolicy, resolveConcurrencyKey, WorkflowConcurrencyRejectedError, } from "./concurrency.js";
+export { applyWaitpointInjection, type DriveOptions, driveUntilPaused } from "./drive.js";
+export { createInMemoryDriver, type InMemoryDriverOptions, } from "./driver-inmemory.js";
+export { type RouteEventArgs, type RouterMatch, routeEvent, } from "./event-router.js";
+export { createHttpStepHandler, type HttpStepHandlerDeps, type HttpStepTarget, } from "./http-step-handler.js";
+export { createInMemoryRunStore } from "./in-memory-store.js";
+export { emptyJournal } from "./journal-helpers.js";
+export { type CancelArgs, cancel, type OrchestratorDeps, type ResumeArgs, type ResumeDueAlarmsArgs, resume, resumeDueAlarms, type TriggerArgs, trigger, } from "./orchestrator.js";
+export { type BuildResumeJournalInput, type BuildResumeJournalResult, type BuildSeededResumeJournalInput, buildResumeJournal, buildSeededResumeJournal, } from "./resume-run.js";
+export { type CronSpec, computeNextFire, createScheduler, manifestScheduleSources, nextCronFire, parseCron, type SchedulableDeclaration, type SchedulerDeps, type SchedulerHandle, type ScheduleSource, toMs, } from "./schedule.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,mBAAmB,EACxB,qCAAqC,EACrC,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,uBAAuB,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACzF,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EACL,KAAK,UAAU,EACf,MAAM,EACN,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,MAAM,EACN,eAAe,EACf,KAAK,WAAW,EAChB,OAAO,GACR,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,SAAS,EACT,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,IAAI,GACL,MAAM,eAAe,CAAA;AACtB,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,22 @@
+// @voyant-travel/workflows-orchestrator
+//
+// Reference orchestrator for Voyant Workflows. Drives runs through
+// the tenant step handler over the v1 wire protocol. Transport- and
+// storage-agnostic: compose with a RunRecordStore of your choice
+// (in-memory for tests, Postgres-backed for production).
+//
+// See docs/runtime-protocol.md §2 + §5 for the contract this
+// implements and docs/design.md §6 for the broader orchestrator
+// state-machine design.
+export { registerRunAbort, signalRunAbort, unregisterRunAbort, } from "./abort-registry.js";
+export { createInProcessConcurrencyCoordinator, resolveConcurrencyKey, WorkflowConcurrencyRejectedError, } from "./concurrency.js";
+export { applyWaitpointInjection, driveUntilPaused } from "./drive.js";
+export { createInMemoryDriver, } from "./driver-inmemory.js";
+export { routeEvent, } from "./event-router.js";
+export { createHttpStepHandler, } from "./http-step-handler.js";
+export { createInMemoryRunStore } from "./in-memory-store.js";
+export { emptyJournal } from "./journal-helpers.js";
+export { cancel, resume, resumeDueAlarms, trigger, } from "./orchestrator.js";
+export { buildResumeJournal, buildSeededResumeJournal, } from "./resume-run.js";
+export { computeNextFire, createScheduler, manifestScheduleSources, nextCronFire, parseCron, toMs, } from "./schedule.js";
+export * from "./types.js";

package/dist/journal-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { JournalSlice } from "@voyant-travel/workflows/protocol";
+export declare function emptyJournal(): JournalSlice;
+//# sourceMappingURL=journal-helpers.d.ts.map

package/dist/journal-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-helpers.d.ts","sourceRoot":"","sources":["../src/journal-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAA;AAErE,wBAAgB,YAAY,IAAI,YAAY,CAQ3C"}

package/dist/journal-helpers.js

@@ -0,0 +1,9 @@
+export function emptyJournal() {
+    return {
+        stepResults: {},
+        waitpointsResolved: {},
+        compensationsRun: {},
+        metadataState: {},
+        streamsCompleted: {},
+    };
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,116 @@
+import type { Duration } from "@voyant-travel/workflows";
+import { type DriveOptions } from "./drive.js";
+import type { JournalSlice, RunRecord, RunRecordStore, RunTrigger, StepHandler, WaitpointInjection } from "./types.js";
+export interface TriggerArgs {
+    workflowId: string;
+    workflowVersion: string;
+    input: unknown;
+    tenantMeta: RunRecord["tenantMeta"];
+    environment?: RunRecord["environment"];
+    triggeredBy?: RunTrigger;
+    tags?: string[];
+    runNumber?: number;
+    /** Optional id to use; defaults to `run_` + crypto random. */
+    runId?: string;
+    /**
+     * Caller-supplied idempotency token. When set and the caller did not
+     * explicitly pass `runId`, the orchestrator derives a deterministic
+     * runId from `(workflowId, idempotencyKey)` so retries of the same
+     * trigger return the same run record without re-driving. The key is
+     * also persisted onto `RunRecord.idempotencyKey` so persistent stores
+     * can populate dedup columns / unique indexes natively.
+     *
+     * See architecture doc §15.2 for the full ingest-side derivation
+     * (eventId → idempotencyKey via `${filterId}:${eventId}`).
+     */
+    idempotencyKey?: string;
+    /**
+     * Optional trigger-time delay. When set to a future instant, the
+     * orchestrator persists the run in `waiting` on a synthetic DATETIME
+     * waitpoint and leaves execution to the normal wakeup/time-wheel path.
+     */
+    delay?: Duration | Date;
+    /** Higher values are claimed first by scheduler/time-wheel stores. */
+    priority?: number;
+    /**
+     * Optional journal seed. Used by external replay/resume callers
+     * that need a new run to skip steps already completed by a parent
+     * run.
+     */
+    initialJournal?: JournalSlice;
+    /**
+     * Metadata cursor paired with `initialJournal`. Resume callers that
+     * seed a journal with an existing `metadataState` must also seed the
+     * positional cursor so replayed metadata mutations are not applied
+     * twice.
+     */
+    initialMetadataAppliedCount?: number;
+    /**
+     * Compute-time budget in ms, typically from `WorkflowConfig.timeout`.
+     * Parked time on waitpoints does not count against this. When the
+     * cumulative invocation time exceeds it, the run ends `failed`
+     * with `code: "WORKFLOW_TIMEOUT"`. Undefined / 0 = no limit.
+     */
+    timeoutMs?: number;
+    /**
+     * For child runs spawned by `ctx.invoke` on a parent that may park.
+     * When set, the orchestrator records it on the child's record so
+     * the child's terminal status cascade-resumes the parent.
+     */
+    parent?: {
+        runId: string;
+        waitpointId: string;
+    };
+    /**
+     * Internal lifecycle hook used by driver-level coordinators that need
+     * the persisted run id before the first invocation starts.
+     */
+    onRunRecordCreated?: (record: RunRecord) => void;
+}
+export interface OrchestratorDeps extends DriveOptions {
+    store: RunRecordStore;
+    handler: StepHandler;
+    /** id generator; defaults to `run_<random>`. */
+    idGenerator?: () => string;
+}
+export declare function trigger(args: TriggerArgs, deps: OrchestratorDeps): Promise<RunRecord>;
+export interface ResumeArgs {
+    runId: string;
+    injection: WaitpointInjection;
+}
+export declare function resume(args: ResumeArgs, deps: OrchestratorDeps): Promise<{
+    ok: true;
+    record: RunRecord;
+} | {
+    ok: false;
+    status: "not_found" | "not_parked" | "no_match";
+    message: string;
+}>;
+export interface ResumeDueAlarmsArgs {
+    runId: string;
+}
+/**
+ * Resolve every DATETIME waitpoint whose `wakeAt` has passed, drive
+ * the run forward, and persist. Returns the saved record, or null
+ * when the run isn't in `waiting` state (already terminal / running
+ * elsewhere), or when no DATETIME waitpoints are actually due yet —
+ * both are no-ops that the caller can treat as "nothing to do."
+ *
+ * Callers (local serve loop, CF DO alarm handler) are responsible for
+ * scheduling the actual wake-up timer. This function is transport-
+ * agnostic: given `now()`, it does the resolve + drive + save.
+ */
+export declare function resumeDueAlarms(args: ResumeDueAlarmsArgs, deps: OrchestratorDeps): Promise<RunRecord | null>;
+export interface CancelArgs {
+    runId: string;
+    reason?: string;
+}
+export declare function cancel(args: CancelArgs, deps: OrchestratorDeps): Promise<{
+    ok: true;
+    record: RunRecord;
+} | {
+    ok: false;
+    status: "not_found" | "already_terminal";
+    message: string;
+}>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator.js

@@ -0,0 +1,411 @@
+// agent-quality: file-size exception -- owner: workflows-orchestrator; existing module stays co-located until a dedicated split preserves behavior and tests.
+// Public entry points for the reference orchestrator.
+//
+// `trigger()` creates a RunRecord, drives it forward through the
+// tenant handler, and persists the resulting record.
+// `resume()` accepts a waitpoint injection for a parked run, applies
+// it, drives forward, and persists.
+// `cancel()` closes out a run without running compensations (they
+// must come from the tenant handler, not the orchestrator).
+import { registerRunAbort, signalRunAbort, unregisterRunAbort } from "./abort-registry.js";
+import { applyWaitpointInjection, driveUntilPaused } from "./drive.js";
+import { emptyJournal } from "./journal-helpers.js";
+export async function trigger(args, deps) {
+    const now = deps.now ?? (() => Date.now());
+    const createdAt = now();
+    // Idempotency: caller-supplied `runId` wins (explicit). Otherwise, when
+    // `idempotencyKey` is supplied, derive a deterministic runId from
+    // `(workflowId, idempotencyKey)`. We then route through `store.tryInsert`
+    // — atomic check-or-insert — so concurrent triggers with the same
+    // derived runId never both proceed to drive (architecture doc §15.2,
+    // closes the race the get-then-save pattern leaves open).
+    const explicitRunId = args.runId;
+    const idempotencyKey = args.idempotencyKey;
+    const derivedRunId = idempotencyKey !== undefined ? `idem-${args.workflowId}-${idempotencyKey}` : undefined;
+    const id = explicitRunId ?? derivedRunId ?? deps.idGenerator?.() ?? defaultRunId(now);
+    const isIdempotent = explicitRunId !== undefined || derivedRunId !== undefined;
+    const delayWakeAt = resolveDelayWakeAt(args.delay, createdAt);
+    const record = {
+        id,
+        workflowId: args.workflowId,
+        workflowVersion: args.workflowVersion,
+        status: delayWakeAt !== undefined ? "waiting" : "running",
+        input: args.input,
+        journal: args.initialJournal ? cloneJournal(args.initialJournal) : emptyJournal(),
+        invocationCount: 0,
+        metadataAppliedCount: args.initialMetadataAppliedCount ?? 0,
+        computeTimeMs: 0,
+        timeoutMs: args.timeoutMs,
+        priority: args.priority,
+        parent: args.parent,
+        pendingWaitpoints: delayWakeAt !== undefined
+            ? [
+                {
+                    clientWaitpointId: triggerDelayWaitpointId(id),
+                    kind: "DATETIME",
+                    meta: {
+                        wakeAt: delayWakeAt,
+                        durationMs: Math.max(0, delayWakeAt - createdAt),
+                        source: "trigger.delay",
+                    },
+                },
+            ]
+            : [],
+        streams: {},
+        startedAt: delayWakeAt ?? createdAt,
+        triggeredBy: args.triggeredBy ?? { kind: "api" },
+        tags: args.tags ?? [],
+        environment: args.environment ?? "development",
+        tenantMeta: args.tenantMeta,
+        runMeta: { number: args.runNumber ?? 1, attempt: 1 },
+        idempotencyKey,
+    };
+    // Idempotent path uses tryInsert; non-idempotent (auto-generated) ids
+    // can't collide so the existing save() is sufficient.
+    if (isIdempotent) {
+        const result = await deps.store.tryInsert(record);
+        if (!result.created) {
+            // Another caller raced in first. Return their record without
+            // re-driving — drive() is what actually fires side effects.
+            return result.record;
+        }
+        args.onRunRecordCreated?.(record);
+    }
+    else {
+        // Persist up-front so concurrent `cancel(runId)` calls can find the
+        // run before any invocation has completed.
+        await deps.store.save(record);
+        args.onRunRecordCreated?.(record);
+    }
+    if (delayWakeAt !== undefined) {
+        return record;
+    }
+    const abortCtrl = registerRunAbort(id);
+    try {
+        await driveUntilPaused(record, {
+            ...driveOptionsFor(deps),
+            signal: abortCtrl.signal,
+        });
+    }
+    finally {
+        unregisterRunAbort(id);
+    }
+    // If an external cancel fired during drive, the aborted step may
+    // have surfaced as `failed` (the step threw on abort). The user's
+    // intent was cancel, so adopt the store's `cancelled` status.
+    if (abortCtrl.signal.aborted) {
+        const latest = await deps.store.get(id);
+        if (latest?.status === "cancelled") {
+            record.status = "cancelled";
+            record.completedAt = latest.completedAt ?? now();
+            record.pendingWaitpoints = [];
+            record.error = latest.error;
+        }
+    }
+    return deps.store.save(record);
+}
+function resolveDelayWakeAt(delay, now) {
+    if (delay === undefined)
+        return undefined;
+    const wakeAt = delay instanceof Date ? delay.getTime() : now + durationToMs(delay);
+    return wakeAt > now ? wakeAt : undefined;
+}
+function durationToMs(duration) {
+    if (typeof duration === "number")
+        return duration;
+    const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(duration);
+    if (!m)
+        throw new Error(`invalid duration: ${String(duration)}`);
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "ms":
+            return n;
+        case "s":
+            return n * 1_000;
+        case "m":
+            return n * 60_000;
+        case "h":
+            return n * 3_600_000;
+        case "d":
+            return n * 86_400_000;
+        case "w":
+            return n * 604_800_000;
+        default:
+            throw new Error(`invalid duration unit: ${m[2]}`);
+    }
+}
+function triggerDelayWaitpointId(runId) {
+    return `trigger-delay:${runId}`;
+}
+function cloneJournal(journal) {
+    return structuredClone(journal);
+}
+/**
+ * Build DriveOptions that carry a `triggerChild` hook bound to the
+ * same deps — so `ctx.invoke(child, ...)` recursively runs the child
+ * through the same orchestrator, store, and handler — plus a
+ * `beforeInvocation` hook that persists mid-flight progress and
+ * honors concurrent cancellations.
+ */
+function driveOptionsFor(deps) {
+    const now = deps.now ?? (() => Date.now());
+    return {
+        ...deps,
+        triggerChild: async ({ parent, waitpoint }) => {
+            const childWorkflowId = String(waitpoint.meta.childWorkflowId);
+            const childInput = waitpoint.meta.childInput;
+            const detach = waitpoint.meta.detach === true;
+            return trigger({
+                workflowId: childWorkflowId,
+                // Children inherit the parent's workflow version slot unless
+                // lockToVersion is set; for v1 we always inherit.
+                workflowVersion: parent.workflowVersion,
+                input: childInput,
+                tenantMeta: parent.tenantMeta,
+                environment: parent.environment,
+                // Inherit the parent's trigger kind for run-tree observability.
+                triggeredBy: parent.triggeredBy,
+                tags: Array.isArray(waitpoint.meta.tags) ? waitpoint.meta.tags : [],
+                // Lineage pointer: if this child parks, its terminal status
+                // cascade-resumes the parent at this specific waitpoint.
+                parent: detach
+                    ? undefined
+                    : { runId: parent.id, waitpointId: waitpoint.clientWaitpointId },
+            }, deps);
+        },
+        beforeInvocation: async (rec) => {
+            // Read-first: a concurrent `cancel()` may have flipped the
+            // stored status. If we saved first, we'd overwrite it.
+            const latest = await deps.store.get(rec.id);
+            if (latest && latest.status === "cancelled") {
+                rec.status = "cancelled";
+                rec.completedAt = latest.completedAt ?? now();
+                rec.pendingWaitpoints = [];
+                if (latest.error)
+                    rec.error = latest.error;
+                return false;
+            }
+            // Persist mid-flight progress so the dashboard sees updates and
+            // the next concurrent cancel() has an up-to-date target.
+            await deps.store.save(rec);
+            return true;
+        },
+    };
+}
+export async function resume(args, deps) {
+    const existing = await deps.store.get(args.runId);
+    if (!existing) {
+        return { ok: false, status: "not_found", message: `run ${args.runId} not found` };
+    }
+    if (existing.status !== "waiting") {
+        return {
+            ok: false,
+            status: "not_parked",
+            message: `run ${args.runId} is not parked (status: ${existing.status})`,
+        };
+    }
+    const ok = applyWaitpointInjection(existing, args.injection, deps.now);
+    if (!ok.ok) {
+        return { ok: false, status: "no_match", message: ok.message };
+    }
+    const abortCtrl = registerRunAbort(existing.id);
+    try {
+        await driveUntilPaused(existing, {
+            ...driveOptionsFor(deps),
+            signal: abortCtrl.signal,
+        });
+    }
+    finally {
+        unregisterRunAbort(existing.id);
+    }
+    if (abortCtrl.signal.aborted) {
+        const latest = await deps.store.get(existing.id);
+        if (latest?.status === "cancelled") {
+            const now = deps.now ?? (() => Date.now());
+            existing.status = "cancelled";
+            existing.completedAt = latest.completedAt ?? now();
+            existing.pendingWaitpoints = [];
+            existing.error = latest.error;
+        }
+    }
+    const saved = await deps.store.save(existing);
+    // If this resume drove the run into a terminal state and it's a
+    // child of some parent, cascade the resolution.
+    if (isTerminalStatus(saved.status)) {
+        await cascadeResumeParent(saved, deps);
+    }
+    return { ok: true, record: saved };
+}
+/**
+ * Resolve every DATETIME waitpoint whose `wakeAt` has passed, drive
+ * the run forward, and persist. Returns the saved record, or null
+ * when the run isn't in `waiting` state (already terminal / running
+ * elsewhere), or when no DATETIME waitpoints are actually due yet —
+ * both are no-ops that the caller can treat as "nothing to do."
+ *
+ * Callers (local serve loop, CF DO alarm handler) are responsible for
+ * scheduling the actual wake-up timer. This function is transport-
+ * agnostic: given `now()`, it does the resolve + drive + save.
+ */
+export async function resumeDueAlarms(args, deps) {
+    const record = await deps.store.get(args.runId);
+    if (!record)
+        return null;
+    if (record.status !== "waiting")
+        return null;
+    const now = deps.now ?? (() => Date.now());
+    const at = now();
+    const stillPending = [];
+    let resolvedAny = false;
+    for (const wp of record.pendingWaitpoints) {
+        const wakeAt = typeof wp.meta.wakeAt === "number" ? wp.meta.wakeAt : undefined;
+        if (wp.kind === "DATETIME" && wakeAt !== undefined && wakeAt <= at) {
+            record.journal.waitpointsResolved[wp.clientWaitpointId] = {
+                kind: "DATETIME",
+                resolvedAt: at,
+                source: "replay",
+            };
+            resolvedAny = true;
+        }
+        else {
+            stillPending.push(wp);
+        }
+    }
+    if (!resolvedAny)
+        return null;
+    record.pendingWaitpoints = stillPending;
+    if (record.pendingWaitpoints.length === 0)
+        record.status = "running";
+    const abortCtrl = registerRunAbort(record.id);
+    try {
+        await driveUntilPaused(record, {
+            ...driveOptionsFor(deps),
+            signal: abortCtrl.signal,
+        });
+    }
+    finally {
+        unregisterRunAbort(record.id);
+    }
+    const saved = await deps.store.save(record);
+    if (isTerminalStatus(saved.status)) {
+        await cascadeResumeParent(saved, deps);
+    }
+    return saved;
+}
+export async function cancel(args, deps) {
+    const existing = await deps.store.get(args.runId);
+    if (!existing) {
+        return { ok: false, status: "not_found", message: `run ${args.runId} not found` };
+    }
+    if (existing.status !== "waiting" && existing.status !== "running") {
+        return {
+            ok: false,
+            status: "already_terminal",
+            message: `run ${args.runId} is already terminal (status: ${existing.status})`,
+        };
+    }
+    const now = deps.now ?? (() => Date.now());
+    existing.status = "cancelled";
+    existing.completedAt = now();
+    existing.pendingWaitpoints = [];
+    if (args.reason) {
+        existing.error = {
+            category: "USER_ERROR",
+            code: "CANCELLED",
+            message: args.reason,
+        };
+    }
+    const saved = await deps.store.save(existing);
+    // Best-effort mid-step abort: if the run is in-flight in this
+    // process, fire its AbortSignal so step bodies that observe
+    // `ctx.signal` (fetches, sleeps, etc.) stop immediately. Returns
+    // `false` when no controller is registered (run is in another
+    // process, or drive has already exited) — that's fine; the
+    // status flip + between-invocation recheck cover that path.
+    signalRunAbort(existing.id, args.reason);
+    // If this cancel was on a child with a parked parent, surface the
+    // cancellation to the parent as a RUN-waitpoint error.
+    if (isTerminalStatus(saved.status)) {
+        await cascadeResumeParent(saved, deps);
+    }
+    return { ok: true, record: saved };
+}
+/**
+ * When a child run reaches a terminal state, look up its `parent`
+ * pointer and resume the parent's matching RUN waitpoint with the
+ * child's output / error. Best-effort: if the parent can't be found
+ * or is no longer parked, silently drop (the parent's own drive will
+ * observe the child's state on replay via a subsequent trigger).
+ */
+async function cascadeResumeParent(child, deps) {
+    if (!child.parent)
+        return;
+    const parent = await deps.store.get(child.parent.runId);
+    if (!parent)
+        return;
+    if (parent.status !== "waiting")
+        return;
+    const wpIdx = parent.pendingWaitpoints.findIndex((w) => w.clientWaitpointId === child.parent.waitpointId);
+    if (wpIdx < 0)
+        return;
+    const now = deps.now ?? (() => Date.now());
+    const at = now();
+    if (child.status === "completed") {
+        parent.journal.waitpointsResolved[child.parent.waitpointId] = {
+            kind: "RUN",
+            resolvedAt: at,
+            payload: child.output,
+            source: "replay",
+        };
+    }
+    else {
+        parent.journal.waitpointsResolved[child.parent.waitpointId] = {
+            kind: "RUN",
+            resolvedAt: at,
+            source: "replay",
+            error: {
+                category: child.error?.category ?? "USER_ERROR",
+                code: child.error?.code ?? "CHILD_RUN_ENDED",
+                message: child.error?.message ?? `child run ended with status ${child.status}`,
+            },
+        };
+    }
+    parent.pendingWaitpoints.splice(wpIdx, 1);
+    if (parent.pendingWaitpoints.length === 0) {
+        parent.status = "running";
+    }
+    // Re-drive the parent. This nested drive goes through the same
+    // handler / store / hooks, so the parent's own parent (if any)
+    // will also cascade-resume when appropriate.
+    const abortCtrl = registerRunAbort(parent.id);
+    try {
+        await driveUntilPaused(parent, {
+            ...driveOptionsFor(deps),
+            signal: abortCtrl.signal,
+        });
+    }
+    finally {
+        unregisterRunAbort(parent.id);
+    }
+    await deps.store.save(parent);
+    // The parent might itself have a parent — recurse.
+    if (isTerminalStatus(parent.status)) {
+        await cascadeResumeParent(parent, deps);
+    }
+}
+function isTerminalStatus(s) {
+    return (s === "completed" ||
+        s === "failed" ||
+        s === "cancelled" ||
+        s === "compensated" ||
+        s === "compensation_failed");
+}
+function defaultRunId(now) {
+    const ts = now().toString(36);
+    // Non-cryptographic; orchestrator core exposes `idGenerator` for
+    // callers that want stronger guarantees.
+    const rand = Math.floor(Math.random() * 1_000_000)
+        .toString(36)
+        .padStart(4, "0");
+    return `run_${ts}_${rand}`;
+}

package/dist/resume-run.d.ts

@@ -0,0 +1,40 @@
+import type { JournalSlice, RunRecord } from "./types.js";
+export interface BuildResumeJournalInput {
+    parent: RunRecord;
+    resumeFromStep?: string;
+    seedResults?: Record<string, unknown>;
+    now?: () => number;
+}
+export interface BuildResumeJournalResult {
+    resumeFromStep: string;
+    journal: JournalSlice;
+    metadataAppliedCount: number;
+}
+export interface BuildSeededResumeJournalInput {
+    parentRunId: string;
+    resumeFromStep: string;
+    seedResults: Record<string, unknown>;
+    metadataState?: Record<string, unknown>;
+    metadataAppliedCount?: number;
+    now?: () => number;
+}
+export declare function buildResumeJournal(input: BuildResumeJournalInput): BuildResumeJournalResult;
+export declare function buildSeededResumeJournal(input: BuildSeededResumeJournalInput): BuildResumeJournalResult;
+export type SeedResultsValidation = {
+    ok: true;
+    seedResults: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Strict structural validation for caller-supplied `seedResults`
+ * (`POST /api/runs/:id/resume`). Seeded entries are written verbatim
+ * into the new run's journal as already-completed steps, so they let
+ * the caller assert "this step ran and produced this output" — they
+ * must be gated behind an operator credential AND shape-checked:
+ * a record of bounded, control-character-free step ids to
+ * JSON-serializable values, bounded in count and total size.
+ */
+export declare function validateSeedResults(value: unknown): SeedResultsValidation;
+//# sourceMappingURL=resume-run.d.ts.map

package/dist/resume-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-run.d.ts","sourceRoot":"","sources":["../src/resume-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAA;AAE3E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;IACrB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,wBAAwB,CAwC3F;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,wBAAwB,CAgB1B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAQlC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAsCzE"}