@warlock.js/core 4.3.0 → 4.5.0

package/esm/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/checkpoint/redis.mjs

@@ -0,0 +1,200 @@
+//#region ../@warlock.js/ai/src/checkpoint/redis.ts
+/**
+* Default key prefix — namespaces the store's keys inside a shared
+* Redis database.
+*/
+const DEFAULT_PREFIX = "warlock:orchestrator";
+/**
+* Redis-backed {@link CheckpointStore} (orchestrator.md §8.2).
+*
+* Owns: the per-session append-only document, a per-orchestrator
+* session-id index (so {@link RedisCheckpointStore.list} works without
+* `KEYS`/`SCAN`), the "latest turn wins" load, and the §4-Phase-6
+* retention prune. Does NOT own: durability guarantees beyond Redis's
+* own, the connection lifecycle (the dev passes a client), or the
+* `keepSnapshots` policy (that lives on the orchestrator config).
+*
+* Because {@link RedisClientLike} is intentionally minimal (`get` /
+* `set` / `del` only — §8.4), the store models a session as a single
+* JSON document rather than one Redis key per turn. This keeps every
+* operation a single round-trip and avoids depending on key scanning,
+* at the cost of read-modify-write on `save`. Callers must serialize
+* traffic per `sessionId` anyway (§17 "two turns racing"), so the
+* read-modify-write is safe under that contract.
+*
+* Front it with the {@link redis} factory — callers never `new` it.
+*/
+var RedisCheckpointStore = class {
+	constructor(options) {
+		if (!options || typeof options.client?.get !== "function" || typeof options.client?.set !== "function" || typeof options.client?.del !== "function") throw new TypeError("ai.checkpoint.redis requires a 'client' option implementing { get, set, del } — pass a connected redis client.");
+		this.client = options.client;
+		this.prefix = options.prefix ?? DEFAULT_PREFIX;
+		this.ttl = options.ttl;
+	}
+	/**
+	* Return the latest checkpoint (highest `turn_index`) for a session,
+	* or `undefined` when the session has no document. Rows are appended
+	* in turn order, so the last element is the latest.
+	*/
+	async load(orchestratorName, sessionId) {
+		const document = await this.readSession(orchestratorName, sessionId);
+		if (!document || document.rows.length === 0) return;
+		return document.rows[document.rows.length - 1];
+	}
+	/**
+	* Append a checkpoint row to its session document, creating the
+	* document and indexing the session id on first write. Append-only —
+	* an existing `turn_index` is never overwritten; a fresh row is
+	* pushed (§4 Phase 6, Q15).
+	*/
+	async save(record) {
+		const { orchestrator_name, session_id } = record;
+		const document = await this.readSession(orchestrator_name, session_id) ?? { rows: [] };
+		document.rows.push(record);
+		await this.writeSession(orchestrator_name, session_id, document);
+		await this.indexSession(orchestrator_name, session_id);
+	}
+	/**
+	* Drop a session document and de-index its session id.
+	*/
+	async delete(orchestratorName, sessionId) {
+		await this.client.del(this.sessionKey(orchestratorName, sessionId));
+		await this.deindexSession(orchestratorName, sessionId);
+	}
+	/**
+	* List the session ids known for an orchestrator, optionally filtered
+	* by a session-id prefix. Reads the self-maintained index document
+	* (§9.3 boot drain).
+	*/
+	async list(orchestratorName, prefix) {
+		const index = await this.readIndex(orchestratorName);
+		if (prefix === void 0) return [...index.sessionIds];
+		return index.sessionIds.filter((sessionId) => sessionId.startsWith(prefix));
+	}
+	/**
+	* Prune retained turns for a session down to the most recent
+	* `keepSnapshots` rows (orchestrator.md §4 Phase 6 / §15.2). Drops
+	* every row whose `turn_index` is below `(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. Additive to the
+	* {@link CheckpointStore} contract — the policy stays on the
+	* orchestrator and the store only executes the bounded trim.
+	*/
+	async prune(orchestratorName, sessionId, keepSnapshots) {
+		if (!Number.isFinite(keepSnapshots) || keepSnapshots < 0) return;
+		const document = await this.readSession(orchestratorName, sessionId);
+		if (!document || document.rows.length === 0) return;
+		const threshold = document.rows[document.rows.length - 1].turn_index - keepSnapshots;
+		const kept = document.rows.filter((row) => row.turn_index >= threshold);
+		if (kept.length === document.rows.length) return;
+		await this.writeSession(orchestratorName, sessionId, { rows: kept });
+	}
+	/**
+	* The Redis store has no relational table — there is nothing to
+	* migrate. Returns an empty string so callers can treat `schema()`
+	* uniformly across drivers (mirrors the memory store).
+	*/
+	schema() {
+		return "";
+	}
+	/**
+	* Set the idle-key TTL (§8.2). Applied on every subsequent write; the
+	* store never opens a background timer.
+	*/
+	setOptions(options) {
+		this.ttl = options.ttl;
+	}
+	/**
+	* Read and parse a session document, or `undefined` when the key is
+	* absent.
+	*/
+	async readSession(orchestratorName, sessionId) {
+		const raw = await this.client.get(this.sessionKey(orchestratorName, sessionId));
+		if (raw === null) return;
+		return JSON.parse(raw);
+	}
+	/**
+	* Serialize and persist a session document, honoring the configured
+	* idle TTL when set.
+	*/
+	async writeSession(orchestratorName, sessionId, document) {
+		await this.write(this.sessionKey(orchestratorName, sessionId), JSON.stringify(document));
+	}
+	/**
+	* Read and parse the per-orchestrator index document, defaulting to an
+	* empty index when absent.
+	*/
+	async readIndex(orchestratorName) {
+		const raw = await this.client.get(this.indexKey(orchestratorName));
+		if (raw === null) return { sessionIds: [] };
+		return JSON.parse(raw);
+	}
+	/**
+	* Add a session id to the per-orchestrator index, no-op when already
+	* present.
+	*/
+	async indexSession(orchestratorName, sessionId) {
+		const index = await this.readIndex(orchestratorName);
+		if (index.sessionIds.includes(sessionId)) return;
+		index.sessionIds.push(sessionId);
+		await this.write(this.indexKey(orchestratorName), JSON.stringify(index));
+	}
+	/**
+	* Remove a session id from the per-orchestrator index, no-op when
+	* absent.
+	*/
+	async deindexSession(orchestratorName, sessionId) {
+		const index = await this.readIndex(orchestratorName);
+		const next = index.sessionIds.filter((id) => id !== sessionId);
+		if (next.length === index.sessionIds.length) return;
+		await this.write(this.indexKey(orchestratorName), JSON.stringify({ sessionIds: next }));
+	}
+	/**
+	* Write a key, attaching the `EX` expiry option when an idle TTL is
+	* configured. The TTL flows through {@link RedisClientLike.set}'s
+	* variadic args as node-redis's `{ EX }` option object.
+	*/
+	async write(key, value) {
+		if (this.ttl !== void 0 && this.ttl > 0) {
+			await this.client.set(key, value, { EX: this.ttl });
+			return;
+		}
+		await this.client.set(key, value);
+	}
+	/**
+	* Key for a session document — `<prefix>:session:<name>:<sessionId>`.
+	*/
+	sessionKey(orchestratorName, sessionId) {
+		return `${this.prefix}:session:${orchestratorName}:${sessionId}`;
+	}
+	/**
+	* Key for a per-orchestrator session-id index —
+	* `<prefix>:index:<name>`.
+	*/
+	indexKey(orchestratorName) {
+		return `${this.prefix}:index:${orchestratorName}`;
+	}
+};
+/**
+* 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 });
+*/
+function redis(options) {
+	return new RedisCheckpointStore(options);
+}
+
+//#endregion
+export { redis };
+//# sourceMappingURL=redis.mjs.map

package/esm/ai/src/checkpoint/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/checkpoint/redis.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { RedisClientLike } from \"../contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Options for the Redis {@link CheckpointStore} (orchestrator.md §8.3).\n *\n * The dev owns the connection — `@warlock.js/ai` takes no peer dep on\n * `redis` and never opens or closes the client.\n */\nexport type RedisCheckpointOptions = {\n  /** An already-connected `redis` client — anything matching {@link RedisClientLike}. */\n  client: RedisClientLike;\n  /**\n   * Key prefix for every key this store writes. Lets one Redis database\n   * back multiple stores without collision. Defaults to\n   * `warlock:orchestrator`.\n   */\n  prefix?: string;\n  /** Idle-key TTL in seconds. When set, every written key expires after the TTL. */\n  ttl?: number;\n};\n\n/**\n * Default key prefix — namespaces the store's keys inside a shared\n * Redis database.\n */\nconst DEFAULT_PREFIX = \"warlock:orchestrator\";\n\n/**\n * Per-session document persisted under one Redis key: the append-only\n * list of {@link CheckpointRecord} rows in turn order, mirroring the\n * Postgres append-only PK shape (§8.6) inside a single JSON value so\n * the store needs only `get`/`set`/`del` from {@link RedisClientLike}.\n */\ntype SessionDocument = {\n  rows: CheckpointRecord[];\n};\n\n/**\n * Per-orchestrator index document: the set of live session ids. Kept as\n * a JSON array because {@link RedisClientLike} exposes no `keys` / `scan`\n * — enumeration for the §9.3 boot drain must be self-maintained.\n */\ntype IndexDocument = {\n  sessionIds: string[];\n};\n\n/**\n * Redis-backed {@link CheckpointStore} (orchestrator.md §8.2).\n *\n * Owns: the per-session append-only document, a per-orchestrator\n * session-id index (so {@link RedisCheckpointStore.list} works without\n * `KEYS`/`SCAN`), the \"latest turn wins\" load, and the §4-Phase-6\n * retention prune. Does NOT own: durability guarantees beyond Redis's\n * own, the connection lifecycle (the dev passes a client), or the\n * `keepSnapshots` policy (that lives on the orchestrator config).\n *\n * Because {@link RedisClientLike} is intentionally minimal (`get` /\n * `set` / `del` only — §8.4), the store models a session as a single\n * JSON document rather than one Redis key per turn. This keeps every\n * operation a single round-trip and avoids depending on key scanning,\n * at the cost of read-modify-write on `save`. Callers must serialize\n * traffic per `sessionId` anyway (§17 \"two turns racing\"), so the\n * read-modify-write is safe under that contract.\n *\n * Front it with the {@link redis} factory — callers never `new` it.\n */\nclass RedisCheckpointStore implements CheckpointStore {\n  /** The dev-supplied redis client. Never disconnected by the store. */\n  private readonly client: RedisClientLike;\n\n  /** Key prefix namespacing every key this store writes. */\n  private readonly prefix: string;\n\n  /** Idle-key TTL in seconds, or `undefined` for no expiry. */\n  private ttl?: number;\n\n  public constructor(options: RedisCheckpointOptions) {\n    if (\n      !options ||\n      typeof options.client?.get !== \"function\" ||\n      typeof options.client?.set !== \"function\" ||\n      typeof options.client?.del !== \"function\"\n    ) {\n      throw new TypeError(\n        \"ai.checkpoint.redis requires a 'client' option implementing { get, set, del } — pass a connected redis client.\",\n      );\n    }\n\n    this.client = options.client;\n    this.prefix = options.prefix ?? DEFAULT_PREFIX;\n    this.ttl = options.ttl;\n  }\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no document. Rows are appended\n   * in turn order, so the last element is the latest.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const document = await this.readSession(orchestratorName, sessionId);\n\n    if (!document || document.rows.length === 0) {\n      return undefined;\n    }\n\n    return document.rows[document.rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session document, creating the\n   * document and indexing the session id on first write. Append-only —\n   * an existing `turn_index` is never overwritten; a fresh row is\n   * pushed (§4 Phase 6, Q15).\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const { orchestrator_name, session_id } = record;\n\n    const document =\n      (await this.readSession(orchestrator_name, session_id)) ?? { rows: [] };\n\n    document.rows.push(record);\n\n    await this.writeSession(orchestrator_name, session_id, document);\n    await this.indexSession(orchestrator_name, session_id);\n  }\n\n  /**\n   * Drop a session document and de-index its session id.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    await this.client.del(this.sessionKey(orchestratorName, sessionId));\n    await this.deindexSession(orchestratorName, sessionId);\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the self-maintained index document\n   * (§9.3 boot drain).\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const index = await this.readIndex(orchestratorName);\n\n    if (prefix === undefined) {\n      return [...index.sessionIds];\n    }\n\n    return index.sessionIds.filter((sessionId) =>\n      sessionId.startsWith(prefix),\n    );\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). Drops\n   * every row whose `turn_index` is below `(max_turn_index -\n   * keepSnapshots)`. The orchestrator calls this synchronously after a\n   * successful {@link save} when `keepSnapshots` is a finite number;\n   * `\"all\"` retention skips the call. Additive to the\n   * {@link CheckpointStore} contract — the policy stays on the\n   * orchestrator and the store only executes the bounded trim.\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    const document = await this.readSession(orchestratorName, sessionId);\n\n    if (!document || document.rows.length === 0) {\n      return;\n    }\n\n    const maxTurnIndex = document.rows[document.rows.length - 1].turn_index;\n    const threshold = maxTurnIndex - keepSnapshots;\n\n    const kept = document.rows.filter((row) => row.turn_index >= threshold);\n\n    if (kept.length === document.rows.length) {\n      return;\n    }\n\n    await this.writeSession(orchestratorName, sessionId, { rows: kept });\n  }\n\n  /**\n   * The Redis store has no relational table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers (mirrors the memory store).\n   */\n  public schema(): string {\n    return \"\";\n  }\n\n  /**\n   * Set the idle-key TTL (§8.2). Applied on every subsequent write; 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   * Read and parse a session document, or `undefined` when the key is\n   * absent.\n   */\n  private async readSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<SessionDocument | undefined> {\n    const raw = await this.client.get(\n      this.sessionKey(orchestratorName, sessionId),\n    );\n\n    if (raw === null) {\n      return undefined;\n    }\n\n    return JSON.parse(raw) as SessionDocument;\n  }\n\n  /**\n   * Serialize and persist a session document, honoring the configured\n   * idle TTL when set.\n   */\n  private async writeSession(\n    orchestratorName: string,\n    sessionId: string,\n    document: SessionDocument,\n  ): Promise<void> {\n    await this.write(\n      this.sessionKey(orchestratorName, sessionId),\n      JSON.stringify(document),\n    );\n  }\n\n  /**\n   * Read and parse the per-orchestrator index document, defaulting to an\n   * empty index when absent.\n   */\n  private async readIndex(orchestratorName: string): Promise<IndexDocument> {\n    const raw = await this.client.get(this.indexKey(orchestratorName));\n\n    if (raw === null) {\n      return { sessionIds: [] };\n    }\n\n    return JSON.parse(raw) as IndexDocument;\n  }\n\n  /**\n   * Add a session id to the per-orchestrator index, no-op when already\n   * present.\n   */\n  private async indexSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    const index = await this.readIndex(orchestratorName);\n\n    if (index.sessionIds.includes(sessionId)) {\n      return;\n    }\n\n    index.sessionIds.push(sessionId);\n\n    await this.write(this.indexKey(orchestratorName), JSON.stringify(index));\n  }\n\n  /**\n   * Remove a session id from the per-orchestrator index, no-op when\n   * absent.\n   */\n  private async deindexSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    const index = await this.readIndex(orchestratorName);\n    const next = index.sessionIds.filter((id) => id !== sessionId);\n\n    if (next.length === index.sessionIds.length) {\n      return;\n    }\n\n    await this.write(\n      this.indexKey(orchestratorName),\n      JSON.stringify({ sessionIds: next }),\n    );\n  }\n\n  /**\n   * Write a key, attaching the `EX` expiry option when an idle TTL is\n   * configured. The TTL flows through {@link RedisClientLike.set}'s\n   * variadic args as node-redis's `{ EX }` option object.\n   */\n  private async write(key: string, value: string): Promise<void> {\n    if (this.ttl !== undefined && this.ttl > 0) {\n      await this.client.set(key, value, { EX: this.ttl });\n\n      return;\n    }\n\n    await this.client.set(key, value);\n  }\n\n  /**\n   * Key for a session document — `<prefix>:session:<name>:<sessionId>`.\n   */\n  private sessionKey(orchestratorName: string, sessionId: string): string {\n    return `${this.prefix}:session:${orchestratorName}:${sessionId}`;\n  }\n\n  /**\n   * Key for a per-orchestrator session-id index —\n   * `<prefix>:index:<name>`.\n   */\n  private indexKey(orchestratorName: string): string {\n    return `${this.prefix}:index:${orchestratorName}`;\n  }\n}\n\n/**\n * Create a Redis-backed {@link CheckpointStore} (orchestrator.md §8.3).\n * The dev installs `redis` and passes a connected client —\n * `@warlock.js/ai` never imports `redis`. {@link CheckpointStore.schema}\n * returns an empty string; Redis needs no migration.\n *\n * @example\n * import { createClient } from \"redis\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const client = createClient();\n * await client.connect();\n *\n * const store = ai.checkpoint.redis({ client });\n */\nexport function redis(options: RedisCheckpointOptions): CheckpointStore {\n  return new RedisCheckpointStore(options);\n}\n"],"mappings":"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"}