@warlock.js/core 4.8.0 → 4.8.2

package/esm/ai/src/checkpoint/pg.mjs

@@ -1,265 +0,0 @@
-//#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

@@ -1 +0,0 @@
-{"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

@@ -1,200 +0,0 @@
-//#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

@@ -1 +0,0 @@
-{"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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"}

package/esm/ai/src/config.mjs

@@ -1,59 +0,0 @@
-//#region ../@warlock.js/ai/src/config.ts
-const aiConfig = {};
-const configListeners = [];
-/**
-* Set or extend process-wide AI configuration. Merges over existing
-* values — fields not present in `partial` keep whatever was set
-* before (or stay unset). Call once at app boot, before constructing
-* any agent / supervisor / middleware that should pick up the
-* defaults.
-*
-* Returns the merged config so callers can verify what landed.
-*
-* @example
-* import { cache } from "@warlock.js/cache";
-* import { ai } from "@warlock.js/ai";
-*
-* ai.config({ defaultStore: cache.driver("redis", { client }) });
-*/
-function setAIConfig(partial) {
-	Object.assign(aiConfig, partial);
-	const snapshot = { ...aiConfig };
-	for (const listener of configListeners) try {
-		listener(snapshot);
-	} catch {}
-	return snapshot;
-}
-/**
-* Resolve the effective `@warlock.js/cache` driver for a cache-backed
-* consumer that didn't receive an explicit one. Returns the global
-* `defaultStore` if set, otherwise `undefined`. The semantic-cache
-* middleware treats `undefined` as fatal and throws. Snapshot
-* persistence no longer consults this — it resolves through
-* {@link resolveDefaultSnapshotStore}.
-*/
-function resolveDefaultStore() {
-	return aiConfig.defaultStore;
-}
-/**
-* Resolve the global default {@link CheckpointStore} for an
-* orchestrator that didn't receive an explicit `checkpointStore`.
-* Returns `undefined` when none is configured — the orchestrator
-* factory decides whether that's fatal.
-*/
-function resolveDefaultCheckpointStore() {
-	return aiConfig.defaultCheckpointStore;
-}
-/**
-* Resolve the global default {@link SnapshotStore} for an orchestrator
-* that didn't receive an explicit `snapshotStore`. Returns `undefined`
-* when none is configured — the orchestrator factory decides whether
-* that's fatal (it is, when `iterate: true`).
-*/
-function resolveDefaultSnapshotStore() {
-	return aiConfig.defaultSnapshotStore;
-}
-
-//#endregion
-export { resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
-//# sourceMappingURL=config.mjs.map

package/esm/ai/src/config.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n *\n * **Augmentable.** Declared as an `interface` (not a `type` alias) so\n * observability/tooling packages can attach their own opaque config slot\n * via declaration merging WITHOUT core importing them — keeping core\n * dependency-free. For example `@warlock.js/ai-panoptic` adds a\n * `panoptic?` field:\n *\n * ```ts\n * declare module \"@warlock.js/ai\" {\n *   interface AIConfig {\n *     panoptic?: PanopticConfig;\n *   }\n * }\n * ```\n *\n * `setAIConfig` stores the whole object via `Object.assign`, so any\n * augmented field is preserved even though core never reads it.\n */\nexport interface AIConfig {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/** A listener notified after every `setAIConfig` merge. */\ntype ConfigListener = (config: AIConfig) => void;\n\nconst configListeners: ConfigListener[] = [];\n\n/**\n * Subscribe to config changes. The listener fires after every\n * {@link setAIConfig} merge with a fresh snapshot of the full config —\n * the seam observability/tooling packages use to react when their\n * augmented slot (e.g. `panoptic`) is set, WITHOUT core importing them.\n *\n * Mirrors the dependency-inversion of the `Observer` registry: core\n * exposes the structural hook; the tool subscribes on its side-effect\n * import. To also catch config that was applied *before* the subscription,\n * read {@link getAIConfig} once right after subscribing.\n *\n * @example\n * import { onConfigApplied, getAIConfig } from \"@warlock.js/ai\";\n * onConfigApplied((config) => applyPanopticConfig(config.panoptic));\n * applyPanopticConfig(getAIConfig().panoptic); // catch pre-set config\n */\nexport function onConfigApplied(listener: ConfigListener): void {\n  configListeners.push(listener);\n}\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  const snapshot = { ...aiConfig };\n\n  // Notify subscribers (e.g. panoptic) after the merge. Errors are\n  // swallowed so a misbehaving listener never breaks config application,\n  // mirroring the observer / onUsage swallow-on-throw discipline.\n  for (const listener of configListeners) {\n    try {\n      listener(snapshot);\n    } catch {\n      // intentionally ignored\n    }\n  }\n\n  return snapshot;\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAiGA,MAAM,WAAqB,CAAC;AAK5B,MAAM,kBAAoC,CAAC;;;;;;;;;;;;;;;;AAqC3C,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,MAAM,WAAW,EAAE,GAAG,SAAS;CAK/B,KAAK,MAAM,YAAY,iBACrB,IAAI;EACF,SAAS,QAAQ;CACnB,QAAQ,CAER;CAGF,OAAO;AACT;;;;;;;;;AAmBA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}

package/esm/ai/src/contracts/end.type.mjs

@@ -1,47 +0,0 @@
-//#region ../@warlock.js/ai/src/contracts/end.type.ts
-/**
-* Framework-global termination sentinel. Emitted by any primitive
-* whose control flow is routed through JSON-serializable strings —
-* supervisor (router agent's `next`, deterministic `route` callback),
-* future planner (plan steps), future orchestrator (session
-* directive), any future primitive that needs to say "stop" across a
-* wire that can't carry `null`.
-*
-* **Why one shared literal.** Consumers learn one word. Cross-
-* primitive pipes — a planner feeding a supervisor, a supervisor
-* nested as a tool inside an orchestrator — can pass the sentinel
-* through without translation.
-*
-* **Why this specific string.** Brand-prefixed (`__warlock:`) so it
-* can't collide with a realistic user-chosen intent / step / route
-* key (`"end"`, `"done"`, `"stop"` are all valid user keys).
-* Underscore-surrounded so it stands out in logs and snapshots.
-* JSON-safe so a router agent emits it verbatim.
-*
-* **Not used by every primitive.** Workflow's `nextStep` returns
-* `null` to end — a callback-level mechanism that predates this
-* sentinel. Workflows keep `null`; the sentinel is for primitives
-* whose "end" must survive a JSON boundary.
-*
-* @example
-* import { END } from "@warlock.js/ai";
-*
-* // Supervisor route callback
-* ai.supervisor({
-*   intents: { writer, critic },
-*   route: (ctx) => (ctx.iteration >= 5 ? END : "writer"),
-* });
-*
-* // Router agent output schema
-* const router = ai.agent({
-*   model,
-*   output: z.object({
-*     next: z.union([z.string(), z.array(z.string()), z.literal(END)]),
-*   }),
-* });
-*/
-const END = "__warlock:end__";
-
-//#endregion
-export { END };
-//# sourceMappingURL=end.type.mjs.map