@adonis-agora/durable 0.1.0

package/dist/src/admission-redis/redis-admission-backend.js

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+// One atomic admit. Reclaims dead-instance slots, prunes stale waiters, enforces the rate window and
+// the concurrency cap, then selects the rightful next waiter by (priority desc, fairness round-robin,
+// arrival FIFO/LIFO) before taking a slot — all server-side so concurrent pods can't race past the cap.
+// Returns {admitted (1|0), retryAt}.
+//   KEYS 1 slots(hash slotId→instanceId)  2 waiters(zset waiterId→-priority)  3 wmeta(hash waiterId→"seq|key")
+//        4 wexpire(zset waiterId→expiry)   5 keyserved(hash key→tick)          6 rate(string)
+//        7 seq(string)                     8 servedSeq(string)
+const ACQUIRE_LUA = `
+local p=cjson.decode(ARGV[1])
+local now=p.now; local instanceId=p.instanceId; local concurrency=p.concurrency
+local rateLimit=p.rateLimit; local ratePeriodMs=p.ratePeriodMs; local waiterId=p.waiterId
+local priority=p.priority; local retryAt=p.retryAt; local hasOrdering=p.hasOrdering
+local fairnessOn=p.fairnessOn; local fairKey=p.fairKey; local instPrefix=p.instPrefix
+local waiterTtl=p.waiterTtl; local instTtl=p.instTtl; local lifo=p.lifo
+
+-- refresh own liveness atomically so this pod can never reclaim its own fresh slot
+redis.call('SET', instPrefix..instanceId, '1', 'PX', instTtl)
+
+-- reclaim slots whose owning instance is gone; count the live ones
+local slotIds=redis.call('HKEYS', KEYS[1]); local inflight=0
+for i=1,#slotIds do
+  local owner=redis.call('HGET', KEYS[1], slotIds[i])
+  if owner and redis.call('EXISTS', instPrefix..owner)==1 then inflight=inflight+1
+  else redis.call('HDEL', KEYS[1], slotIds[i]) end
+end
+
+-- prune waiters that stopped retrying (cancelled/abandoned)
+local stale=redis.call('ZRANGEBYSCORE', KEYS[4], '-inf', now)
+for i=1,#stale do
+  redis.call('ZREM', KEYS[2], stale[i]); redis.call('HDEL', KEYS[3], stale[i]); redis.call('ZREM', KEYS[4], stale[i])
+end
+
+if rateLimit>0 then
+  local used=tonumber(redis.call('GET', KEYS[6]) or '0')
+  if used>=rateLimit then return {0, retryAt} end
+end
+
+local function register()
+  if redis.call('ZSCORE', KEYS[2], waiterId)==false then
+    local seq=redis.call('INCR', KEYS[7])
+    redis.call('HSET', KEYS[3], waiterId, seq..'|'..fairKey)
+  end
+  redis.call('ZADD', KEYS[2], -priority, waiterId)
+  redis.call('ZADD', KEYS[4], now+waiterTtl, waiterId)
+end
+
+if concurrency>0 and inflight>=concurrency then
+  if hasOrdering==1 then register() end
+  return {0, retryAt}
+end
+
+if hasOrdering==1 then
+  register()
+  local firstWS=redis.call('ZRANGE', KEYS[2], 0, 0, 'WITHSCORES')
+  local topScore=firstWS[2]
+  local tier=redis.call('ZRANGEBYSCORE', KEYS[2], topScore, topScore)
+  local bestId=nil; local bestServed=nil; local bestSeq=nil
+  for i=1,#tier do
+    local wid=tier[i]; local meta=redis.call('HGET', KEYS[3], wid)
+    if meta then
+      local sep=string.find(meta, '|', 1, true)
+      local seq=tonumber(string.sub(meta, 1, sep-1))
+      local k=string.sub(meta, sep+1)
+      local served=0
+      if fairnessOn==1 and k~='' then served=tonumber(redis.call('HGET', KEYS[5], k) or '0') end
+      local better=false
+      if bestId==nil then better=true
+      elseif served<bestServed then better=true
+      elseif served==bestServed then
+        if lifo==1 then better=(seq>bestSeq) else better=(seq<bestSeq) end
+      end
+      if better then bestId=wid; bestServed=served; bestSeq=seq end
+    end
+  end
+  if bestId~=waiterId then return {0, retryAt} end
+end
+
+-- admit
+redis.call('HSET', KEYS[1], waiterId, instanceId)
+redis.call('ZREM', KEYS[2], waiterId); redis.call('HDEL', KEYS[3], waiterId); redis.call('ZREM', KEYS[4], waiterId)
+if fairnessOn==1 and fairKey~='' then
+  local tick=redis.call('INCR', KEYS[8]); redis.call('HSET', KEYS[5], fairKey, tick)
+end
+if rateLimit>0 then redis.call('INCR', KEYS[6]); redis.call('PEXPIRE', KEYS[6], ratePeriodMs) end
+return {1, 0}
+`;
+/**
+ * An {@link AdmissionBackend} whose state lives in Redis, so `concurrency` / `rateLimit` / priority +
+ * fairness ordering are enforced ACROSS every engine replica instead of per-process.
+ *
+ * - **Concurrency** is a hash of slot→owning-instance; a slot is reclaimed only when its owner's
+ *   liveness heartbeat lapses, so a live pod holds its slot for the full step duration (no time-lease
+ *   false purge) while a crashed pod's slots free within `instanceTtlMs`.
+ * - **Rate limit** is a fixed-window counter.
+ * - **Ordering** registers blocked callers and, when a slot frees, admits the rightful next under
+ *   (priority desc → fairness round-robin by `key` → arrival FIFO/LIFO). Abandoned waiters are pruned
+ *   so a cancelled run can't sit as a phantom best-waiter.
+ *
+ * Targets a single (non-cluster) Redis — the atomic Lua spans multiple keys.
+ */
+export class RedisAdmissionBackend {
+    redis;
+    prefix;
+    instanceId;
+    instanceTtlMs;
+    waiterTtlMs;
+    retryMs;
+    clock;
+    configs = new Map();
+    heartbeat;
+    subscriber;
+    constructor(options) {
+        this.redis = options.connection;
+        this.prefix = options.prefix ?? 'durable';
+        this.instanceId = options.instanceId ?? randomUUID();
+        this.instanceTtlMs = options.instanceTtlMs ?? 30_000;
+        this.retryMs = options.retryMs ?? 1000;
+        this.waiterTtlMs = options.waiterTtlMs ?? this.retryMs * 3;
+        this.clock = options.clock ?? Date.now;
+        this.redis.defineCommand('admissionAcquire', { numberOfKeys: 8, lua: ACQUIRE_LUA });
+        // Keep this instance's liveness fresh even while idle, so slots it holds aren't reclaimed.
+        void this.refreshLiveness();
+        this.heartbeat = setInterval(() => void this.refreshLiveness().catch(() => undefined), Math.max(1000, Math.floor(this.instanceTtlMs / 3)));
+        this.heartbeat.unref?.();
+    }
+    register(config) {
+        this.configs.set(config.name, config);
+    }
+    handles(queue) {
+        return this.configs.has(queue);
+    }
+    async tryAdmit(queue, item) {
+        const config = this.configs.get(queue);
+        if (!config)
+            return { ok: true }; // unregistered queue → ungated
+        const now = this.clock();
+        const rate = config.rateLimit;
+        const fairnessOn = config.fairness === 'key' ? 1 : 0;
+        const lifo = config.order === 'lifo' ? 1 : 0;
+        const fairKey = fairnessOn === 1 ? (item.key ?? '') : '';
+        // Order-track every call that carries a stable waiterId (the engine always does), so even a plain
+        // concurrency queue admits blocked waiters by arrival FIFO — identical to the in-process backend.
+        const hasOrdering = item.waiterId != null || item.priority != null || fairnessOn === 1 || lifo === 1 ? 1 : 0;
+        const rateKey = rate
+            ? this.key(queue, 'rate', Math.floor(now / rate.periodMs))
+            : this.key(queue, 'rate', 0);
+        const params = {
+            now,
+            instanceId: this.instanceId,
+            concurrency: config.concurrency ?? 0,
+            rateLimit: rate?.limit ?? 0,
+            ratePeriodMs: rate?.periodMs ?? 0,
+            waiterId: item.waiterId ?? `anon:${now}`,
+            priority: item.priority ?? 0,
+            retryAt: now + this.retryMs,
+            hasOrdering,
+            fairnessOn,
+            fairKey,
+            instPrefix: this.instPrefix(),
+            waiterTtl: this.waiterTtlMs,
+            instTtl: this.instanceTtlMs,
+            lifo,
+        };
+        const [admitted, retryAt] = await this.redis.admissionAcquire(this.key(queue, 'slots'), this.key(queue, 'waiters'), this.key(queue, 'wmeta'), this.key(queue, 'wexpire'), this.key(queue, 'keyserved'), rateKey, this.key(queue, 'seq'), this.key(queue, 'servedseq'), JSON.stringify(params));
+        return admitted === 1 ? { ok: true } : { ok: false, retryAt };
+    }
+    async release(queue, slotId) {
+        await this.redis.hdel(this.key(queue, 'slots'), slotId);
+        // Tell the fleet a slot freed so blocked waiters can re-contend now (best-effort; the retry tick
+        // is the guarantee). One channel, queue name as payload.
+        await this.redis.publish(this.freedChannel(), queue);
+    }
+    onFreed(handler) {
+        // A subscriber connection can't run normal commands, so use a dedicated dup of the connection.
+        const sub = this.redis.duplicate();
+        this.subscriber = sub;
+        void sub.subscribe(this.freedChannel());
+        sub.on('message', (_channel, queue) => handler(queue));
+    }
+    /** Stop the liveness heartbeat + subscriber (held slots lapse within `instanceTtlMs`). */
+    async close() {
+        clearInterval(this.heartbeat);
+        this.subscriber?.disconnect();
+    }
+    freedChannel() {
+        return `${this.prefix}:adm:freed`;
+    }
+    async refreshLiveness() {
+        await this.redis.set(`${this.instPrefix()}${this.instanceId}`, '1', 'PX', this.instanceTtlMs);
+    }
+    instPrefix() {
+        return `${this.prefix}:adm:inst:`;
+    }
+    key(queue, part, window) {
+        const base = `${this.prefix}:adm:${queue}:${part}`;
+        return window === undefined ? base : `${base}:${window}`;
+    }
+}
+//# sourceMappingURL=redis-admission-backend.js.map

package/dist/src/admission-redis/redis-admission-backend.js.map

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

package/dist/src/admission.d.ts

@@ -0,0 +1,49 @@
+import { type Admission, type AdmissionItem, type QueueConfig } from './queue.js';
+/**
+ * Pluggable backend for the remote-step flow-control gate (`ctx.call(step, input, { queue })`). The
+ * engine asks it whether a queued call may be admitted now (concurrency / rate / ordering) and tells
+ * it when an admitted slot is released.
+ *
+ * The default {@link InMemoryAdmissionBackend} keeps per-instance counts — correct for a single
+ * orchestrator. Swap in a store/Redis-backed backend to make the caps and ordering GLOBAL across
+ * engine replicas (so `concurrency: 5` means 5 in-flight across the whole fleet, not 5 per pod).
+ *
+ * `tryAdmit`/`release` are async so a global backend can do its atomic round-trip; the in-memory one
+ * resolves synchronously. An UNREGISTERED queue name is treated as ungated (admits immediately) — the
+ * engine only tracks/releases a slot for a registered queue.
+ */
+export interface AdmissionBackend {
+    /** Register (or replace) a queue's config. Called from `engine.registerQueue`. */
+    register(config: QueueConfig): void;
+    /** Whether `queue` is registered (gated). The engine only tracks/releases a slot for a gated queue. */
+    handles(queue: string): boolean;
+    /** May a call on `queue` take a slot now? On `ok`, the caller holds a slot until {@link release}. */
+    tryAdmit(queue: string, item: AdmissionItem): Promise<Admission>;
+    /**
+     * Release the slot granted by {@link tryAdmit} for `queue`. `slotId` is the admitted item's
+     * `waiterId` (the engine's stepId), so a lease-based backend can drop the exact slot; an in-process
+     * counter ignores it.
+     */
+    release(queue: string, slotId: string): Promise<void>;
+    /**
+     * Optional: subscribe to "a slot just freed on `queue`" events (e.g. a fleet-wide pub/sub). The
+     * engine uses it to wake its admission-blocked runs early instead of waiting for their retry tick.
+     * A backend without it falls back to retry-tick polling. Fired best-effort across the fleet.
+     */
+    onFreed?(handler: (queue: string) => void): void;
+}
+/**
+ * Default admission backend: one in-process {@link QueueController} per registered queue. Caps and
+ * waiter ordering are per engine instance (see {@link QueueConfig}). Preserves the exact pre-backend
+ * behaviour — the engine used to hold these controllers directly.
+ */
+export declare class InMemoryAdmissionBackend implements AdmissionBackend {
+    private readonly clock;
+    private readonly controllers;
+    constructor(clock: () => number);
+    register(config: QueueConfig): void;
+    handles(queue: string): boolean;
+    tryAdmit(queue: string, item: AdmissionItem): Promise<Admission>;
+    release(queue: string, _slotId: string): Promise<void>;
+}
+//# sourceMappingURL=admission.d.ts.map

package/dist/src/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../src/admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAmB,MAAM,YAAY,CAAC;AAEnG;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,uGAAuG;IACvG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjE;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;OAIG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAGnD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;gBAErC,KAAK,EAAE,MAAM,MAAM;IAEhD,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAInC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIzB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAOhE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG7D"}

package/dist/src/admission.js

@@ -0,0 +1,30 @@
+import { QueueController } from './queue.js';
+/**
+ * Default admission backend: one in-process {@link QueueController} per registered queue. Caps and
+ * waiter ordering are per engine instance (see {@link QueueConfig}). Preserves the exact pre-backend
+ * behaviour — the engine used to hold these controllers directly.
+ */
+export class InMemoryAdmissionBackend {
+    clock;
+    controllers = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    register(config) {
+        this.controllers.set(config.name, new QueueController(config, this.clock));
+    }
+    handles(queue) {
+        return this.controllers.has(queue);
+    }
+    async tryAdmit(queue, item) {
+        const controller = this.controllers.get(queue);
+        // Unregistered queue → ungated (mirrors the old `this.queues.get(queue)` truthiness check).
+        if (!controller)
+            return { ok: true };
+        return controller.tryAdmit(item);
+    }
+    async release(queue, _slotId) {
+        this.controllers.get(queue)?.release();
+    }
+}
+//# sourceMappingURL=admission.js.map

package/dist/src/admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.js","sourceRoot":"","sources":["../../src/admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwD,eAAe,EAAE,MAAM,YAAY,CAAC;AAoCnG;;;;GAIG;AACH,MAAM,OAAO,wBAAwB;IAGN;IAFZ,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IAElE,YAA6B,KAAmB;QAAnB,UAAK,GAAL,KAAK,CAAc;IAAG,CAAC;IAEpD,QAAQ,CAAC,MAAmB;QAC1B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,IAAmB;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/C,4FAA4F;QAC5F,IAAI,CAAC,UAAU;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,OAAe;QAC1C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;CACF"}

package/dist/src/backoff.d.ts

@@ -0,0 +1,5 @@
+import type { StepOptions } from './interfaces.js';
+/** Delay in ms before the next retry attempt, per a step's `StepOptions` backoff config. Shared by
+ *  the local-step retry loop and the durable remote-step retry, so they stay consistent. */
+export declare function backoffDelay(attempt: number, options?: StepOptions): number;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/src/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;4FAC4F;AAC5F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAM3E"}

package/dist/src/backoff.js

@@ -0,0 +1,11 @@
+/** Delay in ms before the next retry attempt, per a step's `StepOptions` backoff config. Shared by
+ *  the local-step retry loop and the durable remote-step retry, so they stay consistent. */
+export function backoffDelay(attempt, options) {
+    const base = options?.backoffMs ?? 0;
+    if (base <= 0)
+        return 0;
+    const raw = options?.backoff === 'exp' ? base * 2 ** (attempt - 1) : base;
+    const capped = options?.backoffMaxMs ? Math.min(raw, options.backoffMaxMs) : raw;
+    return options?.jitter ? Math.round(capped * (0.5 + Math.random() * 0.5)) : capped;
+}
+//# sourceMappingURL=backoff.js.map

package/dist/src/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/backoff.ts"],"names":[],"mappings":"AAEA;4FAC4F;AAC5F,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,OAAqB;IACjE,MAAM,IAAI,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,MAAM,GAAG,GAAG,OAAO,EAAE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjF,OAAO,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AACrF,CAAC"}

package/dist/src/checkpoints.d.ts

@@ -0,0 +1,42 @@
+import type { StepCheckpoint, StepError, StepEvent, StepKind } from './interfaces.js';
+/**
+ * Build a *phased* step checkpoint — one with distinct enqueue/run/finish timestamps (a local step
+ * that is running/completed/failed, or a pending remote/sleep step). Computes the deterministic
+ * `stepId` and normalizes empty event arrays, so the engine's running/completed/failed/pending
+ * checkpoint literals are constructed in exactly one place instead of ~8.
+ *
+ * For instantaneous checkpoints (sleep timers, markers, delivered signals) use {@link instantCheckpoint}.
+ */
+export declare function stepCheckpoint(p: {
+    runId: string;
+    seq: number;
+    name: string;
+    kind: StepKind;
+    status: StepCheckpoint['status'];
+    attempts: number;
+    enqueuedAt: Date;
+    startedAt: Date;
+    finishedAt: Date;
+    input?: unknown;
+    output?: unknown;
+    error?: StepError | undefined;
+    events?: StepEvent[] | undefined;
+    workerGroup?: string | undefined;
+    wakeAt?: number | undefined;
+}): StepCheckpoint;
+/**
+ * Build an *instantaneous* checkpoint — one with no distinct enqueue/run/finish phases (a durable
+ * sleep timer, a breakpoint marker, a delivered signal, a published `setEvent` value, a `patched`
+ * marker). All three timestamps collapse to now and `attempts` is 1. Collapses what was five
+ * near-identical 10-field `saveCheckpoint({...})` literals into one builder.
+ */
+export declare function instantCheckpoint(p: {
+    runId: string;
+    seq: number;
+    name: string;
+    kind: StepKind;
+    status?: StepCheckpoint['status'];
+    output?: unknown;
+    wakeAt?: number;
+}): StepCheckpoint;
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/src/checkpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.d.ts","sourceRoot":"","sources":["../../src/checkpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAQtF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,GAAG,cAAc,CAmBjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,cAAc,CAgBjB"}

package/dist/src/checkpoints.js

@@ -0,0 +1,57 @@
+import { stepId } from './protocol.js';
+/** Drop an empty events array to `undefined` (the repeated `events?.length ? events : undefined`). */
+function nonEmptyEvents(events) {
+    return events && events.length > 0 ? events : undefined;
+}
+/**
+ * Build a *phased* step checkpoint — one with distinct enqueue/run/finish timestamps (a local step
+ * that is running/completed/failed, or a pending remote/sleep step). Computes the deterministic
+ * `stepId` and normalizes empty event arrays, so the engine's running/completed/failed/pending
+ * checkpoint literals are constructed in exactly one place instead of ~8.
+ *
+ * For instantaneous checkpoints (sleep timers, markers, delivered signals) use {@link instantCheckpoint}.
+ */
+export function stepCheckpoint(p) {
+    return {
+        runId: p.runId,
+        seq: p.seq,
+        name: p.name,
+        kind: p.kind,
+        stepId: stepId(p.runId, p.seq),
+        status: p.status,
+        input: p.input,
+        output: p.output,
+        error: p.error,
+        events: nonEmptyEvents(p.events),
+        attempts: p.attempts,
+        workerGroup: p.workerGroup,
+        wakeAt: p.wakeAt,
+        enqueuedAt: p.enqueuedAt,
+        startedAt: p.startedAt,
+        finishedAt: p.finishedAt,
+    };
+}
+/**
+ * Build an *instantaneous* checkpoint — one with no distinct enqueue/run/finish phases (a durable
+ * sleep timer, a breakpoint marker, a delivered signal, a published `setEvent` value, a `patched`
+ * marker). All three timestamps collapse to now and `attempts` is 1. Collapses what was five
+ * near-identical 10-field `saveCheckpoint({...})` literals into one builder.
+ */
+export function instantCheckpoint(p) {
+    const at = new Date();
+    return {
+        runId: p.runId,
+        seq: p.seq,
+        name: p.name,
+        kind: p.kind,
+        stepId: stepId(p.runId, p.seq),
+        status: p.status ?? 'completed',
+        output: p.output,
+        wakeAt: p.wakeAt,
+        attempts: 1,
+        enqueuedAt: at,
+        startedAt: at,
+        finishedAt: at,
+    };
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/src/checkpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.js","sourceRoot":"","sources":["../../src/checkpoints.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,sGAAsG;AACtG,SAAS,cAAc,CAAC,MAA+B;IACrD,OAAO,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,CAgB9B;IACC,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC;QAC9B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC;QAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,UAAU,EAAE,CAAC,CAAC,UAAU;KACzB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAQjC;IACC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;IACtB,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC;QAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,WAAW;QAC/B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC;QACX,UAAU,EAAE,EAAE;QACd,SAAS,EAAE,EAAE;QACb,UAAU,EAAE,EAAE;KACf,CAAC;AACJ,CAAC"}

package/dist/src/codec-state-store.d.ts

@@ -0,0 +1,60 @@
+import type { RunQuery, SignalWaiter, StateStore, StepCheckpoint, WorkflowRun } from './interfaces.js';
+/**
+ * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
+ * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
+ * cipher / codec); wrap an async KMS yourself if you need one.
+ */
+export interface PayloadCodec {
+    encode(value: unknown): unknown;
+    decode(value: unknown): unknown;
+}
+/**
+ * A `StateStore` decorator that runs run/step **payloads** (input + output) through a
+ * {@link PayloadCodec} — encoded on write, decoded on read — so they're never stored in the clear.
+ * Adapter-agnostic: wrap any store. Searchable metadata (id, status, workflow, tags, timestamps) and
+ * the structured `error` are left untouched so the dashboard, queries, and recovery still work.
+ *
+ * ```ts
+ * const store = new CodecStateStore(new TypeOrmStateStore(ds), aesCodec);
+ * ```
+ */
+export declare class CodecStateStore implements StateStore {
+    private readonly inner;
+    private readonly codec;
+    constructor(inner: StateStore, codec: PayloadCodec);
+    private enc;
+    private dec;
+    private encRun;
+    private decRun;
+    private encCp;
+    private decCp;
+    ensureSchema(): Promise<void>;
+    createRun(run: WorkflowRun): Promise<void>;
+    updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
+    getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    transaction<T>(work: (tx: {
+        raw: unknown;
+        saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
+    }) => Promise<T>): Promise<T>;
+    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
+    releaseRunLock(runId: string): Promise<void>;
+    renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
+    putSignalWaiter(waiter: SignalWaiter): Promise<void>;
+    takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
+    listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    bufferSignal(token: string, payload: unknown): Promise<void>;
+    takeBufferedSignal(token: string): Promise<{
+        payload: unknown;
+    } | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+}
+//# sourceMappingURL=codec-state-store.d.ts.map

package/dist/src/codec-state-store.d.ts.map

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

package/dist/src/codec-state-store.js

@@ -0,0 +1,129 @@
+/**
+ * A `StateStore` decorator that runs run/step **payloads** (input + output) through a
+ * {@link PayloadCodec} — encoded on write, decoded on read — so they're never stored in the clear.
+ * Adapter-agnostic: wrap any store. Searchable metadata (id, status, workflow, tags, timestamps) and
+ * the structured `error` are left untouched so the dashboard, queries, and recovery still work.
+ *
+ * ```ts
+ * const store = new CodecStateStore(new TypeOrmStateStore(ds), aesCodec);
+ * ```
+ */
+export class CodecStateStore {
+    inner;
+    codec;
+    constructor(inner, codec) {
+        this.inner = inner;
+        this.codec = codec;
+    }
+    enc(v) {
+        return v === undefined ? undefined : this.codec.encode(v);
+    }
+    dec(v) {
+        return v === undefined ? undefined : this.codec.decode(v);
+    }
+    encRun(run) {
+        return { ...run, input: this.enc(run.input), output: this.enc(run.output) };
+    }
+    decRun(run) {
+        return (run && { ...run, input: this.dec(run.input), output: this.dec(run.output) });
+    }
+    encCp(cp) {
+        return { ...cp, input: this.enc(cp.input), output: this.enc(cp.output) };
+    }
+    decCp(cp) {
+        return (cp && { ...cp, input: this.dec(cp.input), output: this.dec(cp.output) });
+    }
+    ensureSchema() {
+        return this.inner.ensureSchema?.() ?? Promise.resolve();
+    }
+    createRun(run) {
+        return this.inner.createRun(this.encRun(run));
+    }
+    updateRun(runId, patch) {
+        const next = { ...patch };
+        if ('input' in patch)
+            next.input = this.enc(patch.input);
+        if ('output' in patch)
+            next.output = this.enc(patch.output);
+        return this.inner.updateRun(runId, next);
+    }
+    async getRun(runId) {
+        return this.decRun(await this.inner.getRun(runId));
+    }
+    deleteRun(runId) {
+        return this.inner.deleteRun(runId);
+    }
+    async getCheckpoint(runId, seq) {
+        return this.decCp(await this.inner.getCheckpoint(runId, seq));
+    }
+    saveCheckpoint(checkpoint) {
+        return this.inner.saveCheckpoint(this.encCp(checkpoint));
+    }
+    transaction(work) {
+        if (!this.inner.transaction) {
+            throw new Error('the wrapped store does not support transactions');
+        }
+        // Encode the checkpoint inside the tx, so payloads stay encoded at rest like the normal path.
+        return this.inner.transaction((tx) => work({ raw: tx.raw, saveCheckpoint: (cp) => tx.saveCheckpoint(this.encCp(cp)) }));
+    }
+    async listIncompleteRuns() {
+        return (await this.inner.listIncompleteRuns()).map((r) => this.decRun(r));
+    }
+    async listPendingRuns(limit) {
+        return (await this.inner.listPendingRuns(limit)).map((r) => this.decRun(r));
+    }
+    async listDueTimers(nowMs) {
+        return (await this.inner.listDueTimers(nowMs)).map((r) => this.decRun(r));
+    }
+    tryLockRun(runId, owner, leaseUntilMs, nowMs) {
+        return this.inner.tryLockRun(runId, owner, leaseUntilMs, nowMs);
+    }
+    releaseRunLock(runId) {
+        return this.inner.releaseRunLock(runId);
+    }
+    renewRunLock(runId, owner, leaseUntilMs) {
+        return this.inner.renewRunLock(runId, owner, leaseUntilMs);
+    }
+    putSignalWaiter(waiter) {
+        return this.inner.putSignalWaiter(waiter);
+    }
+    takeSignalWaiter(token) {
+        return this.inner.takeSignalWaiter(token);
+    }
+    listSignalWaiters(prefix) {
+        return this.inner.listSignalWaiters(prefix);
+    }
+    bufferSignal(token, payload) {
+        return this.inner.bufferSignal(token, this.enc(payload));
+    }
+    async takeBufferedSignal(token) {
+        const buffered = await this.inner.takeBufferedSignal(token);
+        return buffered && { payload: this.dec(buffered.payload) };
+    }
+    async listRuns(query) {
+        return (await this.inner.listRuns(query)).map((r) => this.decRun(r));
+    }
+    async listCheckpoints(runId) {
+        return (await this.inner.listCheckpoints(runId)).map((c) => this.decCp(c));
+    }
+    async getLatestCheckpointByName(runId, name) {
+        // Forward the targeted read when the inner store implements it; otherwise fall back to the
+        // (always-present) listCheckpoints scan so wrapping a legacy custom store keeps working.
+        if (this.inner.getLatestCheckpointByName) {
+            const cp = await this.inner.getLatestCheckpointByName(runId, name);
+            return cp ? this.decCp(cp) : undefined;
+        }
+        let latest;
+        for (const cp of await this.inner.listCheckpoints(runId))
+            if (cp.name === name)
+                latest = cp;
+        return latest ? this.decCp(latest) : undefined;
+    }
+    async listCheckpointsByNamePrefix(runId, prefixes) {
+        const matches = this.inner.listCheckpointsByNamePrefix
+            ? await this.inner.listCheckpointsByNamePrefix(runId, prefixes)
+            : (await this.inner.listCheckpoints(runId)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+        return matches.map((c) => this.decCp(c));
+    }
+}
+//# sourceMappingURL=codec-state-store.js.map

package/dist/src/codec-state-store.js.map

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