@blokjs/runner 0.2.2 → 0.4.0

package/dist/scheduling/DeferredDispatchSignal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tier 2 #5 + #7 — thrown by `TriggerBase.run()` when a workflow's
+ * scheduling gates (debounce / delay) defer the run to a future
+ * dispatch. Tier 2 #6 follow-up extends this to cover `onLimit:"queue"`
+ * (concurrency-gate-deferred runs); same transport translation.
+ *
+ * NOT a true error — a control-flow exception. Trigger transports
+ * catch it and translate it into the appropriate transport-level
+ * response:
+ *
+ * - HTTP trigger → `202 Accepted` with `Location: /__blok/runs/:id`
+ *   header and structured JSON body.
+ * - Worker trigger → ACK without retry (the deferred coordinator owns
+ *   the eventual dispatch).
+ *
+ * Carries the run-detail summary the transport needs to populate the
+ * response.
+ */
+export interface DeferredDispatchInfo {
+    /** Run id allocated by the tracer when the run was created. */
+    runId: string;
+    /** Workflow name. */
+    workflowName: string;
+    /**
+     * Resolved status the run was placed in:
+     * - `"delayed"` — Tier 2 #5 (`trigger.delay`).
+     * - `"debounced"` — Tier 2 #7 (`trigger.debounce`).
+     * - `"queued"` — Tier 2 #6 follow-up (`trigger.onLimit:"queue"`).
+     */
+    status: "delayed" | "debounced" | "queued";
+    /** ms since epoch when the run is scheduled to dispatch. */
+    scheduledAt: number;
+    /** ms since epoch when the run will expire if not dispatched. Undefined when no TTL. */
+    expiresAt?: number;
+    /** True when the run was placed in `"debounced"` status (Tier 2 #7). */
+    debounced: boolean;
+    /** Pings absorbed by the run so far (always 1+). */
+    pingCount: number;
+    /**
+     * For leading-mode debounce, the runId of the sibling that fired
+     * immediately. Lets transports return `Location: /__blok/runs/<sibling>`
+     * so the caller can poll the actually-running run.
+     */
+    intoRunId?: string;
+}
+export declare class DeferredDispatchSignal extends Error {
+    readonly info: DeferredDispatchInfo;
+    constructor(info: DeferredDispatchInfo);
+}
+export declare function isDeferredDispatchSignal(err: unknown): err is DeferredDispatchSignal;

package/dist/scheduling/DeferredDispatchSignal.js

@@ -0,0 +1,14 @@
+export class DeferredDispatchSignal extends Error {
+    info;
+    constructor(info) {
+        super(`Run ${info.runId} for workflow '${info.workflowName}' was deferred ` +
+            `(${info.status}; scheduledAt=${info.scheduledAt}; pingCount=${info.pingCount}).`);
+        this.name = "DeferredDispatchSignal";
+        this.info = info;
+        Object.setPrototypeOf(this, DeferredDispatchSignal.prototype);
+    }
+}
+export function isDeferredDispatchSignal(err) {
+    return err instanceof DeferredDispatchSignal;
+}
+//# sourceMappingURL=DeferredDispatchSignal.js.map

package/dist/scheduling/DeferredDispatchSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeferredDispatchSignal.js","sourceRoot":"","sources":["../../src/scheduling/DeferredDispatchSignal.ts"],"names":[],"mappings":"AA8CA,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAChC,IAAI,CAAuB;IAE3C,YAAY,IAA0B;QACrC,KAAK,CACJ,OAAO,IAAI,CAAC,KAAK,kBAAkB,IAAI,CAAC,YAAY,iBAAiB;YACpE,IAAI,IAAI,CAAC,MAAM,iBAAiB,IAAI,CAAC,WAAW,eAAe,IAAI,CAAC,SAAS,IAAI,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACD;AAED,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACpD,OAAO,GAAG,YAAY,sBAAsB,CAAC;AAC9C,CAAC"}

package/dist/scheduling/DeferredRunScheduler.d.ts

@@ -0,0 +1,68 @@
+import type { ScheduledDispatchRow } from "../tracing/types";
+export type DeferredDispatchFn = () => Promise<void>;
+/**
+ * Optional persistence payload — when supplied to `schedule()`, the
+ * scheduler writes a `scheduled_dispatches` row before registering the
+ * timer, and deletes it on cancel or fire. Trigger boot recovery
+ * (e.g. `HttpTrigger.recoverDispatches`) reads these rows to re-register
+ * timers across process restarts.
+ */
+export interface DeferredScheduleOptions {
+    workflowName: string;
+    /** Trigger type — `"http"` for v1; future triggers can opt in. */
+    triggerType: string;
+    /** TTL deadline (ms since epoch). When set, expired rows get marked `expired` on boot recovery. */
+    expiresAt?: number;
+    /** Mirrors the run record's status. */
+    dispatchStatus: ScheduledDispatchRow["dispatchStatus"];
+    /**
+     * JSON-serializable trigger-defined payload sufficient to reconstruct
+     * dispatch on boot. Trigger packages choose what to put here.
+     */
+    payload: unknown;
+}
+export declare class DeferredRunScheduler {
+    private static instance;
+    private entries;
+    static getInstance(): DeferredRunScheduler;
+    /** Test-only — reset the singleton. Cancels all pending timers. */
+    static resetInstance(): void;
+    /**
+     * Register a deferred dispatch. The timer fires at `dispatchAt`
+     * (clamped to ≥ now); when it fires, the entry is removed from the
+     * map and `dispatchFn` is invoked. Errors thrown by `dispatchFn` are
+     * swallowed and logged — the scheduler is fire-and-forget by design.
+     *
+     * Re-scheduling the same `runId` cancels the previous timer and
+     * replaces it (used by the debounce coordinator's "reset on ping").
+     *
+     * When `persist` is provided, the scheduler also writes a
+     * `scheduled_dispatches` row before registering the timer (so a
+     * crash leaves the dispatch recoverable), and deletes the row on
+     * cancel or fire.
+     */
+    schedule(runId: string, dispatchAt: number, dispatchFn: DeferredDispatchFn, persist?: DeferredScheduleOptions): void;
+    /**
+     * Cancel a pending dispatch. Returns true if the entry existed and
+     * was cancelled; false otherwise. Idempotent. When the entry was
+     * persisted, also deletes the `scheduled_dispatches` row.
+     *
+     * `cancelPersistedOnly` (default false) lets callers force the
+     * persistence-row delete even when the in-memory timer is gone (e.g.
+     * recovery cleanup that knows about a row but never had a timer).
+     */
+    cancel(runId: string, cancelPersistedOnly?: boolean): boolean;
+    private deletePersistedRow;
+    /** True if `runId` has a pending timer. */
+    has(runId: string): boolean;
+    /** Number of pending timers. Useful for tests + observability. */
+    size(): number;
+    /**
+     * Fire ALL pending dispatches immediately and clear the queue.
+     * Awaits each `dispatchFn` so the caller knows when the queue is
+     * drained. Useful for graceful shutdown.
+     */
+    drainAll(): Promise<void>;
+    /** Cancel everything without dispatching. */
+    clear(): void;
+}

package/dist/scheduling/DeferredRunScheduler.js

@@ -0,0 +1,154 @@
+/**
+ * Tier 2 #5 — in-memory scheduler for deferred workflow runs. Tier 2
+ * #5+#7 follow-up adds optional sqlite-backed durability via the
+ * {@link DeferredScheduleOptions.persist} parameter.
+ *
+ * Process-wide singleton; obtained via {@link DeferredRunScheduler.getInstance}.
+ * Reset between tests via {@link DeferredRunScheduler.resetInstance}.
+ */
+import { RunTracker } from "../tracing/RunTracker";
+export class DeferredRunScheduler {
+    static instance = null;
+    entries = new Map();
+    static getInstance() {
+        if (!DeferredRunScheduler.instance) {
+            DeferredRunScheduler.instance = new DeferredRunScheduler();
+        }
+        return DeferredRunScheduler.instance;
+    }
+    /** Test-only — reset the singleton. Cancels all pending timers. */
+    static resetInstance() {
+        DeferredRunScheduler.instance?.clear();
+        DeferredRunScheduler.instance = null;
+    }
+    /**
+     * Register a deferred dispatch. The timer fires at `dispatchAt`
+     * (clamped to ≥ now); when it fires, the entry is removed from the
+     * map and `dispatchFn` is invoked. Errors thrown by `dispatchFn` are
+     * swallowed and logged — the scheduler is fire-and-forget by design.
+     *
+     * Re-scheduling the same `runId` cancels the previous timer and
+     * replaces it (used by the debounce coordinator's "reset on ping").
+     *
+     * When `persist` is provided, the scheduler also writes a
+     * `scheduled_dispatches` row before registering the timer (so a
+     * crash leaves the dispatch recoverable), and deletes the row on
+     * cancel or fire.
+     */
+    schedule(runId, dispatchAt, dispatchFn, persist) {
+        // Persist BEFORE the timer so a crash between persist + setTimeout
+        // still leaves the row recoverable.
+        const persisted = persist !== undefined;
+        if (persisted) {
+            const tracker = RunTracker.getInstance();
+            if (tracker.active) {
+                try {
+                    tracker.getStore().upsertScheduledDispatch({
+                        runId,
+                        workflowName: persist.workflowName,
+                        triggerType: persist.triggerType,
+                        scheduledAt: dispatchAt,
+                        expiresAt: persist.expiresAt,
+                        dispatchStatus: persist.dispatchStatus,
+                        payload: persist.payload,
+                        createdAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    // Don't block the dispatch on persistence failure — log and continue.
+                    console.error(`[blok][scheduling] persist failed for run ${runId}; continuing in-memory only:`, err instanceof Error ? err.stack || err.message : err);
+                }
+            }
+        }
+        // Replace any existing entry for this runId.
+        const existing = this.entries.get(runId);
+        if (existing)
+            clearTimeout(existing.timer);
+        const delay = Math.max(0, dispatchAt - Date.now());
+        const timer = setTimeout(() => {
+            this.entries.delete(runId);
+            // Best-effort delete the persisted row before invoking dispatchFn —
+            // dispatch will write the run's terminal status separately.
+            if (persisted)
+                this.deletePersistedRow(runId);
+            void dispatchFn().catch((err) => {
+                console.error(`[blok][scheduling] DeferredRunScheduler dispatch failed for run ${runId}:`, err instanceof Error ? err.stack || err.message : err);
+            });
+        }, delay);
+        // `Node` will keep the event loop alive for pending timers — that's
+        // the desired behavior for delayed runs in long-running services.
+        // `unref()` would be wrong here.
+        this.entries.set(runId, { runId, dispatchAt, timer, dispatchFn, persisted });
+    }
+    /**
+     * Cancel a pending dispatch. Returns true if the entry existed and
+     * was cancelled; false otherwise. Idempotent. When the entry was
+     * persisted, also deletes the `scheduled_dispatches` row.
+     *
+     * `cancelPersistedOnly` (default false) lets callers force the
+     * persistence-row delete even when the in-memory timer is gone (e.g.
+     * recovery cleanup that knows about a row but never had a timer).
+     */
+    cancel(runId, cancelPersistedOnly = false) {
+        const entry = this.entries.get(runId);
+        if (!entry) {
+            if (cancelPersistedOnly) {
+                return this.deletePersistedRow(runId);
+            }
+            return false;
+        }
+        clearTimeout(entry.timer);
+        this.entries.delete(runId);
+        if (entry.persisted)
+            this.deletePersistedRow(runId);
+        return true;
+    }
+    deletePersistedRow(runId) {
+        const tracker = RunTracker.getInstance();
+        if (!tracker.active)
+            return false;
+        try {
+            return tracker.getStore().deleteScheduledDispatch(runId);
+        }
+        catch (err) {
+            console.error(`[blok][scheduling] persist-cleanup failed for run ${runId}:`, err instanceof Error ? err.stack || err.message : err);
+            return false;
+        }
+    }
+    /** True if `runId` has a pending timer. */
+    has(runId) {
+        return this.entries.has(runId);
+    }
+    /** Number of pending timers. Useful for tests + observability. */
+    size() {
+        return this.entries.size;
+    }
+    /**
+     * Fire ALL pending dispatches immediately and clear the queue.
+     * Awaits each `dispatchFn` so the caller knows when the queue is
+     * drained. Useful for graceful shutdown.
+     */
+    async drainAll() {
+        const toFire = Array.from(this.entries.values());
+        // Cancel all timers first so we don't double-dispatch.
+        for (const entry of toFire)
+            clearTimeout(entry.timer);
+        this.entries.clear();
+        // Sequential dispatch — preserves intended order if it matters.
+        for (const entry of toFire) {
+            try {
+                await entry.dispatchFn();
+            }
+            catch (err) {
+                console.error(`[blok][scheduling] drainAll dispatch failed for run ${entry.runId}:`, err instanceof Error ? err.stack || err.message : err);
+            }
+        }
+    }
+    /** Cancel everything without dispatching. */
+    clear() {
+        for (const entry of this.entries.values())
+            clearTimeout(entry.timer);
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=DeferredRunScheduler.js.map

package/dist/scheduling/DeferredRunScheduler.js.map

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

package/dist/scheduling/readSchedulingConfig.d.ts

@@ -0,0 +1,24 @@
+/** Parsed, normalized debounce config ready for the coordinator. */
+export interface NormalizedDebounceConfig {
+    keyExpression: string;
+    mode: "leading" | "trailing";
+    delayMs: number;
+    maxDelayMs?: number;
+}
+/** Parsed, normalized scheduling config ready for the gates. */
+export interface NormalizedSchedulingConfig {
+    /** Delay in ms; undefined when no delay configured. */
+    delayMs?: number;
+    /** TTL in ms; undefined when no TTL configured. */
+    ttlMs?: number;
+    /** Debounce config; undefined when no debounce configured. */
+    debounce?: NormalizedDebounceConfig;
+}
+/**
+ * Read a workflow's trigger config and return the normalized scheduling
+ * config, or null when the workflow has no scheduling gates.
+ */
+export declare function readSchedulingConfig(trigger: Record<string, unknown> | undefined | null): NormalizedSchedulingConfig | null;
+export declare const SCHEDULING_DEFAULTS: {
+    readonly debounceMode: "trailing";
+};

package/dist/scheduling/readSchedulingConfig.js

@@ -0,0 +1,52 @@
+/**
+ * Tier 2 #5 + #7 — extract scheduling config from a workflow's trigger
+ * block, regardless of which trigger type owns it (HTTP, Worker, …).
+ *
+ * Returns `null` when the trigger has NO scheduling fields set. The
+ * caller (`TriggerBase.run()`) treats null as "skip the gates, run the
+ * workflow synchronously" — zero-overhead default.
+ *
+ * Upfront duration parsing converts `"1h"` → `3600000` so downstream
+ * code only deals in milliseconds. Invalid duration values are dropped
+ * (treated as if the field were unset) — this is fail-open by design,
+ * matching `idempotencyKey` semantics. Use `BLOK_MAPPER_MODE=strict`
+ * for fail-fast behavior in production (handled at the trigger config
+ * validation layer, not here).
+ */
+import { tryParseDuration } from "@blokjs/helper";
+const SCHEDULING_TRIGGER_KEYS = ["http", "worker"];
+/**
+ * Read a workflow's trigger config and return the normalized scheduling
+ * config, or null when the workflow has no scheduling gates.
+ */
+export function readSchedulingConfig(trigger) {
+    if (!trigger)
+        return null;
+    for (const triggerKey of SCHEDULING_TRIGGER_KEYS) {
+        const cfg = trigger[triggerKey];
+        if (!cfg)
+            continue;
+        const delayMs = cfg.delay !== undefined ? (tryParseDuration(cfg.delay) ?? undefined) : undefined;
+        const ttlMs = cfg.ttl !== undefined ? (tryParseDuration(cfg.ttl) ?? undefined) : undefined;
+        let debounce;
+        if (cfg.debounce && typeof cfg.debounce === "object") {
+            const d = cfg.debounce;
+            const keyExpression = typeof d.key === "string" ? d.key.trim() : "";
+            const dDelayMs = d.delay !== undefined ? (tryParseDuration(d.delay) ?? undefined) : undefined;
+            if (keyExpression && dDelayMs !== undefined && dDelayMs >= 0) {
+                const mode = d.mode === "leading" ? "leading" : "trailing";
+                const maxDelayMs = d.maxDelay !== undefined ? (tryParseDuration(d.maxDelay) ?? undefined) : undefined;
+                debounce = { keyExpression, mode, delayMs: dDelayMs, maxDelayMs };
+            }
+        }
+        const hasAny = delayMs !== undefined || ttlMs !== undefined || debounce !== undefined;
+        if (hasAny) {
+            return { delayMs, ttlMs, debounce };
+        }
+    }
+    return null;
+}
+export const SCHEDULING_DEFAULTS = {
+    debounceMode: "trailing",
+};
+//# sourceMappingURL=readSchedulingConfig.js.map

package/dist/scheduling/readSchedulingConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readSchedulingConfig.js","sourceRoot":"","sources":["../../src/scheduling/readSchedulingConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAU,CAAC;AAiC5D;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAmD;IAEnD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,KAAK,MAAM,UAAU,IAAI,uBAAuB,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAA8B,CAAC;QAC7D,IAAI,CAAC,GAAG;YAAE,SAAS;QAEnB,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjG,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE3F,IAAI,QAA8C,CAAC;QACnD,IAAI,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;YACvB,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9F,IAAI,aAAa,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,GAA2B,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;gBACnF,MAAM,UAAU,GAAG,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACtG,QAAQ,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;YACnE,CAAC;QACF,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,CAAC;QACtF,IAAI,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QACrC,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,YAAY,EAAE,UAAmB;CACxB,CAAC"}

package/dist/timeouts/StepTimeoutError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tier 2 quick-wins — thrown by `RunnerSteps` when a step's
+ * `step.process()` exceeds its `maxDuration` cap.
+ *
+ * The error participates in the existing retry loop: each retry
+ * attempt wraps its own setTimeout-based timeout, so a step that
+ * times out N times will trigger N retries (each capped at
+ * `maxDuration`) before the run flips to `"timedOut"`.
+ *
+ * Note: setTimeout-based timeout REJECTS the wrapper promise but
+ * doesn't truly abort the underlying async work — the
+ * `step.process()` continues running until natural completion.
+ * The parent runner has already moved on; the orphaned promise
+ * resolves harmlessly into the void. Proper cooperative
+ * cancellation via `AbortSignal` is a deferred follow-up.
+ */
+export declare class StepTimeoutError extends Error {
+    readonly stepName: string;
+    readonly maxDurationMs: number;
+    constructor(stepName: string, maxDurationMs: number);
+}
+export declare function isStepTimeoutError(err: unknown): err is StepTimeoutError;

package/dist/timeouts/StepTimeoutError.js

@@ -0,0 +1,31 @@
+/**
+ * Tier 2 quick-wins — thrown by `RunnerSteps` when a step's
+ * `step.process()` exceeds its `maxDuration` cap.
+ *
+ * The error participates in the existing retry loop: each retry
+ * attempt wraps its own setTimeout-based timeout, so a step that
+ * times out N times will trigger N retries (each capped at
+ * `maxDuration`) before the run flips to `"timedOut"`.
+ *
+ * Note: setTimeout-based timeout REJECTS the wrapper promise but
+ * doesn't truly abort the underlying async work — the
+ * `step.process()` continues running until natural completion.
+ * The parent runner has already moved on; the orphaned promise
+ * resolves harmlessly into the void. Proper cooperative
+ * cancellation via `AbortSignal` is a deferred follow-up.
+ */
+export class StepTimeoutError extends Error {
+    stepName;
+    maxDurationMs;
+    constructor(stepName, maxDurationMs) {
+        super(`Step '${stepName}' exceeded maxDuration of ${maxDurationMs}ms`);
+        this.name = "StepTimeoutError";
+        this.stepName = stepName;
+        this.maxDurationMs = maxDurationMs;
+        Object.setPrototypeOf(this, StepTimeoutError.prototype);
+    }
+}
+export function isStepTimeoutError(err) {
+    return err instanceof StepTimeoutError;
+}
+//# sourceMappingURL=StepTimeoutError.js.map

package/dist/timeouts/StepTimeoutError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepTimeoutError.js","sourceRoot":"","sources":["../../src/timeouts/StepTimeoutError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAC1B,QAAQ,CAAS;IACjB,aAAa,CAAS;IAEtC,YAAY,QAAgB,EAAE,aAAqB;QAClD,KAAK,CAAC,SAAS,QAAQ,6BAA6B,aAAa,IAAI,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACzD,CAAC;CACD;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC9C,OAAO,GAAG,YAAY,gBAAgB,CAAC;AACxC,CAAC"}

package/dist/tracing/InMemoryRunStore.d.ts

@@ -1,5 +1,5 @@
 import type { RunStore } from "./RunStore";
-import type { Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
+import type { CachedStepResult, ConcurrencySlotResult, Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, ScheduledDispatchRow, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
 /**
  * In-memory implementation of RunStore using Maps.
  * Zero dependencies, fastest possible reads/writes.
@@ -12,6 +12,11 @@ export declare class InMemoryRunStore implements RunStore {
     private events;
     private logs;
     private dashboards;
+    private idempotencyCache;
+    private concurrencyLocks;
+    private scheduledDispatches;
+    private idemKey;
+    private concurrencyBucketKey;
     saveRun(run: WorkflowRun): void;
     updateRun(runId: string, updates: Partial<WorkflowRun>): void;
     saveNodeRun(nodeRun: NodeRun): void;
@@ -25,6 +30,7 @@ export declare class InMemoryRunStore implements RunStore {
     };
     getNodeRuns(runId: string): NodeRun[];
     getNodeRun(nodeRunId: string): NodeRun | undefined;
+    getRunsByParent(parentRunId: string): WorkflowRun[];
     getEvents(runId: string, since?: number): RunEvent[];
     getLogs(runId: string, nodeId?: string): TraceLogEntry[];
     getWorkflowSummaries(): WorkflowSummary[];
@@ -39,6 +45,27 @@ export declare class InMemoryRunStore implements RunStore {
     clearAll(): number;
     deleteRunsBefore(timestamp: number): number;
     evictOldRuns(maxRuns: number): void;
+    getIdempotencyCache(workflowName: string, stepId: string, key: string): CachedStepResult | null;
+    setIdempotencyCache(workflowName: string, stepId: string, key: string, entry: CachedStepResult): void;
+    purgeExpiredIdempotencyCache(now: number): number;
+    acquireConcurrencySlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): ConcurrencySlotResult;
+    releaseConcurrencySlot(workflowName: string, concurrencyKey: string, runId: string): void;
+    purgeExpiredConcurrencySlots(now: number): number;
+    getConcurrencySnapshot(now: number): Array<{
+        workflowName: string;
+        concurrencyKey: string;
+        leases: Array<{
+            runId: string;
+            expiresAt: number;
+        }>;
+    }>;
+    upsertScheduledDispatch(row: ScheduledDispatchRow): void;
+    deleteScheduledDispatch(runId: string): boolean;
+    getScheduledDispatches(opts?: {
+        triggerType?: string;
+        status?: string;
+    }): ScheduledDispatchRow[];
+    purgeExpiredScheduledDispatches(now: number): number;
     close(): void;
     private deleteRun;
 }