@warlock.js/ai 4.2.10 → 4.3.0

package/esm/batch/run-batch-item.mjs

@@ -0,0 +1,100 @@
+import { isAbortError, resolveBackoff, resolveRetryConfig } from "../workflow/retry.mjs";
+import { toAIError } from "../workflow/step-runner.mjs";
+
+//#region ../@warlock.js/ai/src/batch/run-batch-item.ts
+/**
+* Sleep for `ms`, settling early (without throwing) if `signal`
+* aborts during the wait. The caller re-checks `signal.aborted` after
+* this resolves, so a silent early return is enough — we never want a
+* pending timer to keep the batch alive past cancellation.
+*/
+function sleep(ms, signal) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Execute one item with per-item retry, isolated so a failure can
+* neither throw nor disturb sibling items running in the same pool.
+*
+* Reuses the workflow retry vocabulary verbatim
+* ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and
+* workflow steps retry identically. An item is `"completed"` when the
+* primitive's own result carries no `error`; a primitive that returns
+* `result.error` (rather than throwing) is treated as a failed attempt
+* and re-run under the same policy.
+*
+* Cancellation short-circuits: if the signal is already aborted on
+* entry the item is reported `"cancelled"` without executing; an abort
+* observed mid-flight surfaces as `"cancelled"` too.
+*/
+async function runBatchItem(params) {
+	const { index, input, executable, signal } = params;
+	if (signal?.aborted) return {
+		index,
+		status: "cancelled",
+		attempts: 0
+	};
+	const retryConfig = resolveRetryConfig({ retry: params.retry }, void 0);
+	const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);
+	let lastResult;
+	let lastError;
+	let attemptsMade = 0;
+	for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+		if (signal?.aborted) return {
+			index,
+			status: "cancelled",
+			result: lastResult,
+			attempts: attemptsMade
+		};
+		attemptsMade = attempt;
+		try {
+			const result = await executable.execute(input, { signal });
+			lastResult = result;
+			if (!result.error) return {
+				index,
+				status: "completed",
+				result,
+				attempts: attempt
+			};
+			lastError = result.error;
+		} catch (error) {
+			if (isAbortError(error)) return {
+				index,
+				status: "cancelled",
+				result: lastResult,
+				attempts: attempt
+			};
+			lastError = error;
+		}
+		if (!(attempt < totalAttempts && (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true))) break;
+		retryConfig.onRetry?.(attempt + 1, lastError);
+		const delay = resolveBackoff(attempt, retryConfig.backoff);
+		if (delay > 0) await sleep(delay, signal);
+	}
+	if (signal?.aborted) return {
+		index,
+		status: "cancelled",
+		result: lastResult,
+		attempts: attemptsMade
+	};
+	return {
+		index,
+		status: "failed",
+		result: lastResult,
+		error: toAIError(lastError),
+		attempts: attemptsMade
+	};
+}
+
+//#endregion
+export { runBatchItem };
+//# sourceMappingURL=run-batch-item.mjs.map

package/esm/batch/run-batch-item.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-batch-item.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/run-batch-item.ts"],"sourcesContent":["import type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { RetryConfig } from \"../contracts/workflow/retry-config.type\";\nimport { isAbortError, resolveBackoff, resolveRetryConfig } from \"../workflow/retry\";\nimport { toAIError } from \"../workflow/step-runner\";\nimport type { BatchItemResult } from \"./batch.type\";\n\n/**\n * Parameters for {@link runBatchItem}. Kept as a plain bag so the\n * concurrency pool can build it once per index without a long\n * positional argument list.\n */\nexport type RunBatchItemParams<TInput, TOptions, TResult extends BaseResult> = {\n  index: number;\n  input: TInput;\n  executable: ExecutableContract<TInput, TOptions, TResult>;\n  retry: RetryConfig | undefined;\n  signal: AbortSignal | undefined;\n};\n\n/**\n * Sleep for `ms`, settling early (without throwing) if `signal`\n * aborts during the wait. The caller re-checks `signal.aborted` after\n * this resolves, so a silent early return is enough — we never want a\n * pending timer to keep the batch alive past cancellation.\n */\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  return new Promise((resolve) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      resolve();\n    };\n\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\n/**\n * Execute one item with per-item retry, isolated so a failure can\n * neither throw nor disturb sibling items running in the same pool.\n *\n * Reuses the workflow retry vocabulary verbatim\n * ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and\n * workflow steps retry identically. An item is `\"completed\"` when the\n * primitive's own result carries no `error`; a primitive that returns\n * `result.error` (rather than throwing) is treated as a failed attempt\n * and re-run under the same policy.\n *\n * Cancellation short-circuits: if the signal is already aborted on\n * entry the item is reported `\"cancelled\"` without executing; an abort\n * observed mid-flight surfaces as `\"cancelled\"` too.\n */\nexport async function runBatchItem<TInput, TOptions, TResult extends BaseResult>(\n  params: RunBatchItemParams<TInput, TOptions, TResult>,\n): Promise<BatchItemResult<TResult>> {\n  const { index, input, executable, signal } = params;\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", attempts: 0 };\n  }\n\n  const retryConfig = resolveRetryConfig({ retry: params.retry }, undefined);\n  const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);\n\n  let lastResult: TResult | undefined;\n  let lastError: unknown;\n  let attemptsMade = 0;\n\n  for (let attempt = 1; attempt <= totalAttempts; attempt++) {\n    if (signal?.aborted) {\n      return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n    }\n\n    attemptsMade = attempt;\n\n    try {\n      const result = await executable.execute(input, { signal } as TOptions);\n      lastResult = result;\n\n      if (!result.error) {\n        return { index, status: \"completed\", result, attempts: attempt };\n      }\n\n      lastError = result.error;\n    } catch (error) {\n      if (isAbortError(error)) {\n        return { index, status: \"cancelled\", result: lastResult, attempts: attempt };\n      }\n\n      lastError = error;\n    }\n\n    const canRetry =\n      attempt < totalAttempts &&\n      (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true);\n\n    if (!canRetry) {\n      break;\n    }\n\n    retryConfig.onRetry?.(attempt + 1, lastError);\n\n    const delay = resolveBackoff(attempt, retryConfig.backoff);\n    if (delay > 0) {\n      await sleep(delay, signal);\n    }\n  }\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n  }\n\n  return {\n    index,\n    status: \"failed\",\n    result: lastResult,\n    error: toAIError(lastError),\n    attempts: attemptsMade,\n  };\n}\n"],"mappings":";;;;;;;;;;AA0BA,SAAS,MAAM,IAAY,QAAgD;CACzE,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ,oBAAoB,SAAS,OAAO;GAC5C,QAAQ;EACV,GAAG,EAAE;EAEL,MAAM,gBAAsB;GAC1B,aAAa,KAAK;GAClB,QAAQ;EACV;EAEA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC3D,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,eAAsB,aACpB,QACmC;CACnC,MAAM,EAAE,OAAO,OAAO,YAAY,WAAW;CAE7C,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,UAAU;CAAE;CAGnD,MAAM,cAAc,mBAAmB,EAAE,OAAO,OAAO,MAAM,GAAG,MAAS;CACzE,MAAM,gBAAgB,KAAK,IAAI,GAAG,YAAY,YAAY,CAAC;CAE3D,IAAI;CACJ,IAAI;CACJ,IAAI,eAAe;CAEnB,KAAK,IAAI,UAAU,GAAG,WAAW,eAAe,WAAW;EACzD,IAAI,QAAQ,SACV,OAAO;GAAE;GAAO,QAAQ;GAAa,QAAQ;GAAY,UAAU;EAAa;EAGlF,eAAe;EAEf,IAAI;GACF,MAAM,SAAS,MAAM,WAAW,QAAQ,OAAO,EAAE,OAAO,CAAa;GACrE,aAAa;GAEb,IAAI,CAAC,OAAO,OACV,OAAO;IAAE;IAAO,QAAQ;IAAa;IAAQ,UAAU;GAAQ;GAGjE,YAAY,OAAO;EACrB,SAAS,OAAO;GACd,IAAI,aAAa,KAAK,GACpB,OAAO;IAAE;IAAO,QAAQ;IAAa,QAAQ;IAAY,UAAU;GAAQ;GAG7E,YAAY;EACd;EAMA,IAAI,EAHF,UAAU,kBACT,YAAY,UAAU,YAAY,QAAQ,WAAW,OAAO,MAAM,QAAQ,QAG3E;EAGF,YAAY,UAAU,UAAU,GAAG,SAAS;EAE5C,MAAM,QAAQ,eAAe,SAAS,YAAY,OAAO;EACzD,IAAI,QAAQ,GACV,MAAM,MAAM,OAAO,MAAM;CAE7B;CAEA,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,QAAQ;EAAY,UAAU;CAAa;CAGlF,OAAO;EACL;EACA,QAAQ;EACR,QAAQ;EACR,OAAO,UAAU,SAAS;EAC1B,UAAU;CACZ;AACF"}

package/esm/batch/run-with-concurrency.mjs

@@ -0,0 +1,39 @@
+//#region ../@warlock.js/ai/src/batch/run-with-concurrency.ts
+/**
+* Run an async `worker` over every index `0..total-1` with at most
+* `limit` workers in flight at any moment, preserving nothing about
+* completion order (the worker is responsible for recording results
+* positionally). Resolves once every index has settled.
+*
+* A fixed pool of `limit` runners each pull the next unclaimed index
+* from a shared cursor — this keeps exactly `limit` items in flight
+* even when item durations vary wildly, unlike fixed-size chunking
+* which stalls a chunk on its slowest member.
+*
+* `limit` is clamped to `[1, total]`: a non-positive limit runs fully
+* serially, a limit larger than `total` simply starts every item.
+* `total === 0` resolves immediately.
+*
+* The worker must never reject — it owns its own try/catch and records
+* outcomes. A rejection here would abort sibling runners, which is not
+* the batch contract (one item's failure never cancels another's).
+*/
+async function runWithConcurrency(total, limit, worker) {
+	if (total <= 0) return;
+	const poolSize = Math.max(1, Math.min(limit, total));
+	let cursor = 0;
+	const runner = async () => {
+		while (cursor < total) {
+			const index = cursor;
+			cursor += 1;
+			await worker(index);
+		}
+	};
+	const pool = [];
+	for (let slot = 0; slot < poolSize; slot++) pool.push(runner());
+	await Promise.all(pool);
+}
+
+//#endregion
+export { runWithConcurrency };
+//# sourceMappingURL=run-with-concurrency.mjs.map

package/esm/batch/run-with-concurrency.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-concurrency.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/run-with-concurrency.ts"],"sourcesContent":["/**\n * Run an async `worker` over every index `0..total-1` with at most\n * `limit` workers in flight at any moment, preserving nothing about\n * completion order (the worker is responsible for recording results\n * positionally). Resolves once every index has settled.\n *\n * A fixed pool of `limit` runners each pull the next unclaimed index\n * from a shared cursor — this keeps exactly `limit` items in flight\n * even when item durations vary wildly, unlike fixed-size chunking\n * which stalls a chunk on its slowest member.\n *\n * `limit` is clamped to `[1, total]`: a non-positive limit runs fully\n * serially, a limit larger than `total` simply starts every item.\n * `total === 0` resolves immediately.\n *\n * The worker must never reject — it owns its own try/catch and records\n * outcomes. A rejection here would abort sibling runners, which is not\n * the batch contract (one item's failure never cancels another's).\n */\nexport async function runWithConcurrency(\n  total: number,\n  limit: number,\n  worker: (index: number) => Promise<void>,\n): Promise<void> {\n  if (total <= 0) {\n    return;\n  }\n\n  const poolSize = Math.max(1, Math.min(limit, total));\n  let cursor = 0;\n\n  const runner = async (): Promise<void> => {\n    while (cursor < total) {\n      const index = cursor;\n      cursor += 1;\n      await worker(index);\n    }\n  };\n\n  const pool: Promise<void>[] = [];\n  for (let slot = 0; slot < poolSize; slot++) {\n    pool.push(runner());\n  }\n\n  await Promise.all(pool);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,eAAsB,mBACpB,OACA,OACA,QACe;CACf,IAAI,SAAS,GACX;CAGF,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,CAAC;CACnD,IAAI,SAAS;CAEb,MAAM,SAAS,YAA2B;EACxC,OAAO,SAAS,OAAO;GACrB,MAAM,QAAQ;GACd,UAAU;GACV,MAAM,OAAO,KAAK;EACpB;CACF;CAEA,MAAM,OAAwB,CAAC;CAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,UAAU,QAClC,KAAK,KAAK,OAAO,CAAC;CAGpB,MAAM,QAAQ,IAAI,IAAI;AACxB"}

package/esm/checkpoint/index.d.mts

@@ -0,0 +1,3 @@
+import { memory } from "./memory.mjs";
+import { PgCheckpointOptions, pg } from "./pg.mjs";
+import { RedisCheckpointOptions, redis } from "./redis.mjs";

package/esm/checkpoint/memory.d.mts

@@ -0,0 +1,21 @@
+import { CheckpointStore } from "../contracts/orchestrator/checkpoint-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/checkpoint/memory.d.ts
+/**
+ * Create an in-memory {@link CheckpointStore}. Zero-config — no client,
+ * no connection. Suitable for dev, tests, and single-process apps that
+ * don't need resume across restarts.
+ *
+ * @example
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const orchestrator = ai.orchestrator({
+ *   name: "support",
+ *   intents: { ... },
+ *   checkpointStore: ai.checkpoint.memory(),
+ * });
+ */
+declare function memory(): CheckpointStore;
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.d.mts.map

package/esm/checkpoint/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/memory.ts"],"mappings":";;;;;AAmKA;;;;AAAyC;;;;;;;;iBAAzB,MAAA,IAAU,eAAe"}

package/esm/checkpoint/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/memory.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\n\n/**\n * Composite key for the in-memory session index — one bucket per\n * `(orchestratorName, sessionId)` pair. The separator can't appear in\n * the segments in practice (names are identifiers, sessionIds are\n * dev-owned opaque strings), so a simple join is collision-safe enough\n * for an in-process store.\n */\nfunction bucketKey(orchestratorName: string, sessionId: string): string {\n  return `${orchestratorName}\u0000${sessionId}`;\n}\n\n/**\n * In-memory {@link CheckpointStore} — append-only session checkpoints\n * held in a process-local `Map`, never persisted to disk.\n *\n * Owns: the per-session bucket of {@link CheckpointRecord} rows and the\n * \"latest turn wins\" load semantics. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps that don't need\n * resume across restarts. Reach for `ai.checkpoint.pg()` /\n * `ai.checkpoint.redis()` (Phase 2) when durability matters.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemoryCheckpointStore implements CheckpointStore {\n  /** Per-session append-only row buckets, keyed by `(orchestratorName, sessionId)`. */\n  private readonly sessions = new Map<string, CheckpointRecord[]>();\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no rows. Rows are appended in\n   * turn order, so the last element is the latest — no scan needed.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const rows = this.sessions.get(bucketKey(orchestratorName, sessionId));\n\n    if (!rows || rows.length === 0) {\n      return undefined;\n    }\n\n    return rows[rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session bucket. Append-only — an\n   * existing `turn_index` is never overwritten; a fresh row is pushed.\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const key = bucketKey(record.orchestrator_name, record.session_id);\n    const rows = this.sessions.get(key);\n\n    if (rows) {\n      rows.push(record);\n\n      return;\n    }\n\n    this.sessions.set(key, [record]);\n  }\n\n  /**\n   * Drop every row for a session, ending it.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    this.sessions.delete(bucketKey(orchestratorName, sessionId));\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the latest row of each bucket so the\n   * authoritative `session_id` is returned even if the key encoding\n   * ever changes.\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const sessionIds: string[] = [];\n\n    for (const rows of this.sessions.values()) {\n      const latest = rows[rows.length - 1];\n\n      if (!latest || latest.orchestrator_name !== orchestratorName) {\n        continue;\n      }\n\n      if (prefix !== undefined && !latest.session_id.startsWith(prefix)) {\n        continue;\n      }\n\n      sessionIds.push(latest.session_id);\n    }\n\n    return sessionIds;\n  }\n\n  /**\n   * Drop every row for a session whose `turn_index` is strictly below\n   * `keepBeforeTurnIndex`, enforcing the `keepSnapshots` retention bound\n   * (§4 Phase 6, Q20). Rebuilds the bucket in place with the surviving\n   * tail; an emptied bucket is removed so `list()` no longer reports the\n   * session.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepBeforeTurnIndex: number,\n  ): Promise<void> {\n    const key = bucketKey(orchestratorName, sessionId);\n    const rows = this.sessions.get(key);\n\n    if (!rows) {\n      return;\n    }\n\n    const kept = rows.filter((row) => row.turn_index >= keepBeforeTurnIndex);\n\n    if (kept.length === 0) {\n      this.sessions.delete(key);\n\n      return;\n    }\n\n    if (kept.length !== rows.length) {\n      this.sessions.set(key, kept);\n    }\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link CheckpointStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need resume across restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   checkpointStore: ai.checkpoint.memory(),\n * });\n */\nexport function memory(): CheckpointStore {\n  return new MemoryCheckpointStore();\n}\n"],"mappings":";;;;;;;;AAYA,SAAS,UAAU,kBAA0B,WAA2B;CACtE,OAAO,GAAG,iBAAiB,GAAG;AAChC;;;;;;;;;;;;;;AAeA,IAAM,wBAAN,MAAuD;;kCAEzB,IAAI,IAAgC;;;;;;;CAOhE,MAAa,KACX,kBACA,WACuC;EACvC,MAAM,OAAO,KAAK,SAAS,IAAI,UAAU,kBAAkB,SAAS,CAAC;EAErE,IAAI,CAAC,QAAQ,KAAK,WAAW,GAC3B;EAGF,OAAO,KAAK,KAAK,SAAS;CAC5B;;;;;CAMA,MAAa,KAAK,QAAyC;EACzD,MAAM,MAAM,UAAU,OAAO,mBAAmB,OAAO,UAAU;EACjE,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,MAAM;GACR,KAAK,KAAK,MAAM;GAEhB;EACF;EAEA,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;CACjC;;;;CAKA,MAAa,OACX,kBACA,WACe;EACf,KAAK,SAAS,OAAO,UAAU,kBAAkB,SAAS,CAAC;CAC7D;;;;;;;CAQA,MAAa,KACX,kBACA,QACmB;EACnB,MAAM,aAAuB,CAAC;EAE9B,KAAK,MAAM,QAAQ,KAAK,SAAS,OAAO,GAAG;GACzC,MAAM,SAAS,KAAK,KAAK,SAAS;GAElC,IAAI,CAAC,UAAU,OAAO,sBAAsB,kBAC1C;GAGF,IAAI,WAAW,UAAa,CAAC,OAAO,WAAW,WAAW,MAAM,GAC9D;GAGF,WAAW,KAAK,OAAO,UAAU;EACnC;EAEA,OAAO;CACT;;;;;;;;CASA,MAAa,MACX,kBACA,WACA,qBACe;EACf,MAAM,MAAM,UAAU,kBAAkB,SAAS;EACjD,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,CAAC,MACH;EAGF,MAAM,OAAO,KAAK,QAAQ,QAAQ,IAAI,cAAc,mBAAmB;EAEvE,IAAI,KAAK,WAAW,GAAG;GACrB,KAAK,SAAS,OAAO,GAAG;GAExB;EACF;EAEA,IAAI,KAAK,WAAW,KAAK,QACvB,KAAK,SAAS,IAAI,KAAK,IAAI;CAE/B;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,SAAgB,SAA0B;CACxC,OAAO,IAAI,sBAAsB;AACnC"}

package/esm/checkpoint/pg.d.mts

@@ -0,0 +1,37 @@
+import { PgClientLike } from "../contracts/orchestrator/snapshot-store.contract.mjs";
+import { CheckpointStore } from "../contracts/orchestrator/checkpoint-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/checkpoint/pg.d.ts
+/**
+ * Options for the Postgres {@link CheckpointStore} (orchestrator.md §8.3).
+ *
+ * The dev owns the connection — `@warlock.js/ai` takes no peer dep on
+ * `pg` and never opens or closes the client. A single `pg.Pool` can
+ * back both the cache and the orchestrator stores.
+ */
+type PgCheckpointOptions = {
+  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */client: PgClientLike; /** Backing table name. Defaults to `warlock_orchestrator_sessions` (§8.6). Must be a safe SQL identifier. */
+  table?: string; /** Idle-row TTL in seconds. When set, rows older than the TTL are eligible for cleanup on prune. */
+  ttl?: number;
+};
+/**
+ * Create a Postgres-backed {@link CheckpointStore} (orchestrator.md
+ * §8.3). The dev installs `pg` and passes a `pg.Pool` / `pg.Client` —
+ * `@warlock.js/ai` never imports `pg`. Run {@link CheckpointStore.schema}
+ * through your migration tool once before use; the store never
+ * auto-migrates.
+ *
+ * @example
+ * import { Pool } from "pg";
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = ai.checkpoint.pg({ client: pool });
+ *
+ * // Once, via your migration tooling:
+ * // await pool.query(store.schema());
+ */
+declare function pg(options: PgCheckpointOptions): CheckpointStore;
+//#endregion
+export { PgCheckpointOptions, pg };
+//# sourceMappingURL=pg.d.mts.map

package/esm/checkpoint/pg.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/pg.ts"],"mappings":";;;;;;AAaA;;;;;KAAY,mBAAA;EAIV,yFAFA,MAAA,EAAQ,YAAY,EAIjB;EAFH,KAAA,WAyWc;EAvWd,GAAA;AAAA;;;;;;AAuW+D;;;;;;;;;;;;iBAAjD,EAAA,CAAG,OAAA,EAAS,mBAAA,GAAsB,eAAe"}

package/esm/checkpoint/pg.mjs

@@ -0,0 +1,265 @@
+//#region ../@warlock.js/ai/src/checkpoint/pg.ts
+/**
+* Default backing table — matches the §8.6 reference DDL verbatim so a
+* stock migration provisions the store with no extra config.
+*/
+const DEFAULT_TABLE = "warlock_orchestrator_sessions";
+/**
+* Allowed characters in a Postgres identifier (table name). The table
+* name is interpolated into DDL/DML, so anything outside this
+* conservative ASCII subset is rejected — interpolating an arbitrary
+* string would be a SQL-injection footgun (mirrors `PgCacheDriver`).
+*/
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Coerce a Postgres `INTEGER` column back to a number. `pg` hands back
+* `INTEGER` as a JS number already, but some pool wrappers surface it
+* as a string — normalize defensively so `turn_index` arithmetic and
+* the latest-turn ordering never compare strings.
+*/
+function toNumber(value) {
+	return typeof value === "string" ? Number(value) : value;
+}
+/**
+* Coerce a nullable Postgres integer column to `number | null`.
+*/
+function toNullableNumber(value) {
+	return value === null || value === void 0 ? null : toNumber(value);
+}
+/**
+* Coerce a Postgres timestamp/text column to an ISO string. `pg`
+* returns `TIMESTAMPTZ` as a `Date`; normalize to the ISO wire shape
+* the {@link CheckpointRecord} contract declares.
+*/
+function toIso(value) {
+	if (value instanceof Date) return value.toISOString();
+	return value;
+}
+/**
+* Coerce a nullable Postgres timestamp column to `string | null`.
+*/
+function toNullableIso(value) {
+	if (value === null || value === void 0) return null;
+	return toIso(value);
+}
+/**
+* Decode the single `last_route` `TEXT` column back to the
+* `string | string[] | null` shape the contract declares. A fan-out
+* array is written JSON-encoded (it starts with `[`), so a leading `[`
+* is the signal to parse; any other value is a single intent stored
+* verbatim. Symmetric with {@link PgCheckpointStore.serializeRoute}.
+*/
+function deserializeRoute(value) {
+	if (value === null || value === void 0) return null;
+	const route = value;
+	if (route.startsWith("[")) return JSON.parse(route);
+	return route;
+}
+/**
+* Map a raw DB row to a {@link CheckpointRecord}. Column names match
+* the §8.6 DDL 1:1, so this is a typed projection plus the defensive
+* coercions a heterogeneous `pg` client population needs.
+*/
+function rowToRecord(row) {
+	const state = typeof row.state === "string" ? JSON.parse(row.state) : row.state;
+	return {
+		orchestrator_name: row.orchestrator_name,
+		session_id: row.session_id,
+		turn_index: toNumber(row.turn_index),
+		state,
+		last_route: deserializeRoute(row.last_route),
+		signature: row.signature,
+		version: row.version ?? null,
+		summarized_through: toNullableNumber(row.summarized_through),
+		lock_acquired_at: toNullableIso(row.lock_acquired_at),
+		lock_expires_at: toNullableIso(row.lock_expires_at),
+		saved_at: toIso(row.saved_at)
+	};
+}
+/**
+* Postgres-backed {@link CheckpointStore} (orchestrator.md §8.2, §8.6).
+*
+* Owns: append-only checkpoint rows keyed by
+* `(orchestrator_name, session_id, turn_index)`, the "latest turn wins"
+* load, the §8.6 DDL via {@link PgCheckpointStore.schema}, and the
+* §4-Phase-6 retention prune. Does NOT own: the connection lifecycle
+* (the dev passes a client and keeps it), schema migration (the dev
+* runs `schema()` through their own tool — never auto-migrated, §8.5),
+* or the `keepSnapshots` policy itself (that lives on the orchestrator
+* config; the orchestrator passes the resolved bound into
+* {@link PgCheckpointStore.prune}).
+*
+* Front it with the {@link pg} factory — callers never `new` it.
+*/
+var PgCheckpointStore = class {
+	constructor(options) {
+		if (!options || typeof options.client?.query !== "function") throw new TypeError("ai.checkpoint.pg requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
+		const table = options.table ?? DEFAULT_TABLE;
+		if (!SAFE_IDENTIFIER.test(table)) throw new TypeError(`ai.checkpoint.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		this.client = options.client;
+		this.table = table;
+		this.ttl = options.ttl;
+	}
+	/**
+	* Return the latest checkpoint (highest `turn_index`) for a session,
+	* or `undefined` when the store has never seen it. The `(name,
+	* session_id, turn_index DESC)` lookup index keeps this O(1) on the
+	* latest row (§8.6).
+	*/
+	async load(orchestratorName, sessionId) {
+		const { rows } = await this.client.query(`SELECT * FROM ${this.table}
+       WHERE orchestrator_name = $1 AND session_id = $2
+       ORDER BY turn_index DESC
+       LIMIT 1`, [orchestratorName, sessionId]);
+		if (rows.length === 0) return;
+		return rowToRecord(rows[0]);
+	}
+	/**
+	* Persist a fresh checkpoint row. Append-only — an existing
+	* `turn_index` is never overwritten; the PK collision surfaces as a
+	* Postgres error rather than a silent clobber (§4 Phase 6, Q15).
+	*/
+	async save(record) {
+		await this.client.query(`INSERT INTO ${this.table} (
+         orchestrator_name, session_id, turn_index, state, last_route,
+         signature, version, summarized_through, lock_acquired_at,
+         lock_expires_at, saved_at
+       )
+       VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, $8, $9, $10, $11)`, [
+			record.orchestrator_name,
+			record.session_id,
+			record.turn_index,
+			JSON.stringify(record.state),
+			this.serializeRoute(record.last_route),
+			record.signature,
+			record.version,
+			record.summarized_through,
+			record.lock_acquired_at,
+			record.lock_expires_at,
+			record.saved_at
+		]);
+	}
+	/**
+	* Delete every checkpoint row for a session, ending it.
+	*/
+	async delete(orchestratorName, sessionId) {
+		await this.client.query(`DELETE FROM ${this.table}
+       WHERE orchestrator_name = $1 AND session_id = $2`, [orchestratorName, sessionId]);
+	}
+	/**
+	* List the distinct session ids known for an orchestrator, optionally
+	* filtered by a session-id prefix. Used by the production boot-drain
+	* loop (§9.3). The prefix is matched with `LIKE`, escaping the SQL
+	* wildcards so a literal `_` or `%` in the prefix is not treated as a
+	* pattern.
+	*/
+	async list(orchestratorName, prefix) {
+		if (prefix === void 0) {
+			const { rows } = await this.client.query(`SELECT DISTINCT session_id FROM ${this.table}
+         WHERE orchestrator_name = $1`, [orchestratorName]);
+			return rows.map((row) => row.session_id);
+		}
+		const escaped = prefix.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+		const { rows } = await this.client.query(`SELECT DISTINCT session_id FROM ${this.table}
+       WHERE orchestrator_name = $1 AND session_id LIKE $2 ESCAPE '\\'`, [orchestratorName, `${escaped}%`]);
+		return rows.map((row) => row.session_id);
+	}
+	/**
+	* Prune retained turns for a session down to the most recent
+	* `keepSnapshots` rows (orchestrator.md §4 Phase 6 / §15.2). Deletes
+	* every row with `turn_index < (max_turn_index - keepSnapshots)`. The
+	* orchestrator calls this synchronously after a successful
+	* {@link save} when `keepSnapshots` is a finite number; `"all"`
+	* retention skips the call entirely. Additive to the
+	* {@link CheckpointStore} contract — the contract carries no prune
+	* hook, so the policy stays on the orchestrator and the store only
+	* executes the bounded delete.
+	*/
+	async prune(orchestratorName, sessionId, keepSnapshots) {
+		if (!Number.isFinite(keepSnapshots) || keepSnapshots < 0) return;
+		await this.client.query(`DELETE FROM ${this.table}
+       WHERE orchestrator_name = $1
+         AND session_id = $2
+         AND turn_index < (
+           SELECT max(turn_index) - $3
+           FROM ${this.table}
+           WHERE orchestrator_name = $1 AND session_id = $2
+         )`, [
+			orchestratorName,
+			sessionId,
+			keepSnapshots
+		]);
+	}
+	/**
+	* Return the §8.6 reference DDL for this store's backing table,
+	* interpolating the configured table name. The dev runs it through
+	* their migration tool — the framework never auto-migrates (§8.5).
+	*
+	* @example
+	* await pool.query(store.schema());
+	*/
+	schema() {
+		return [
+			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
+			`  orchestrator_name    TEXT NOT NULL,`,
+			`  session_id           TEXT NOT NULL,`,
+			`  turn_index           INTEGER NOT NULL,`,
+			`  state                JSONB NOT NULL,`,
+			`  last_route           TEXT,`,
+			`  signature            TEXT NOT NULL,`,
+			`  version              TEXT,`,
+			`  summarized_through   INTEGER,`,
+			`  lock_acquired_at     TIMESTAMPTZ,`,
+			`  lock_expires_at      TIMESTAMPTZ,`,
+			`  saved_at             TIMESTAMPTZ NOT NULL DEFAULT now(),`,
+			`  PRIMARY KEY (orchestrator_name, session_id, turn_index)`,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at`,
+			`  ON ${this.table} (saved_at);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_lookup`,
+			`  ON ${this.table} (orchestrator_name, session_id, turn_index DESC);`
+		].join("\n");
+	}
+	/**
+	* Set the idle-row TTL (§8.2). Stored for prune-time cleanup; the
+	* store never opens a background timer.
+	*/
+	setOptions(options) {
+		this.ttl = options.ttl;
+	}
+	/**
+	* `last_route` rides a single `TEXT` column. A fan-out array is
+	* JSON-encoded so it round-trips through one column without a schema
+	* change; a single intent (an identifier — never starts with `[`) is
+	* stored verbatim. {@link deserializeRoute} reverses this on load.
+	*/
+	serializeRoute(route) {
+		if (route === null) return null;
+		if (Array.isArray(route)) return JSON.stringify(route);
+		return route;
+	}
+};
+/**
+* Create a Postgres-backed {@link CheckpointStore} (orchestrator.md
+* §8.3). The dev installs `pg` and passes a `pg.Pool` / `pg.Client` —
+* `@warlock.js/ai` never imports `pg`. Run {@link CheckpointStore.schema}
+* through your migration tool once before use; the store never
+* auto-migrates.
+*
+* @example
+* import { Pool } from "pg";
+* import { ai } from "@warlock.js/ai";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+* const store = ai.checkpoint.pg({ client: pool });
+*
+* // Once, via your migration tooling:
+* // await pool.query(store.schema());
+*/
+function pg(options) {
+	return new PgCheckpointStore(options);
+}
+
+//#endregion
+export { pg };
+//# sourceMappingURL=pg.mjs.map

package/esm/checkpoint/pg.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/pg.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { PgClientLike } from \"../contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Options for the Postgres {@link CheckpointStore} (orchestrator.md §8.3).\n *\n * The dev owns the connection — `@warlock.js/ai` takes no peer dep on\n * `pg` and never opens or closes the client. A single `pg.Pool` can\n * back both the cache and the orchestrator stores.\n */\nexport type PgCheckpointOptions = {\n  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */\n  client: PgClientLike;\n  /** Backing table name. Defaults to `warlock_orchestrator_sessions` (§8.6). Must be a safe SQL identifier. */\n  table?: string;\n  /** Idle-row TTL in seconds. When set, rows older than the TTL are eligible for cleanup on prune. */\n  ttl?: number;\n};\n\n/**\n * Default backing table — matches the §8.6 reference DDL verbatim so a\n * stock migration provisions the store with no extra config.\n */\nconst DEFAULT_TABLE = \"warlock_orchestrator_sessions\";\n\n/**\n * Allowed characters in a Postgres identifier (table name). The table\n * name is interpolated into DDL/DML, so anything outside this\n * conservative ASCII subset is rejected — interpolating an arbitrary\n * string would be a SQL-injection footgun (mirrors `PgCacheDriver`).\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Coerce a Postgres `INTEGER` column back to a number. `pg` hands back\n * `INTEGER` as a JS number already, but some pool wrappers surface it\n * as a string — normalize defensively so `turn_index` arithmetic and\n * the latest-turn ordering never compare strings.\n */\nfunction toNumber(value: unknown): number {\n  return typeof value === \"string\" ? Number(value) : (value as number);\n}\n\n/**\n * Coerce a nullable Postgres integer column to `number | null`.\n */\nfunction toNullableNumber(value: unknown): number | null {\n  return value === null || value === undefined ? null : toNumber(value);\n}\n\n/**\n * Coerce a Postgres timestamp/text column to an ISO string. `pg`\n * returns `TIMESTAMPTZ` as a `Date`; normalize to the ISO wire shape\n * the {@link CheckpointRecord} contract declares.\n */\nfunction toIso(value: unknown): string {\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  return value as string;\n}\n\n/**\n * Coerce a nullable Postgres timestamp column to `string | null`.\n */\nfunction toNullableIso(value: unknown): string | null {\n  if (value === null || value === undefined) {\n    return null;\n  }\n\n  return toIso(value);\n}\n\n/**\n * Decode the single `last_route` `TEXT` column back to the\n * `string | string[] | null` shape the contract declares. A fan-out\n * array is written JSON-encoded (it starts with `[`), so a leading `[`\n * is the signal to parse; any other value is a single intent stored\n * verbatim. Symmetric with {@link PgCheckpointStore.serializeRoute}.\n */\nfunction deserializeRoute(value: unknown): string | string[] | null {\n  if (value === null || value === undefined) {\n    return null;\n  }\n\n  const route = value as string;\n\n  if (route.startsWith(\"[\")) {\n    return JSON.parse(route) as string[];\n  }\n\n  return route;\n}\n\n/**\n * Map a raw DB row to a {@link CheckpointRecord}. Column names match\n * the §8.6 DDL 1:1, so this is a typed projection plus the defensive\n * coercions a heterogeneous `pg` client population needs.\n */\nfunction rowToRecord(row: Record<string, unknown>): CheckpointRecord {\n  const state =\n    typeof row.state === \"string\" ? JSON.parse(row.state) : row.state;\n\n  return {\n    orchestrator_name: row.orchestrator_name as string,\n    session_id: row.session_id as string,\n    turn_index: toNumber(row.turn_index),\n    state,\n    last_route: deserializeRoute(row.last_route),\n    signature: row.signature as string,\n    version: (row.version as string | null) ?? null,\n    summarized_through: toNullableNumber(row.summarized_through),\n    lock_acquired_at: toNullableIso(row.lock_acquired_at),\n    lock_expires_at: toNullableIso(row.lock_expires_at),\n    saved_at: toIso(row.saved_at),\n  };\n}\n\n/**\n * Postgres-backed {@link CheckpointStore} (orchestrator.md §8.2, §8.6).\n *\n * Owns: append-only checkpoint rows keyed by\n * `(orchestrator_name, session_id, turn_index)`, the \"latest turn wins\"\n * load, the §8.6 DDL via {@link PgCheckpointStore.schema}, and the\n * §4-Phase-6 retention prune. Does NOT own: the connection lifecycle\n * (the dev passes a client and keeps it), schema migration (the dev\n * runs `schema()` through their own tool — never auto-migrated, §8.5),\n * or the `keepSnapshots` policy itself (that lives on the orchestrator\n * config; the orchestrator passes the resolved bound into\n * {@link PgCheckpointStore.prune}).\n *\n * Front it with the {@link pg} factory — callers never `new` it.\n */\nclass PgCheckpointStore implements CheckpointStore {\n  /** The dev-supplied `pg.Pool` / `pg.Client`. Never closed by the store. */\n  private readonly client: PgClientLike;\n\n  /** Validated backing table name, safe to interpolate into SQL. */\n  private readonly table: string;\n\n  /** Idle-row TTL in seconds, or `undefined` for no expiry. */\n  private ttl?: number;\n\n  public constructor(options: PgCheckpointOptions) {\n    if (!options || typeof options.client?.query !== \"function\") {\n      throw new TypeError(\n        \"ai.checkpoint.pg requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n      );\n    }\n\n    const table = options.table ?? DEFAULT_TABLE;\n\n    if (!SAFE_IDENTIFIER.test(table)) {\n      throw new TypeError(\n        `ai.checkpoint.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    this.client = options.client;\n    this.table = table;\n    this.ttl = options.ttl;\n  }\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the store has never seen it. The `(name,\n   * session_id, turn_index DESC)` lookup index keeps this O(1) on the\n   * latest row (§8.6).\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const { rows } = await this.client.query(\n      `SELECT * FROM ${this.table}\n       WHERE orchestrator_name = $1 AND session_id = $2\n       ORDER BY turn_index DESC\n       LIMIT 1`,\n      [orchestratorName, sessionId],\n    );\n\n    if (rows.length === 0) {\n      return undefined;\n    }\n\n    return rowToRecord(rows[0] as Record<string, unknown>);\n  }\n\n  /**\n   * Persist a fresh checkpoint row. Append-only — an existing\n   * `turn_index` is never overwritten; the PK collision surfaces as a\n   * Postgres error rather than a silent clobber (§4 Phase 6, Q15).\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    await this.client.query(\n      `INSERT INTO ${this.table} (\n         orchestrator_name, session_id, turn_index, state, last_route,\n         signature, version, summarized_through, lock_acquired_at,\n         lock_expires_at, saved_at\n       )\n       VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, $8, $9, $10, $11)`,\n      [\n        record.orchestrator_name,\n        record.session_id,\n        record.turn_index,\n        JSON.stringify(record.state),\n        this.serializeRoute(record.last_route),\n        record.signature,\n        record.version,\n        record.summarized_through,\n        record.lock_acquired_at,\n        record.lock_expires_at,\n        record.saved_at,\n      ],\n    );\n  }\n\n  /**\n   * Delete every checkpoint row for a session, ending it.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    await this.client.query(\n      `DELETE FROM ${this.table}\n       WHERE orchestrator_name = $1 AND session_id = $2`,\n      [orchestratorName, sessionId],\n    );\n  }\n\n  /**\n   * List the distinct session ids known for an orchestrator, optionally\n   * filtered by a session-id prefix. Used by the production boot-drain\n   * loop (§9.3). The prefix is matched with `LIKE`, escaping the SQL\n   * wildcards so a literal `_` or `%` in the prefix is not treated as a\n   * pattern.\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    if (prefix === undefined) {\n      const { rows } = await this.client.query(\n        `SELECT DISTINCT session_id FROM ${this.table}\n         WHERE orchestrator_name = $1`,\n        [orchestratorName],\n      );\n\n      return rows.map((row) => (row as Record<string, unknown>).session_id as string);\n    }\n\n    const escaped = prefix\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    const { rows } = await this.client.query(\n      `SELECT DISTINCT session_id FROM ${this.table}\n       WHERE orchestrator_name = $1 AND session_id LIKE $2 ESCAPE '\\\\'`,\n      [orchestratorName, `${escaped}%`],\n    );\n\n    return rows.map((row) => (row as Record<string, unknown>).session_id as string);\n  }\n\n  /**\n   * Prune retained turns for a session down to the most recent\n   * `keepSnapshots` rows (orchestrator.md §4 Phase 6 / §15.2). Deletes\n   * every row with `turn_index < (max_turn_index - keepSnapshots)`. The\n   * orchestrator calls this synchronously after a successful\n   * {@link save} when `keepSnapshots` is a finite number; `\"all\"`\n   * retention skips the call entirely. Additive to the\n   * {@link CheckpointStore} contract — the contract carries no prune\n   * hook, so the policy stays on the orchestrator and the store only\n   * executes the bounded delete.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepSnapshots: number,\n  ): Promise<void> {\n    if (!Number.isFinite(keepSnapshots) || keepSnapshots < 0) {\n      return;\n    }\n\n    await this.client.query(\n      `DELETE FROM ${this.table}\n       WHERE orchestrator_name = $1\n         AND session_id = $2\n         AND turn_index < (\n           SELECT max(turn_index) - $3\n           FROM ${this.table}\n           WHERE orchestrator_name = $1 AND session_id = $2\n         )`,\n      [orchestratorName, sessionId, keepSnapshots],\n    );\n  }\n\n  /**\n   * Return the §8.6 reference DDL for this store's backing table,\n   * interpolating the configured table name. The dev runs it through\n   * their migration tool — the framework never auto-migrates (§8.5).\n   *\n   * @example\n   * await pool.query(store.schema());\n   */\n  public schema(): string {\n    return [\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  orchestrator_name    TEXT NOT NULL,`,\n      `  session_id           TEXT NOT NULL,`,\n      `  turn_index           INTEGER NOT NULL,`,\n      `  state                JSONB NOT NULL,`,\n      `  last_route           TEXT,`,\n      `  signature            TEXT NOT NULL,`,\n      `  version              TEXT,`,\n      `  summarized_through   INTEGER,`,\n      `  lock_acquired_at     TIMESTAMPTZ,`,\n      `  lock_expires_at      TIMESTAMPTZ,`,\n      `  saved_at             TIMESTAMPTZ NOT NULL DEFAULT now(),`,\n      `  PRIMARY KEY (orchestrator_name, session_id, turn_index)`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at`,\n      `  ON ${this.table} (saved_at);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_lookup`,\n      `  ON ${this.table} (orchestrator_name, session_id, turn_index DESC);`,\n    ].join(\"\\n\");\n  }\n\n  /**\n   * Set the idle-row TTL (§8.2). Stored for prune-time cleanup; the\n   * store never opens a background timer.\n   */\n  public setOptions(options: { ttl?: number }): void {\n    this.ttl = options.ttl;\n  }\n\n  /**\n   * `last_route` rides a single `TEXT` column. A fan-out array is\n   * JSON-encoded so it round-trips through one column without a schema\n   * change; a single intent (an identifier — never starts with `[`) is\n   * stored verbatim. {@link deserializeRoute} reverses this on load.\n   */\n  private serializeRoute(route: string | string[] | null): string | null {\n    if (route === null) {\n      return null;\n    }\n\n    if (Array.isArray(route)) {\n      return JSON.stringify(route);\n    }\n\n    return route;\n  }\n}\n\n/**\n * Create a Postgres-backed {@link CheckpointStore} (orchestrator.md\n * §8.3). The dev installs `pg` and passes a `pg.Pool` / `pg.Client` —\n * `@warlock.js/ai` never imports `pg`. Run {@link CheckpointStore.schema}\n * through your migration tool once before use; the store never\n * auto-migrates.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n * const store = ai.checkpoint.pg({ client: pool });\n *\n * // Once, via your migration tooling:\n * // await pool.query(store.schema());\n */\nexport function pg(options: PgCheckpointOptions): CheckpointStore {\n  return new PgCheckpointStore(options);\n}\n"],"mappings":"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"}

package/esm/checkpoint/redis.d.mts

@@ -0,0 +1,39 @@
+import { RedisClientLike } from "../contracts/orchestrator/snapshot-store.contract.mjs";
+import { CheckpointStore } from "../contracts/orchestrator/checkpoint-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/checkpoint/redis.d.ts
+/**
+ * Options for the Redis {@link CheckpointStore} (orchestrator.md §8.3).
+ *
+ * The dev owns the connection — `@warlock.js/ai` takes no peer dep on
+ * `redis` and never opens or closes the client.
+ */
+type RedisCheckpointOptions = {
+  /** An already-connected `redis` client — anything matching {@link RedisClientLike}. */client: RedisClientLike;
+  /**
+   * Key prefix for every key this store writes. Lets one Redis database
+   * back multiple stores without collision. Defaults to
+   * `warlock:orchestrator`.
+   */
+  prefix?: string; /** Idle-key TTL in seconds. When set, every written key expires after the TTL. */
+  ttl?: number;
+};
+/**
+ * Create a Redis-backed {@link CheckpointStore} (orchestrator.md §8.3).
+ * The dev installs `redis` and passes a connected client —
+ * `@warlock.js/ai` never imports `redis`. {@link CheckpointStore.schema}
+ * returns an empty string; Redis needs no migration.
+ *
+ * @example
+ * import { createClient } from "redis";
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const client = createClient();
+ * await client.connect();
+ *
+ * const store = ai.checkpoint.redis({ client });
+ */
+declare function redis(options: RedisCheckpointOptions): CheckpointStore;
+//#endregion
+export { RedisCheckpointOptions, redis };
+//# sourceMappingURL=redis.d.mts.map

package/esm/checkpoint/redis.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/redis.ts"],"mappings":";;;;;;AAYA;;;;KAAY,sBAAA;EAEF,uFAAR,MAAA,EAAQ,eAAe;EAQvB;;AAAG;AA0UL;;EA5UE,MAAA,WA4UqE;EA1UrE,GAAA;AAAA;;;AA0UqE;;;;;;;;;;;;;iBAAvD,KAAA,CAAM,OAAA,EAAS,sBAAA,GAAyB,eAAe"}