@voyant-travel/workflows-orchestrator 0.107.10

package/dist/resume-run.js

@@ -0,0 +1,119 @@
+import { emptyJournal } from "./journal-helpers.js";
+export function buildResumeJournal(input) {
+    const resumeFromStep = input.resumeFromStep ?? findFirstFailedStep(input.parent);
+    if (!resumeFromStep) {
+        throw new Error(`run "${input.parent.id}" has no failed step; pass resumeFromStep explicitly to resume it`);
+    }
+    const journal = emptyJournal();
+    journal.metadataState = structuredClone(input.parent.journal.metadataState);
+    if (input.seedResults) {
+        return buildSeededResumeJournal({
+            parentRunId: input.parent.id,
+            resumeFromStep,
+            seedResults: input.seedResults,
+            metadataState: journal.metadataState,
+            metadataAppliedCount: input.parent.metadataAppliedCount,
+            now: input.now,
+        });
+    }
+    for (const [stepId, entry] of Object.entries(input.parent.journal.stepResults)) {
+        if (stepId === resumeFromStep)
+            break;
+        if (entry.status !== "ok") {
+            throw new Error(`step "${stepId}" completed before "${resumeFromStep}" but is not successful; cannot seed resume journal`);
+        }
+        journal.stepResults[stepId] = structuredClone(entry);
+    }
+    return {
+        resumeFromStep,
+        journal,
+        metadataAppliedCount: input.parent.metadataAppliedCount,
+    };
+}
+export function buildSeededResumeJournal(input) {
+    const journal = emptyJournal();
+    journal.metadataState = input.metadataState
+        ? structuredClone(input.metadataState)
+        : {};
+    const now = input.now ?? (() => Date.now());
+    let at = now();
+    for (const [stepId, output] of Object.entries(input.seedResults)) {
+        journal.stepResults[stepId] = seededStepEntry(output, at);
+        at += 1;
+    }
+    return {
+        resumeFromStep: input.resumeFromStep,
+        journal,
+        metadataAppliedCount: input.metadataAppliedCount ?? 0,
+    };
+}
+const SEED_RESULTS_MAX_ENTRIES = 256;
+const SEED_RESULTS_MAX_STEP_ID_LENGTH = 200;
+const SEED_RESULTS_MAX_SERIALIZED_CHARS = 1_000_000;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control chars is the point -- owner: workflows-orchestrator; existing suppression is intentional pending typed cleanup.
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+/**
+ * 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 function validateSeedResults(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, message: "seedResults must be an object of stepId → output" };
+    }
+    const entries = Object.entries(value);
+    if (entries.length > SEED_RESULTS_MAX_ENTRIES) {
+        return {
+            ok: false,
+            message: `seedResults may contain at most ${SEED_RESULTS_MAX_ENTRIES} entries`,
+        };
+    }
+    for (const [stepId, output] of entries) {
+        if (stepId.length === 0 || stepId.length > SEED_RESULTS_MAX_STEP_ID_LENGTH) {
+            return {
+                ok: false,
+                message: `seedResults step ids must be 1-${SEED_RESULTS_MAX_STEP_ID_LENGTH} characters`,
+            };
+        }
+        if (CONTROL_CHARS.test(stepId)) {
+            return { ok: false, message: "seedResults step ids must not contain control characters" };
+        }
+        let serialized;
+        try {
+            serialized = JSON.stringify(output);
+        }
+        catch {
+            return { ok: false, message: `seedResults["${stepId}"] is not JSON-serializable` };
+        }
+        if (serialized === undefined) {
+            return { ok: false, message: `seedResults["${stepId}"] is not JSON-serializable` };
+        }
+        if (serialized.length > SEED_RESULTS_MAX_SERIALIZED_CHARS) {
+            return {
+                ok: false,
+                message: `seedResults["${stepId}"] exceeds the ${SEED_RESULTS_MAX_SERIALIZED_CHARS}-character serialized limit`,
+            };
+        }
+    }
+    return { ok: true, seedResults: value };
+}
+function findFirstFailedStep(parent) {
+    for (const [stepId, entry] of Object.entries(parent.journal.stepResults)) {
+        if (entry.status === "err")
+            return stepId;
+    }
+    return undefined;
+}
+function seededStepEntry(output, at) {
+    return {
+        attempt: 1,
+        status: "ok",
+        output,
+        startedAt: at,
+        finishedAt: at,
+    };
+}

package/dist/schedule.d.ts

@@ -0,0 +1,51 @@
+import type { Duration, EnvironmentName, ScheduleDeclaration } from "@voyant-travel/workflows";
+import type { ManifestSchedule, WorkflowManifest } from "@voyant-travel/workflows/protocol";
+export type SchedulableDeclaration = ScheduleDeclaration | ManifestSchedule;
+export interface ScheduleSource {
+    id?: string;
+    workflowId: string;
+    decl: SchedulableDeclaration;
+}
+export interface SchedulerDeps {
+    sources: readonly ScheduleSource[];
+    onFire: (args: {
+        workflowId: string;
+        input: unknown;
+        scheduleId: string;
+        scheduleName?: string;
+        fireAt: number;
+    }) => Promise<void>;
+    now?: () => number;
+    environment?: EnvironmentName;
+    tickMs?: number;
+    setInterval?: typeof setInterval;
+    clearInterval?: typeof clearInterval;
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+}
+export interface SchedulerHandle {
+    start: () => void;
+    stop: () => void;
+    tick: () => Promise<void>;
+    nextFirings: () => {
+        workflowId: string;
+        scheduleId: string;
+        name?: string;
+        nextAt: number;
+        done: boolean;
+    }[];
+    sourceCount: () => number;
+}
+export declare function manifestScheduleSources(manifest: WorkflowManifest): ScheduleSource[];
+export declare function createScheduler(deps: SchedulerDeps): SchedulerHandle;
+export declare function computeNextFire(decl: SchedulableDeclaration, fromMs: number): number;
+export interface CronSpec {
+    minute: number[];
+    hour: number[];
+    day: number[];
+    month: number[];
+    dow: number[];
+}
+export declare function parseCron(expr: string): CronSpec;
+export declare function nextCronFire(spec: CronSpec, fromMs: number): number;
+export declare function toMs(duration: Duration | string | number): number;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAA;AAE3F,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG,gBAAgB,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,sBAAsB,CAAA;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;IAClC,MAAM,EAAE,CAAC,IAAI,EAAE;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,OAAO,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,MAAM,EAAE,MAAM,CAAA;KACf,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,OAAO,WAAW,CAAA;IAChC,aAAa,CAAC,EAAE,OAAO,aAAa,CAAA;IACpC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,WAAW,EAAE,MAAM;QACjB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,OAAO,CAAA;KACd,EAAE,CAAA;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;CAC1B;AA0BD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAYpF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAmHpE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASpF;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,GAAG,EAAE,MAAM,EAAE,CAAA;CACd;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAYhD;AA8BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBnE;AAED,wBAAgB,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAqBjE"}

package/dist/schedule.js

@@ -0,0 +1,243 @@
+function unrefTimer(timer) {
+    if (typeof timer === "object" &&
+        timer !== null &&
+        "unref" in timer &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+export function manifestScheduleSources(manifest) {
+    const sources = [];
+    for (const workflow of manifest.workflows) {
+        workflow.schedules.forEach((decl, index) => {
+            sources.push({
+                id: `${manifest.versionId}:${workflow.id}:${decl.name ?? index}`,
+                workflowId: workflow.id,
+                decl,
+            });
+        });
+    }
+    return sources;
+}
+export function createScheduler(deps) {
+    const now = deps.now ?? (() => Date.now());
+    const tickMs = deps.tickMs ?? 1_000;
+    const setInt = deps.setInterval ?? setInterval;
+    const clearInt = deps.clearInterval ?? clearInterval;
+    const env = deps.environment ?? "development";
+    const log = deps.logger ?? (() => { });
+    const states = [];
+    for (const [index, source] of deps.sources.entries()) {
+        if (source.decl.enabled === false)
+            continue;
+        if (source.decl.environments && !source.decl.environments.includes(env))
+            continue;
+        let firstAt;
+        try {
+            firstAt = computeNextFire(source.decl, now());
+        }
+        catch (err) {
+            log("warn", `scheduler: skipping source for workflow "${source.workflowId}": ${String(err)}`);
+            continue;
+        }
+        states.push({
+            source,
+            scheduleId: source.id ?? `${source.workflowId}:${source.decl.name ?? index}`,
+            nextAt: firstAt,
+            done: false,
+            inFlight: false,
+            queued: [],
+        });
+    }
+    let timer;
+    const advanceAfterFire = (state, firedAt) => {
+        if ("at" in state.source.decl) {
+            state.done = true;
+            return;
+        }
+        try {
+            state.nextAt = computeNextFire(state.source.decl, firedAt);
+        }
+        catch (err) {
+            log("error", `scheduler: cannot compute next fire for "${state.source.workflowId}": ${String(err)}`);
+            state.done = true;
+        }
+    };
+    const fire = async (state, fireAt) => {
+        try {
+            const input = await resolveInput(state.source.decl.input);
+            await deps.onFire({
+                workflowId: state.source.workflowId,
+                input,
+                scheduleId: state.scheduleId,
+                scheduleName: state.source.decl.name,
+                fireAt,
+            });
+        }
+        catch (err) {
+            log("error", `scheduler: onFire threw for "${state.source.workflowId}": ${String(err)}`);
+        }
+        finally {
+            const next = state.queued.shift();
+            if (next) {
+                void fire(state, next.fireAt);
+            }
+            else {
+                state.inFlight = false;
+            }
+        }
+    };
+    const doTick = async () => {
+        const t = now();
+        const ready = states.filter((state) => !state.done && state.nextAt <= t);
+        for (const state of ready) {
+            const overlap = state.source.decl.overlap ?? "skip";
+            if (state.inFlight && overlap === "skip")
+                continue;
+            const fireAt = state.nextAt;
+            if (state.inFlight && overlap === "queue") {
+                state.queued.push({ fireAt });
+                advanceAfterFire(state, t);
+                continue;
+            }
+            state.inFlight = true;
+            const firePromise = fire(state, fireAt);
+            advanceAfterFire(state, t);
+            if (overlap !== "allow")
+                await firePromise;
+        }
+    };
+    return {
+        start() {
+            if (timer)
+                return;
+            timer = setInt(() => {
+                doTick().catch(() => { });
+            }, tickMs);
+            unrefTimer(timer);
+        },
+        stop() {
+            if (!timer)
+                return;
+            clearInt(timer);
+            timer = undefined;
+        },
+        tick: doTick,
+        nextFirings() {
+            return states.map((state) => ({
+                workflowId: state.source.workflowId,
+                scheduleId: state.scheduleId,
+                name: state.source.decl.name,
+                nextAt: state.nextAt,
+                done: state.done,
+            }));
+        },
+        sourceCount() {
+            return states.length;
+        },
+    };
+}
+export function computeNextFire(decl, fromMs) {
+    if ("cron" in decl && decl.cron !== undefined)
+        return nextCronFire(parseCron(decl.cron), fromMs);
+    if ("every" in decl && decl.every !== undefined)
+        return fromMs + toMs(decl.every);
+    if ("at" in decl && decl.at !== undefined) {
+        const at = typeof decl.at === "string" ? Date.parse(decl.at) : decl.at.getTime();
+        if (!Number.isFinite(at))
+            throw new Error(`invalid "at" value: ${String(decl.at)}`);
+        return at < fromMs ? Number.POSITIVE_INFINITY : at;
+    }
+    throw new Error(`schedule declaration missing one of cron/every/at`);
+}
+export function parseCron(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`invalid cron "${expr}" - expected 5 fields (minute hour day month dow)`);
+    }
+    return {
+        minute: parseField(parts[0], 0, 59, "minute"),
+        hour: parseField(parts[1], 0, 23, "hour"),
+        day: parseField(parts[2], 1, 31, "day"),
+        month: parseField(parts[3], 1, 12, "month"),
+        dow: parseField(parts[4], 0, 6, "dow"),
+    };
+}
+function parseField(f, min, max, label) {
+    const out = new Set();
+    for (const part of f.split(",")) {
+        const stepMatch = /^(.+)\/(\d+)$/.exec(part);
+        const body = stepMatch ? stepMatch[1] : part;
+        const step = stepMatch ? Number(stepMatch[2]) : 1;
+        if (!(step >= 1))
+            throw new Error(`cron ${label} step must be >=1 in "${f}"`);
+        let lo;
+        let hi;
+        if (body === "*") {
+            lo = min;
+            hi = max;
+        }
+        else if (body.includes("-")) {
+            const [a, b] = body.split("-");
+            lo = Number(a);
+            hi = Number(b);
+        }
+        else {
+            lo = Number(body);
+            hi = lo;
+        }
+        if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo < min || hi > max || lo > hi) {
+            throw new Error(`cron ${label} out of range [${min}..${max}] in "${f}"`);
+        }
+        for (let i = lo; i <= hi; i += step)
+            out.add(i);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+export function nextCronFire(spec, fromMs) {
+    const date = new Date(fromMs);
+    date.setUTCSeconds(0, 0);
+    date.setUTCMinutes(date.getUTCMinutes() + 1);
+    const maxIterations = 60 * 24 * 366 * 5;
+    for (let i = 0; i < maxIterations; i++) {
+        if (spec.minute.includes(date.getUTCMinutes()) &&
+            spec.hour.includes(date.getUTCHours()) &&
+            spec.day.includes(date.getUTCDate()) &&
+            spec.month.includes(date.getUTCMonth() + 1) &&
+            spec.dow.includes(date.getUTCDay())) {
+            return date.getTime();
+        }
+        date.setUTCMinutes(date.getUTCMinutes() + 1);
+    }
+    throw new Error("cron search exceeded 5 years without finding a match");
+}
+export function toMs(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 "${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 "${duration}"`);
+    }
+}
+async function resolveInput(input) {
+    if (typeof input === "function") {
+        return await input();
+    }
+    return input;
+}

package/dist/testing/driver-compliance.d.ts

@@ -0,0 +1,58 @@
+import type { DriverFactory, DriverFactoryDeps, ServiceResolver } from "@voyant-travel/workflows/driver";
+import type { WorkflowManifest } from "@voyant-travel/workflows/protocol";
+/**
+ * Tiny in-memory ServiceResolver builder for compliance tests. Lets a test
+ * register named services then assert workflow bodies can resolve them via
+ * `ctx.services.resolve(...)`.
+ */
+export declare function makeServiceResolver(entries?: Record<string, unknown>): ServiceResolver;
+/**
+ * Build a `DriverFactoryDeps` value suitable for compliance tests. Captures
+ * log lines so individual tests can assert on them when needed. Pass
+ * `services` to register specific entries; defaults to an empty resolver.
+ */
+export declare function testFactoryDeps(services?: ServiceResolver): DriverFactoryDeps & {
+    logs: Array<[string, string, object?]>;
+};
+/**
+ * Build a minimal manifest for tests. The shape matches `WorkflowManifest`;
+ * filter-related fields stay empty until the event-router (PR2) lands.
+ */
+export declare function buildTestManifest(versionId?: string): WorkflowManifest;
+/**
+ * Opt-in capability flags for drivers that don't share a process with
+ * step bodies. Default to `true` because in-process drivers (InMemory,
+ * Mode 2) satisfy every contract. Out-of-process drivers (Mode 1 / CF
+ * edge — orchestrator and tenant live in separate Worker isolates) opt
+ * out of in-process-only assertions like `ctx.services` threading.
+ */
+export interface DriverComplianceCapabilities {
+    /**
+     * When true, the framework's `ModuleContainer` is plumbed to step
+     * bodies via `ctx.services`. False for Mode 1, where the orchestrator
+     * and tenant are separate Workers and a per-tenant container would
+     * have to ship across a serialization boundary.
+     */
+    servicesThreading?: boolean;
+    /**
+     * When true, `admin.listRuns(...)` returns runs the driver knows about.
+     * False for self-host Mode 1, which has no native cross-run query
+     * layer (per architecture doc §8.3) — `listRuns` exists but returns
+     * an empty page; voyant-cloud provides an index in its repo.
+     */
+    crossRunQueries?: boolean;
+    /**
+     * When true, the driver under test runs an in-process DATETIME wakeup
+     * loop/timer during compliance tests. False for drivers whose compliance
+     * harness intentionally disables or fakes the time wheel.
+     */
+    autoDatetimeWakeups?: boolean;
+    /**
+     * When true, workflow-level `WorkflowConfig.concurrency` is enforced
+     * for in-process workflow definitions. False for Mode 1 / Cloudflare
+     * until it grows a cross-run coordination DO.
+     */
+    workflowConcurrency?: boolean;
+}
+export declare function runDriverComplianceSuite(name: string, makeFactory: () => DriverFactory, capabilities?: DriverComplianceCapabilities): void;
+//# sourceMappingURL=driver-compliance.d.ts.map

package/dist/testing/driver-compliance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-compliance.d.ts","sourceRoot":"","sources":["../../src/testing/driver-compliance.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAA;AAKzE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,eAAe,CAa1F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,GAAE,eAAuC,GAChD,iBAAiB,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAAE,CAOhE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,SAAe,GAAG,gBAAgB,CAc5E;AA4BD;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAID,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,aAAa,EAChC,YAAY,GAAE,4BAAiC,GAC9C,IAAI,CAqnBN"}