@crewhaus/durable-execution 0.3.1 → 0.4.0

package/dist/idempotency-store.d.ts

@@ -0,0 +1,22 @@
+import { type IdempotencyKey, type IdempotencyRecord, type IdempotencyStore } from "./index";
+/**
+ * A filesystem-backed idempotency store: one `<key>.json` per record under
+ * `dir`. `get` fails safe (a missing/corrupt file reads as "no record", so a
+ * torn write re-runs rather than throwing); `put` is a single atomic-enough
+ * `writeFileSync`.
+ */
+export declare class FileIdempotencyStore implements IdempotencyStore {
+    private readonly dir;
+    constructor(dir: string);
+    private pathFor;
+    get(key: IdempotencyKey): Promise<IdempotencyRecord | undefined>;
+    put(record: IdempotencyRecord): Promise<void>;
+}
+/**
+ * Build the idempotency store the bundle's durable-execution wrapping uses,
+ * from `env.CREWHAUS_IDEMPOTENCY_STORE`. Records are namespaced by `spec` so
+ * two shapes sharing a working directory never collide. Throws on an
+ * unrecognised value so a typo fails loudly at boot rather than silently
+ * degrading exactly-once to in-memory.
+ */
+export declare function createIdempotencyStore(spec: string, env?: Record<string, string | undefined>): IdempotencyStore;

package/dist/idempotency-store.js

@@ -0,0 +1,84 @@
+/**
+ * Loop contract 0.4 (Batch F, temporal contract / G61 exactly-once half) —
+ * a DURABLE {@link IdempotencyStore} plus the env-driven factory the emitted
+ * graph / workflow bundles select their store with.
+ *
+ * `withIdempotency` (see `./index`) dedups a node/step by (runId, name,
+ * attempt), but its default {@link InMemoryIdempotencyStore} evaporates when
+ * the process exits — so it only guards against in-process double-invocation.
+ * For crash-resume exactly-once the record has to OUTLIVE the process: a
+ * restart re-executing the same run must find the prior attempt's cached
+ * result. {@link FileIdempotencyStore} persists one JSON file per key under a
+ * spec-scoped directory so a `bun agent.ts` restart (same runId) skips
+ * already-completed work instead of re-running its side effects.
+ *
+ * This is best-effort exactly-once, not transactional: a crash in the window
+ * between a node's external side effect and the store write still re-runs on
+ * resume (at-least-once). The durable record strictly TIGHTENS the guarantee
+ * over the in-memory default; it cannot make a non-transactional external
+ * effect perfectly exactly-once.
+ *
+ * Selection mirrors the channel daemon's `CREWHAUS_DEDUP_STORE` convention:
+ *   - `memory` (default) — in-memory, no cross-restart resume.
+ *   - `file:<dir>` / `file` — durable JSON records under
+ *     `<dir>/<spec>/` (default dir `.crewhaus/idempotency`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { InMemoryIdempotencyStore, } from "./index";
+function safeSegment(spec) {
+    const cleaned = spec.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return cleaned.length > 0 ? cleaned : "spec";
+}
+/**
+ * A filesystem-backed idempotency store: one `<key>.json` per record under
+ * `dir`. `get` fails safe (a missing/corrupt file reads as "no record", so a
+ * torn write re-runs rather than throwing); `put` is a single atomic-enough
+ * `writeFileSync`.
+ */
+export class FileIdempotencyStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        mkdirSync(dir, { recursive: true });
+    }
+    pathFor(key) {
+        return join(this.dir, `${key}.json`);
+    }
+    async get(key) {
+        const p = this.pathFor(key);
+        if (!existsSync(p))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(p, "utf-8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async put(record) {
+        writeFileSync(this.pathFor(record.key), JSON.stringify(record));
+    }
+}
+const DEFAULT_IDEMPOTENCY_DIR = join(".crewhaus", "idempotency");
+/**
+ * Build the idempotency store the bundle's durable-execution wrapping uses,
+ * from `env.CREWHAUS_IDEMPOTENCY_STORE`. Records are namespaced by `spec` so
+ * two shapes sharing a working directory never collide. Throws on an
+ * unrecognised value so a typo fails loudly at boot rather than silently
+ * degrading exactly-once to in-memory.
+ */
+export function createIdempotencyStore(spec, env = process.env) {
+    const raw = env["CREWHAUS_IDEMPOTENCY_STORE"] ?? "memory";
+    if (raw === "memory")
+        return new InMemoryIdempotencyStore();
+    if (raw === "file") {
+        return new FileIdempotencyStore(join(DEFAULT_IDEMPOTENCY_DIR, safeSegment(spec)));
+    }
+    if (raw.startsWith("file:")) {
+        const base = raw.slice("file:".length);
+        const dir = base.length > 0 ? base : DEFAULT_IDEMPOTENCY_DIR;
+        return new FileIdempotencyStore(join(dir, safeSegment(spec)));
+    }
+    throw new Error(`[durable-execution] unknown CREWHAUS_IDEMPOTENCY_STORE "${raw}" — use "memory" (default) or "file:<dir>".`);
+}

package/dist/index.d.ts

@@ -65,4 +65,21 @@ export declare function resumeFrom(store: CheckpointStore, graphRunId: GraphRunI
     checkpointId: CheckpointId;
     nextNode: string;
 } | undefined>;
+/**
+ * Loop contract 0.4 (Batch F, temporal contract / G61) — the linear-resume
+ * counterpart to {@link withIdempotency} for shapes that run steps
+ * sequentially in one process (the workflow target) rather than through the
+ * graph engine's `NodeContext`. `runId` is a plain string (the workflow's
+ * `CREWHAUS_RUN_ID` or a fresh id), not a branded `GraphRunId`.
+ *
+ * The first call for `(runId, name, attempt)` runs `fn` and records its
+ * result; a restart of the SAME `runId` against a durable store finds the
+ * record and skips straight to the cached value — so a crashed multi-step
+ * workflow resumes at the first not-yet-completed step instead of re-running
+ * the ones that already finished (and their side effects). With the default
+ * in-memory store it is transparent (each step runs once, keys are unique).
+ */
+export declare function runOnce<T>(store: IdempotencyStore, runId: string, name: string, fn: () => Promise<T>, attempt?: number): Promise<T>;
 export { InMemoryIdempotencyStore };
+export { type ArmedSchedule, type ArmScheduleHandlers, type WakeSchedule, armSchedule, nextCronMatch, nextWakeDelayMs, } from "./schedule";
+export { FileIdempotencyStore, createIdempotencyStore } from "./idempotency-store";

package/dist/index.js

@@ -84,4 +84,40 @@ export async function resumeFrom(store, graphRunId) {
         return undefined;
     return { checkpointId: head.id, nextNode: head.nodeName };
 }
+/**
+ * Loop contract 0.4 (Batch F, temporal contract / G61) — the linear-resume
+ * counterpart to {@link withIdempotency} for shapes that run steps
+ * sequentially in one process (the workflow target) rather than through the
+ * graph engine's `NodeContext`. `runId` is a plain string (the workflow's
+ * `CREWHAUS_RUN_ID` or a fresh id), not a branded `GraphRunId`.
+ *
+ * The first call for `(runId, name, attempt)` runs `fn` and records its
+ * result; a restart of the SAME `runId` against a durable store finds the
+ * record and skips straight to the cached value — so a crashed multi-step
+ * workflow resumes at the first not-yet-completed step instead of re-running
+ * the ones that already finished (and their side effects). With the default
+ * in-memory store it is transparent (each step runs once, keys are unique).
+ */
+export async function runOnce(store, runId, name, fn, attempt = 0) {
+    const key = idempotencyKey(runId, name, attempt);
+    const cached = await store.get(key);
+    if (cached !== undefined)
+        return cached.result;
+    const result = await fn();
+    await store.put({
+        key,
+        graphRunId: runId,
+        nodeName: name,
+        attempt,
+        result,
+        completedAt: new Date().toISOString(),
+    });
+    return result;
+}
 export { InMemoryIdempotencyStore };
+// Loop contract 0.4 (Batch F, temporal contract) — the schedule wake-loop
+// runtime the channel/batch daemons arm their `schedule:` block with, and the
+// durable idempotency store + env factory the graph/workflow bundles select
+// for crash-resume exactly-once.
+export { armSchedule, nextCronMatch, nextWakeDelayMs, } from "./schedule";
+export { FileIdempotencyStore, createIdempotencyStore } from "./idempotency-store";

package/dist/schedule.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Loop contract 0.4 (Batch F, temporal contract / G84 schedule half) — the
+ * runtime the daemon-able bundles (channel / batch) arm their `schedule:`
+ * wake loop with. The compiler lowers `schedule:` into an `IrSchedule`
+ * (cron OR interval, durations already normalized to ms); the emitters embed
+ * the numeric-literal {@link WakeSchedule} and hand `armSchedule` the wake
+ * callback, so all of the cron arithmetic lives HERE — one tested place —
+ * instead of duplicated across two emitted daemon templates.
+ *
+ * `WakeSchedule` is the IR's `IrSchedule` MINUS `instructions` (the synthetic
+ * wake prompt is the emitter's concern, threaded into `onWake`): the schedule
+ * runtime only decides *when* to fire, never *what* to run. That keeps this
+ * package free of any `@crewhaus/ir` dependency.
+ *
+ * The cron parser is a pragmatic 5-/6-field matcher: `*`, `?`, numeric,
+ * lists (`a,b`), ranges (`a-b`), and steps (`* /n`, `a/n`, `a-b/n`), plus
+ * month/weekday names, evaluated in an IANA timezone (default UTC). The
+ * Quartz-style extensions (`L`, `W`, `#`) are not interpreted — a field
+ * containing one is treated as a wildcard so the daemon never crashes on a
+ * cron it cannot fully model; the spec's own `schedule.cron` regex is the
+ * syntactic gate.
+ */
+/** IR's `IrSchedule` without `instructions` — the "when", never the "what". */
+export type WakeSchedule = {
+    readonly kind: "cron";
+    /** A 5- or 6-field cron expression (6-field is second-first, Quartz). */
+    readonly cron: string;
+    /** IANA tz the cron evaluates in; absent → UTC. */
+    readonly timezone?: string;
+    /** Random +/- delay per wake, in ms. Absent → fire exactly on time. */
+    readonly jitterMs?: number;
+} | {
+    readonly kind: "interval";
+    readonly everyMs: number;
+    readonly jitterMs?: number;
+};
+/**
+ * The next `Date` strictly after `from` at which `cron` fires, evaluated in
+ * `timezone` (UTC when absent). Minute-granularity search; a 6-field cron's
+ * leading seconds field picks the smallest matching second inside the
+ * matched minute. Standard day-of-month / day-of-week rule: when BOTH are
+ * restricted the match is their UNION; when one is `*` the other decides.
+ */
+export declare function nextCronMatch(cron: string, from: Date, timezone?: string): Date;
+/**
+ * Milliseconds to wait from `fromMs` before the next wake. Jitter (when
+ * declared) adds a uniform `+/- jitterMs` offset drawn from `rand`
+ * (`Math.random` by default); the result never goes negative.
+ */
+export declare function nextWakeDelayMs(schedule: WakeSchedule, fromMs: number, rand?: () => number): number;
+export interface ArmScheduleHandlers {
+    /** Runs on every wake; awaited so overlapping ticks can't stack. */
+    readonly onWake: () => void | Promise<void>;
+    /** A thrown `onWake` lands here instead of crashing the scheduler. */
+    readonly onError?: (err: unknown) => void;
+    readonly now?: () => number;
+    readonly rand?: () => number;
+    readonly setTimer?: (fn: () => void, ms: number) => unknown;
+    readonly clearTimer?: (handle: unknown) => void;
+}
+export interface ArmedSchedule {
+    /** Stop the loop and clear any pending timer. Idempotent. */
+    cancel(): void;
+}
+/**
+ * Arm a self-rescheduling wake loop for `schedule`. Each tick computes its
+ * OWN next delay (so cron drift and per-wake jitter stay correct across a
+ * long-lived daemon) and re-arms only AFTER `onWake` resolves, so a slow tick
+ * can never overlap itself. All timing seams (`now`/`rand`/`setTimer`) are
+ * injectable for deterministic tests. Returns a cancel handle the daemon's
+ * shutdown path calls.
+ */
+export declare function armSchedule(schedule: WakeSchedule, handlers: ArmScheduleHandlers): ArmedSchedule;

package/dist/schedule.js

@@ -0,0 +1,238 @@
+/**
+ * Loop contract 0.4 (Batch F, temporal contract / G84 schedule half) — the
+ * runtime the daemon-able bundles (channel / batch) arm their `schedule:`
+ * wake loop with. The compiler lowers `schedule:` into an `IrSchedule`
+ * (cron OR interval, durations already normalized to ms); the emitters embed
+ * the numeric-literal {@link WakeSchedule} and hand `armSchedule` the wake
+ * callback, so all of the cron arithmetic lives HERE — one tested place —
+ * instead of duplicated across two emitted daemon templates.
+ *
+ * `WakeSchedule` is the IR's `IrSchedule` MINUS `instructions` (the synthetic
+ * wake prompt is the emitter's concern, threaded into `onWake`): the schedule
+ * runtime only decides *when* to fire, never *what* to run. That keeps this
+ * package free of any `@crewhaus/ir` dependency.
+ *
+ * The cron parser is a pragmatic 5-/6-field matcher: `*`, `?`, numeric,
+ * lists (`a,b`), ranges (`a-b`), and steps (`* /n`, `a/n`, `a-b/n`), plus
+ * month/weekday names, evaluated in an IANA timezone (default UTC). The
+ * Quartz-style extensions (`L`, `W`, `#`) are not interpreted — a field
+ * containing one is treated as a wildcard so the daemon never crashes on a
+ * cron it cannot fully model; the spec's own `schedule.cron` regex is the
+ * syntactic gate.
+ */
+const MONTH_NAMES = {
+    jan: 1,
+    feb: 2,
+    mar: 3,
+    apr: 4,
+    may: 5,
+    jun: 6,
+    jul: 7,
+    aug: 8,
+    sep: 9,
+    oct: 10,
+    nov: 11,
+    dec: 12,
+};
+const DOW_NAMES = {
+    sun: 0,
+    mon: 1,
+    tue: 2,
+    wed: 3,
+    thu: 4,
+    fri: 5,
+    sat: 6,
+};
+function fieldMatches(field, n) {
+    return field === "*" || field.has(n);
+}
+/**
+ * Parse one cron field into a {@link FieldMatch}. Unrecognised tokens (the
+ * `L`/`W`/`#` Quartz extensions) collapse the whole field to `"*"` — a
+ * fail-open the daemon can survive rather than a throw that would kill the
+ * scheduler.
+ */
+function parseField(field, min, max, names) {
+    const trimmed = field.trim();
+    if (trimmed === "*" || trimmed === "?")
+        return "*";
+    if (/[LW#]/i.test(trimmed))
+        return "*";
+    const out = new Set();
+    const tok = (t) => {
+        const named = names?.[t.toLowerCase()];
+        return named !== undefined ? named : Number.parseInt(t, 10);
+    };
+    for (const part of trimmed.split(",")) {
+        const slash = part.indexOf("/");
+        const rangeText = slash >= 0 ? part.slice(0, slash) : part;
+        const step = slash >= 0 ? Math.max(1, Number.parseInt(part.slice(slash + 1), 10) || 1) : 1;
+        let lo;
+        let hi;
+        if (rangeText === "*" || rangeText === "?" || rangeText === "") {
+            lo = min;
+            hi = max;
+        }
+        else if (rangeText.includes("-")) {
+            const [a, b] = rangeText.split("-");
+            lo = tok(a ?? "");
+            hi = tok(b ?? "");
+        }
+        else {
+            lo = tok(rangeText);
+            // `a/n` (a bare start with a step) means "a, a+n, a+2n, … up to max".
+            hi = slash >= 0 ? max : lo;
+        }
+        if (Number.isNaN(lo) || Number.isNaN(hi))
+            return "*";
+        for (let v = lo; v <= hi; v += step) {
+            if (v >= min && v <= max)
+                out.add(v);
+        }
+    }
+    return out.size === 0 ? "*" : out;
+}
+const WEEKDAY_INDEX = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+};
+/** Wall-clock fields of `date` in `timezone` (UTC when absent). */
+function wallClock(date, timezone) {
+    if (timezone === undefined) {
+        return {
+            minute: date.getUTCMinutes(),
+            hour: date.getUTCHours(),
+            dom: date.getUTCDate(),
+            month: date.getUTCMonth() + 1,
+            dow: date.getUTCDay(),
+        };
+    }
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour12: false,
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        weekday: "short",
+    }).formatToParts(date);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    const hour24 = Number.parseInt(get("hour"), 10);
+    return {
+        minute: Number.parseInt(get("minute"), 10),
+        // Intl with hour12:false yields "24" for midnight in some ICU builds.
+        hour: hour24 === 24 ? 0 : hour24,
+        dom: Number.parseInt(get("day"), 10),
+        month: Number.parseInt(get("month"), 10),
+        dow: WEEKDAY_INDEX[get("weekday")] ?? 0,
+    };
+}
+const MINUTE_MS = 60_000;
+const CRON_SEARCH_MINUTES = 366 * 24 * 60; // give up after a year without a match
+/**
+ * The next `Date` strictly after `from` at which `cron` fires, evaluated in
+ * `timezone` (UTC when absent). Minute-granularity search; a 6-field cron's
+ * leading seconds field picks the smallest matching second inside the
+ * matched minute. Standard day-of-month / day-of-week rule: when BOTH are
+ * restricted the match is their UNION; when one is `*` the other decides.
+ */
+export function nextCronMatch(cron, from, timezone) {
+    const fields = cron.trim().split(/\s+/);
+    const [secR, minR, hourR, domR, monR, dowR] = fields.length >= 6 ? fields : ["0", ...fields];
+    const secSet = parseField(secR ?? "0", 0, 59);
+    const minSet = parseField(minR ?? "*", 0, 59);
+    const hourSet = parseField(hourR ?? "*", 0, 23);
+    const domSet = parseField(domR ?? "*", 1, 31);
+    const monSet = parseField(monR ?? "*", 1, 12, MONTH_NAMES);
+    const dowRaw = parseField(dowR ?? "*", 0, 7, DOW_NAMES);
+    // Normalize Sunday: cron accepts both 0 and 7.
+    const dowSet = dowRaw === "*" ? "*" : new Set([...dowRaw].map((d) => (d === 7 ? 0 : d)));
+    const domRestricted = domSet !== "*";
+    const dowRestricted = dowSet !== "*";
+    // Search minute-by-minute from the CURRENT minute (so a 6-field cron whose
+    // matching second is still ahead inside `from`'s own minute is found), and
+    // accept only a whole timestamp STRICTLY after `from`.
+    const fromMs = from.getTime();
+    let t = new Date(Math.floor(fromMs / MINUTE_MS) * MINUTE_MS);
+    for (let i = 0; i <= CRON_SEARCH_MINUTES; i++) {
+        const wc = wallClock(t, timezone);
+        const domOk = fieldMatches(domSet, wc.dom);
+        const dowOk = fieldMatches(dowSet, wc.dow);
+        const dayOk = domRestricted && dowRestricted ? domOk || dowOk : domRestricted ? domOk : dowOk;
+        if (dayOk &&
+            fieldMatches(minSet, wc.minute) &&
+            fieldMatches(hourSet, wc.hour) &&
+            fieldMatches(monSet, wc.month)) {
+            for (let s = 0; s <= 59; s++) {
+                if (!fieldMatches(secSet, s))
+                    continue;
+                const candidate = t.getTime() + s * 1000;
+                if (candidate > fromMs)
+                    return new Date(candidate);
+            }
+        }
+        t = new Date(t.getTime() + MINUTE_MS);
+    }
+    throw new Error(`cron "${cron}" produced no wake within a year`);
+}
+/**
+ * Milliseconds to wait from `fromMs` before the next wake. Jitter (when
+ * declared) adds a uniform `+/- jitterMs` offset drawn from `rand`
+ * (`Math.random` by default); the result never goes negative.
+ */
+export function nextWakeDelayMs(schedule, fromMs, rand = Math.random) {
+    const base = schedule.kind === "interval"
+        ? schedule.everyMs
+        : nextCronMatch(schedule.cron, new Date(fromMs), schedule.timezone).getTime() - fromMs;
+    const jitter = schedule.jitterMs !== undefined && schedule.jitterMs > 0
+        ? (rand() * 2 - 1) * schedule.jitterMs
+        : 0;
+    return Math.max(0, Math.round(base + jitter));
+}
+/**
+ * Arm a self-rescheduling wake loop for `schedule`. Each tick computes its
+ * OWN next delay (so cron drift and per-wake jitter stay correct across a
+ * long-lived daemon) and re-arms only AFTER `onWake` resolves, so a slow tick
+ * can never overlap itself. All timing seams (`now`/`rand`/`setTimer`) are
+ * injectable for deterministic tests. Returns a cancel handle the daemon's
+ * shutdown path calls.
+ */
+export function armSchedule(schedule, handlers) {
+    const now = handlers.now ?? Date.now;
+    const rand = handlers.rand ?? Math.random;
+    const setTimer = handlers.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = handlers.clearTimer ?? ((h) => clearTimeout(h));
+    let cancelled = false;
+    let handle;
+    const scheduleNext = () => {
+        if (cancelled)
+            return;
+        const delay = nextWakeDelayMs(schedule, now(), rand);
+        handle = setTimer(() => {
+            if (cancelled)
+                return;
+            void (async () => {
+                try {
+                    await handlers.onWake();
+                }
+                catch (err) {
+                    handlers.onError?.(err);
+                }
+                scheduleNext();
+            })();
+        }, delay);
+    };
+    scheduleNext();
+    return {
+        cancel() {
+            cancelled = true;
+            if (handle !== undefined)
+                clearTimer(handle);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/durable-execution",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Exactly-once node execution wrapper over graph-engine — idempotency keys + crash-replay",
   "main": "dist/index.js",
@@ -15,8 +15,8 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/checkpoint-store": "0.3.1",
-    "@crewhaus/errors": "0.3.1"
+    "@crewhaus/checkpoint-store": "0.4.0",
+    "@crewhaus/errors": "0.4.0"
   },
   "license": "Apache-2.0",
   "author": {