@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/state/init.js

@@ -7,9 +7,12 @@
  * Postgres advisory lock. A run with no pending migration runs no DDL, thus it
  * takes no lock on a Cortex table.
  */
+import { errorOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
 import { Kysely, PostgresDialect, sql } from "kysely";
 import { Migrator } from "kysely/migration";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { presentFirst } from "../lib/present.js";
 import { cortexMigrations } from "./migrations/index.js";
 /**
  * The longest time that a migration statement waits for a lock. An `ALTER TABLE`
@@ -37,7 +40,7 @@ export async function initCortexState(pool, injected) {
             migrationLockTableName: "cortex_migration_lock",
             // Without a schema, the migrator finds its tables in any schema, thus a
             // test schema would see the tables of the other test schemas.
-            migrationTableSchema: rows[0].schema,
+            migrationTableSchema: presentFirst(rows, "the current schema row").schema,
         });
         const { error, results } = await migrator.migrateToLatest();
         for (const result of results ?? []) {
@@ -45,7 +48,7 @@ export async function initCortexState(pool, injected) {
                 logger.info("migration applied", { migration: result.migrationName });
         }
         if (error !== undefined) {
-            throw error instanceof Error ? error : new Error(`cortex state migration failed: ${String(error)}`);
+            throw errorOf(error) ?? new Error(`cortex state migration failed: ${textOf(error)}`);
         }
     }
     finally {

package/dist/state/migrations/20260927120000_baseline.js

@@ -6,6 +6,8 @@
  * that an earlier harness created with its boot-time DDL: it brings that
  * database to this schema, and the migrator records it.
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { CompiledQuery, sql } from "kysely";
 import { backfillAiSdkMessageEnvelopes } from "../../memory/message-backfill.js";
 // No ';' may appear anywhere in this text, comments included: it is executed by
@@ -635,7 +637,7 @@ export function baseline(logger) {
                 await sql.raw("CREATE EXTENSION IF NOT EXISTS vector").execute(db);
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
+                const msg = errorMessageOf(err) ?? textOf(err);
                 throw new Error(`Cortex requires the pgvector extension. ` +
                     `CREATE EXTENSION IF NOT EXISTS vector failed: ${msg}. ` +
                     `Ask platform-infra to enable pgvector on the RDS parameter group, ` +

package/dist/state/migrations/20261026120000_add_the_edit_intents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Record the intent of each `edit_file` call inside a durable step, keyed by
+ * the step. A rerun of the step after the write, before its checkpoint, then
+ * gives back the result of the edit and does not apply it a second time.
+ */
+import type { Migration } from "kysely/migration";
+export declare const addTheEditIntents: Migration;

package/dist/state/migrations/20261026120000_add_the_edit_intents.js

@@ -0,0 +1,21 @@
+/**
+ * Record the intent of each `edit_file` call inside a durable step, keyed by
+ * the step. A rerun of the step after the write, before its checkpoint, then
+ * gives back the result of the edit and does not apply it a second time.
+ */
+import { sql } from "kysely";
+export const addTheEditIntents = {
+    async up(db) {
+        await sql `CREATE TABLE IF NOT EXISTS cortex_edit_intents (
+  step_key     TEXT PRIMARY KEY,
+  analysis_id  TEXT NOT NULL,
+  path         TEXT NOT NULL,
+  hash_before  TEXT NOT NULL,
+  hash_after   TEXT NOT NULL,
+  result       JSONB NOT NULL,
+  call_record  JSONB NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_edit_intents_analysis ON cortex_edit_intents (analysis_id)`.execute(db);
+    },
+};

package/dist/state/migrations/20261027120000_record_the_applied_memory_edits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Record the key of each `update_working_memory` call that a durable step
+ * applied, in the transaction of the edit. A rerun of the step after the edit,
+ * before its checkpoint, then finds its key and changes nothing.
+ */
+import type { Migration } from "kysely/migration";
+export declare const recordTheAppliedMemoryEdits: Migration;

package/dist/state/migrations/20261027120000_record_the_applied_memory_edits.js

@@ -0,0 +1,16 @@
+/**
+ * Record the key of each `update_working_memory` call that a durable step
+ * applied, in the transaction of the edit. A rerun of the step after the edit,
+ * before its checkpoint, then finds its key and changes nothing.
+ */
+import { sql } from "kysely";
+export const recordTheAppliedMemoryEdits = {
+    async up(db) {
+        await sql `CREATE TABLE IF NOT EXISTS cortex_applied_memory_edits (
+  call_key     TEXT PRIMARY KEY,
+  analysis_id  TEXT NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_applied_memory_edits_analysis ON cortex_applied_memory_edits (analysis_id)`.execute(db);
+    },
+};

package/dist/state/migrations/20261027120100_store_the_authoring_results.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Store the result of each authoring call that a durable step landed, keyed by
+ * the report thread and the step. The result lands in the transaction of the
+ * document. A rerun of the step after the landing, before its checkpoint, then
+ * gives the stored result and does not apply the operation a second time.
+ */
+import type { Migration } from "kysely/migration";
+export declare const storeTheAuthoringResults: Migration;

package/dist/state/migrations/20261027120100_store_the_authoring_results.js

@@ -0,0 +1,20 @@
+/**
+ * Store the result of each authoring call that a durable step landed, keyed by
+ * the report thread and the step. The result lands in the transaction of the
+ * document. A rerun of the step after the landing, before its checkpoint, then
+ * gives the stored result and does not apply the operation a second time.
+ */
+import { sql } from "kysely";
+export const storeTheAuthoringResults = {
+    async up(db) {
+        await sql `CREATE TABLE IF NOT EXISTS cortex_authoring_results (
+  thread_id    TEXT NOT NULL,
+  call_key     TEXT NOT NULL,
+  analysis_id  TEXT NOT NULL,
+  result       JSONB NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (thread_id, call_key)
+)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_authoring_results_analysis ON cortex_authoring_results (analysis_id)`.execute(db);
+    },
+};

package/dist/state/migrations/20261027120200_key_the_groups_of_a_turn.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Key each group of a chat turn on its first row. A turn workflow writes each
+ * round in a step, and a step that runs again after its commit finds the key
+ * and stores nothing, thus no row of a turn lands two times.
+ */
+import type { Migration } from "kysely/migration";
+export declare const keyTheGroupsOfATurn: Migration;

package/dist/state/migrations/20261027120200_key_the_groups_of_a_turn.js

@@ -0,0 +1,12 @@
+/**
+ * Key each group of a chat turn on its first row. A turn workflow writes each
+ * round in a step, and a step that runs again after its commit finds the key
+ * and stores nothing, thus no row of a turn lands two times.
+ */
+import { sql } from "kysely";
+export const keyTheGroupsOfATurn = {
+    async up(db) {
+        await sql `ALTER TABLE messages ADD COLUMN IF NOT EXISTS round_key TEXT`.execute(db);
+        await sql `CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_round_key ON messages(thread_id, round_key) WHERE round_key IS NOT NULL`.execute(db);
+    },
+};

package/dist/state/migrations/20261027120300_mark_the_active_turn_of_a_thread.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mark the turn that runs on a thread. The open of a turn claims the thread,
+ * and the end of the turn releases it, thus a second turn on the same thread
+ * is refused before it writes a row.
+ */
+import type { Migration } from "kysely/migration";
+export declare const markTheActiveTurnOfAThread: Migration;

package/dist/state/migrations/20261027120300_mark_the_active_turn_of_a_thread.js

@@ -0,0 +1,11 @@
+/**
+ * Mark the turn that runs on a thread. The open of a turn claims the thread,
+ * and the end of the turn releases it, thus a second turn on the same thread
+ * is refused before it writes a row.
+ */
+import { sql } from "kysely";
+export const markTheActiveTurnOfAThread = {
+    async up(db) {
+        await sql `ALTER TABLE cortex_analysis_threads ADD COLUMN IF NOT EXISTS active_turn_id TEXT`.execute(db);
+    },
+};

package/dist/state/migrations/20261028120000_record_the_paused_work.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Record each workflow that waits in a pause. The row is the state that a host
+ * reads when it lists the paused work of an analysis, for example after a
+ * restart, and it names the topic that the resume sends to.
+ */
+import type { Migration } from "kysely/migration";
+export declare const recordThePausedWork: Migration;

package/dist/state/migrations/20261028120000_record_the_paused_work.js

@@ -0,0 +1,25 @@
+/**
+ * Record each workflow that waits in a pause. The row is the state that a host
+ * reads when it lists the paused work of an analysis, for example after a
+ * restart, and it names the topic that the resume sends to.
+ */
+import { sql } from "kysely";
+export const recordThePausedWork = {
+    async up(db) {
+        await sql `CREATE TABLE IF NOT EXISTS cortex_paused_work (
+            workflow_id TEXT PRIMARY KEY,
+            work_id TEXT NOT NULL,
+            work_kind TEXT NOT NULL,
+            analysis_id TEXT NOT NULL,
+            thread_id TEXT,
+            state TEXT NOT NULL,
+            cause JSONB NOT NULL,
+            attempt INTEGER NOT NULL,
+            retry_at TIMESTAMPTZ,
+            topic TEXT NOT NULL,
+            paused_at TIMESTAMPTZ NOT NULL
+        )`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_paused_work_analysis ON cortex_paused_work(analysis_id)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_paused_work_work ON cortex_paused_work(work_id)`.execute(db);
+    },
+};

package/dist/state/migrations/20261028120100_end_the_suspended_runs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * End the rows of the suspended state. A suspended run ended `CANCELLED` in the
+ * engine, and no code can resume it, thus its row reads as `failed` with its
+ * reason. An analysis has no suspended state any more, because paused work
+ * records itself in `cortex_paused_work`.
+ */
+import type { Migration } from "kysely/migration";
+export declare const endTheSuspendedRuns: Migration;

package/dist/state/migrations/20261028120100_end_the_suspended_runs.js

@@ -0,0 +1,13 @@
+/**
+ * End the rows of the suspended state. A suspended run ended `CANCELLED` in the
+ * engine, and no code can resume it, thus its row reads as `failed` with its
+ * reason. An analysis has no suspended state any more, because paused work
+ * records itself in `cortex_paused_work`.
+ */
+import { sql } from "kysely";
+export const endTheSuspendedRuns = {
+    async up(db) {
+        await sql `UPDATE cortex_runs SET status = 'failed' WHERE status = 'suspended_insufficient_funds'`.execute(db);
+        await sql `UPDATE cortex_analysis_state SET status = 'active' WHERE status = 'suspended_insufficient_funds'`.execute(db);
+    },
+};

package/dist/state/migrations/20261029120000_reference_the_run_mandate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The run ledger keeps a reference to the run credential, not a token: the id
+ * of the mandate, which a realization resolves to a short-lived credential.
+ * The reference has no expiry, because the run does not depend on a clock.
+ */
+import type { Migration } from "kysely/migration";
+export declare const referenceTheRunMandate: Migration;

package/dist/state/migrations/20261029120000_reference_the_run_mandate.js

@@ -0,0 +1,23 @@
+/**
+ * The run ledger keeps a reference to the run credential, not a token: the id
+ * of the mandate, which a realization resolves to a short-lived credential.
+ * The reference has no expiry, because the run does not depend on a clock.
+ */
+import { sql } from "kysely";
+export const referenceTheRunMandate = {
+    async up(db) {
+        // The baseline adds `mandate_jti` again on a database that ran it before, thus the column can stand beside
+        // `mandate_id`. Then it holds no value that `mandate_id` does not.
+        await sql `DO $$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name = 'cortex_runs' AND column_name = 'mandate_jti') THEN
+                IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name = 'cortex_runs' AND column_name = 'mandate_id') THEN
+                    ALTER TABLE cortex_runs DROP COLUMN mandate_jti;
+                ELSE
+                    ALTER TABLE cortex_runs RENAME COLUMN mandate_jti TO mandate_id;
+                END IF;
+            END IF;
+        END $$`.execute(db); // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+        await sql `ALTER TABLE cortex_runs DROP COLUMN IF EXISTS mandate_expires_at`.execute(db); // oss-core-managed-ok: run-mandate ledger
+    },
+};

package/dist/state/migrations/20261029120100_record_the_run_session_of_a_pause.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A pause row of a run or a profile keeps the run session of its workflow. A
+ * resume renews the run credential from it before the work goes on, and a
+ * turn, whose credential comes with the person, keeps none.
+ */
+import type { Migration } from "kysely/migration";
+export declare const recordTheRunSessionOfAPause: Migration;

package/dist/state/migrations/20261029120100_record_the_run_session_of_a_pause.js

@@ -0,0 +1,11 @@
+/**
+ * A pause row of a run or a profile keeps the run session of its workflow. A
+ * resume renews the run credential from it before the work goes on, and a
+ * turn, whose credential comes with the person, keeps none.
+ */
+import { sql } from "kysely";
+export const recordTheRunSessionOfAPause = {
+    async up(db) {
+        await sql `ALTER TABLE cortex_paused_work ADD COLUMN IF NOT EXISTS run_session JSONB`.execute(db);
+    },
+};

package/dist/state/migrations/index.js

@@ -12,6 +12,15 @@ import { indexTheRunsByStart } from "./20261012120000_index_the_runs_by_start.js
 import { indexTheEndedRunsAndTheRecentThreads } from "./20261013120000_index_the_ended_runs_and_the_recent_threads.js";
 import { narrowTheActiveRunIndex } from "./20261013180000_narrow_the_active_run_index.js";
 import { indexThePlansByParentAndTheRunsByPlan } from "./20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.js";
+import { addTheEditIntents } from "./20261026120000_add_the_edit_intents.js";
+import { recordTheAppliedMemoryEdits } from "./20261027120000_record_the_applied_memory_edits.js";
+import { storeTheAuthoringResults } from "./20261027120100_store_the_authoring_results.js";
+import { keyTheGroupsOfATurn } from "./20261027120200_key_the_groups_of_a_turn.js";
+import { markTheActiveTurnOfAThread } from "./20261027120300_mark_the_active_turn_of_a_thread.js";
+import { recordThePausedWork } from "./20261028120000_record_the_paused_work.js";
+import { endTheSuspendedRuns } from "./20261028120100_end_the_suspended_runs.js";
+import { referenceTheRunMandate } from "./20261029120000_reference_the_run_mandate.js";
+import { recordTheRunSessionOfAPause } from "./20261029120100_record_the_run_session_of_a_pause.js";
 export function cortexMigrations(logger) {
     return {
         "20260927120000_baseline": baseline(logger),
@@ -21,5 +30,14 @@ export function cortexMigrations(logger) {
         "20261013120000_index_the_ended_runs_and_the_recent_threads": indexTheEndedRunsAndTheRecentThreads,
         "20261013180000_narrow_the_active_run_index": narrowTheActiveRunIndex,
         "20261014120000_index_the_plans_by_parent_and_the_runs_by_plan": indexThePlansByParentAndTheRunsByPlan,
+        "20261026120000_add_the_edit_intents": addTheEditIntents,
+        "20261027120000_record_the_applied_memory_edits": recordTheAppliedMemoryEdits,
+        "20261027120100_store_the_authoring_results": storeTheAuthoringResults,
+        "20261027120200_key_the_groups_of_a_turn": keyTheGroupsOfATurn,
+        "20261027120300_mark_the_active_turn_of_a_thread": markTheActiveTurnOfAThread,
+        "20261028120000_record_the_paused_work": recordThePausedWork,
+        "20261028120100_end_the_suspended_runs": endTheSuspendedRuns,
+        "20261029120000_reference_the_run_mandate": referenceTheRunMandate,
+        "20261029120100_record_the_run_session_of_a_pause": recordTheRunSessionOfAPause,
     };
 }

package/dist/state/paused-work.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The rows of `cortex_paused_work`: one row for each workflow that waits in a pause. The workflow writes its row
+ * before it waits and deletes it when the wait ends. A stop of the work deletes the rows of the work.
+ */
+import type { ResultAsync } from "neverthrow";
+import type { QueryConfig } from "pg";
+import type { RunSession } from "../auth/types.js";
+import type { PauseCause, WorkKind } from "../contracts/chat-parts.js";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+/** One waiting workflow, as its row records it. */
+export type PauseRecord = {
+    readonly workflowId: string;
+    readonly workId: string;
+    readonly workKind: WorkKind;
+    readonly analysisId: string;
+    readonly threadId?: string;
+    readonly state: "retrying" | "paused";
+    readonly cause: PauseCause;
+    /** The count of timer retries before this wait. */
+    readonly attempt: number;
+    /** ISO 8601. Present for the state `retrying` only. */
+    readonly retryAt?: string;
+    /** The topic that the message of a resume goes to. */
+    readonly topic: string;
+    /** ISO 8601. */
+    readonly pausedAt: string;
+    /** The run session of the workflow, for a run and a profile. A resume renews the run credential from it. */
+    readonly runSession?: RunSession;
+};
+/**
+ * The row-reading surface of the reads: one query whose rows the row schema types. A computed test fake satisfies
+ * it directly, where the row-generic of `Querier` cannot be implemented by a fake that computes its rows.
+ */
+export type PauseRowQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
+};
+/** Write the row of a waiting workflow. A workflow waits in one pause at a time, thus a new pause replaces its row. */
+export declare function recordPause(pool: Querier, record: PauseRecord): ResultAsync<void, DbError>;
+/** Delete the row of a workflow whose wait ended. A second delete changes nothing. */
+export declare function clearPause(pool: Querier, workflowId: string): ResultAsync<void, DbError>;
+/** Delete the rows of workflows that no longer wait, in one statement. */
+export declare function clearPauses(pool: Querier, workflowIds: readonly string[]): ResultAsync<void, DbError>;
+/** Delete the rows of each workflow of the work, for a stop of the work. */
+export declare function clearPausesOfWork(pool: Querier, workId: string): ResultAsync<void, DbError>;
+/** The rows of the paused work of an analysis, the oldest pause first. */
+export declare function queryPausesOfAnalysis(pool: PauseRowQuerier, analysisId: string): ResultAsync<PauseRecord[], DbError>;
+/** The rows of the waiting workflows of one work in an analysis. */
+export declare function queryPausesOfWork(pool: PauseRowQuerier, analysisId: string, workId: string): ResultAsync<PauseRecord[], DbError>;

package/dist/state/paused-work.js

@@ -0,0 +1,105 @@
+/**
+ * The rows of `cortex_paused_work`: one row for each workflow that waits in a pause. The workflow writes its row
+ * before it waits and deletes it when the wait ends. A stop of the work deletes the rows of the work.
+ */
+import { z } from "zod";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+const PauseCauseSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("outage") }),
+    z.object({ kind: z.literal("credential") }),
+    z.object({ kind: z.literal("host"), reason: z.string() }),
+]);
+const PauseRowSchema = z.object({
+    workflow_id: z.string(),
+    work_id: z.string(),
+    work_kind: z.enum(["turn", "run", "profile"]),
+    analysis_id: z.string(),
+    thread_id: z.string().nullable(),
+    state: z.enum(["retrying", "paused"]),
+    cause: PauseCauseSchema,
+    attempt: z.number(),
+    retry_at: z.date().nullable(),
+    topic: z.string(),
+    paused_at: z.date(),
+    run_session: z
+        .object({
+        identity: z.object({ user: z.string() }),
+        scope: z.object({ kind: z.literal("analysis"), analysisId: z.string(), threadId: z.string().optional() }),
+        provenance: z.object({ agentId: z.string(), callPath: z.array(z.string()) }),
+        runFrame: z.object({ runId: z.string(), stepId: z.string().optional() }),
+        // The harness never reads the opaque `auth`: the row holds the JSON that the workflow wrote from its own
+        // `RunSession`, and the realization of the host downcasts it.
+        auth: z.record(z.string(), z.json()),
+    })
+        .nullable(),
+});
+const COLUMNS = "workflow_id, work_id, work_kind, analysis_id, thread_id, state, cause, attempt, retry_at, topic, paused_at, run_session";
+function recordOf(row) {
+    const parsed = PauseRowSchema.parse(row);
+    return {
+        workflowId: parsed.workflow_id,
+        workId: parsed.work_id,
+        workKind: parsed.work_kind,
+        analysisId: parsed.analysis_id,
+        threadId: parsed.thread_id ?? undefined,
+        state: parsed.state,
+        cause: parsed.cause,
+        attempt: parsed.attempt,
+        retryAt: parsed.retry_at?.toISOString(),
+        topic: parsed.topic,
+        pausedAt: parsed.paused_at.toISOString(),
+        runSession: parsed.run_session ?? undefined,
+    };
+}
+/** Write the row of a waiting workflow. A workflow waits in one pause at a time, thus a new pause replaces its row. */
+export function recordPause(pool, record) {
+    return tryMutation("pausedWork.record", () => pool.query(`INSERT INTO cortex_paused_work (${COLUMNS})
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+             ON CONFLICT (workflow_id) DO UPDATE SET
+               work_id = EXCLUDED.work_id, work_kind = EXCLUDED.work_kind, analysis_id = EXCLUDED.analysis_id,
+               thread_id = EXCLUDED.thread_id, state = EXCLUDED.state, cause = EXCLUDED.cause, attempt = EXCLUDED.attempt,
+               retry_at = EXCLUDED.retry_at, topic = EXCLUDED.topic, paused_at = EXCLUDED.paused_at,
+               run_session = EXCLUDED.run_session`, [
+        record.workflowId,
+        record.workId,
+        record.workKind,
+        record.analysisId,
+        record.threadId ?? null,
+        record.state,
+        JSON.stringify(record.cause),
+        record.attempt,
+        record.retryAt ?? null,
+        record.topic,
+        record.pausedAt,
+        record.runSession === undefined ? null : JSON.stringify(record.runSession),
+    ])).map(() => undefined);
+}
+/** Delete the row of a workflow whose wait ended. A second delete changes nothing. */
+export function clearPause(pool, workflowId) {
+    return tryMutation("pausedWork.clear", () => pool.query("DELETE FROM cortex_paused_work WHERE workflow_id = $1", [workflowId])).map(() => undefined);
+}
+/** Delete the rows of workflows that no longer wait, in one statement. */
+export function clearPauses(pool, workflowIds) {
+    return tryMutation("pausedWork.clearMany", () => pool.query("DELETE FROM cortex_paused_work WHERE workflow_id = ANY($1)", [workflowIds])).map(() => undefined);
+}
+/** Delete the rows of each workflow of the work, for a stop of the work. */
+export function clearPausesOfWork(pool, workId) {
+    return tryMutation("pausedWork.clearWork", () => pool.query("DELETE FROM cortex_paused_work WHERE work_id = $1", [workId])).map(() => undefined);
+}
+/** The rows of the paused work of an analysis, the oldest pause first. */
+export function queryPausesOfAnalysis(pool, analysisId) {
+    return tryQuery("pausedWork.ofAnalysis", async () => {
+        const { rows } = await pool.query(`SELECT ${COLUMNS} FROM cortex_paused_work WHERE analysis_id = $1 ORDER BY paused_at, workflow_id`, [analysisId]);
+        return rows.map(recordOf);
+    });
+}
+/** The rows of the waiting workflows of one work in an analysis. */
+export function queryPausesOfWork(pool, analysisId, workId) {
+    return tryQuery("pausedWork.ofWork", async () => {
+        const { rows } = await pool.query(`SELECT ${COLUMNS} FROM cortex_paused_work WHERE analysis_id = $1 AND work_id = $2 ORDER BY workflow_id`, [
+            analysisId,
+            workId,
+        ]);
+        return rows.map(recordOf);
+    });
+}

package/dist/state/plans.d.ts

@@ -3,13 +3,32 @@
  * and analysis-scoped lookup.
  */
 import type { ResultAsync } from "neverthrow";
+import type { QueryConfig } from "pg";
 import { type DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-export interface InsertPlanInput {
+/**
+ * What the plan reads of the pool: one row-reading query over concrete rows.
+ * A real `Pool` and a `Querier`-typed caller satisfy it; a computed test fake
+ * satisfies it directly, where the row-generic `Querier` refuses it.
+ */
+export type PlanRowQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
+};
+/**
+ * `cortex_plans.plan_id` shape contract — `pln-` followed by 8 lowercase hex
+ * chars. The chat trigger (`tools/execute-analysis.ts`) enforces the same regex on
+ * its tool input; `upsertPlan` re-asserts it because it accepts a caller-derived
+ * id rather than minting one. The shape itself is the `PLAN_ID_RE` home in
+ * `contracts/schemas/chat-parts.ts`.
+ */
+export type InsertPlanInput = {
     analysisId: string;
     plan: unknown;
     parentPlanId?: string | null;
-}
+};
 /**
  * Insert a plan and return the generated planId.
  * Validates that parentPlanId (if set) belongs to the same analysis —
@@ -21,13 +40,13 @@ export interface InsertPlanInput {
  * as a query failure and they surface verbatim to the caller.
  */
 export declare function insertPlan(pool: Querier, input: InsertPlanInput): ResultAsync<string, DbError>;
-export interface UpsertPlanInput {
+export type UpsertPlanInput = {
     /** Caller-derived id — must match the `pln-<8hex>` contract. */
     planId: string;
     analysisId: string;
     plan: unknown;
     parentPlanId?: string | null;
-}
+};
 /**
  * Insert a plan under a caller-supplied id, or no-op if that id already exists
  * (`ON CONFLICT (plan_id) DO NOTHING`). Unlike {@link insertPlan}, the id is
@@ -53,9 +72,9 @@ export declare function upsertPlan(pool: Querier, input: UpsertPlanInput): Resul
  */
 export declare function loadPlan(pool: Querier, planId: string, opts: {
     analysisId: string;
-}): ResultAsync<unknown | null, DbError>;
+}): ResultAsync<unknown, DbError>;
 /** A stored plan with its lineage, as {@link loadPlanRecord} reads it. */
-export interface PlanRecord {
+export type PlanRecord = {
     planId: string;
     /** The stored document, as the store holds it. A reader parses it. */
     plan: unknown;
@@ -63,7 +82,7 @@ export interface PlanRecord {
     /** The newest plan of the same analysis that names this plan as its parent. */
     supersededBy: string | null;
     createdAt: string;
-}
+};
 /**
  * Analysis-scoped read of one plan with its parent and the newest plan that
  * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
@@ -72,6 +91,6 @@ export interface PlanRecord {
  * `created_at` is ISO 8601 text, thus the text order is the time order; the plan
  * id breaks a tie so that the answer is stable.
  */
-export declare function loadPlanRecord(pool: Querier, planId: string, opts: {
+export declare function loadPlanRecord(pool: PlanRowQuerier, planId: string, opts: {
     analysisId: string;
 }): ResultAsync<PlanRecord | null, DbError>;

package/dist/state/plans.js

@@ -3,14 +3,9 @@
  * and analysis-scoped lookup.
  */
 import { randomUUID } from "node:crypto";
+import { PLAN_ID_RE } from "../contracts/schemas/chat-parts.js";
+import { z } from "zod";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
-/**
- * `cortex_plans.plan_id` shape contract — `pln-` followed by 8 lowercase hex
- * chars. The chat trigger (`tools/execute-analysis.ts`) enforces the same regex on
- * its tool input; `upsertPlan` re-asserts it because it accepts a caller-derived
- * id rather than minting one.
- */
-const PLAN_ID_PATTERN = /^pln-[a-f0-9]{8}$/;
 /**
  * Enforce tenant scope for a `parentPlanId`: the parent row must exist AND belong
  * to `analysisId`. Shared by {@link insertPlan} and {@link upsertPlan} — the
@@ -30,7 +25,7 @@ function checkParentScope(pool, parentPlanId, analysisId, label) {
         if ((parent.rowCount ?? 0) === 0) {
             throw new Error(`parent plan ${parentPlanId} not found`);
         }
-        if (parent.rows[0].analysis_id !== analysisId) {
+        if (parent.rows[0]?.analysis_id !== analysisId) {
             throw new Error(`parent plan ${parentPlanId} belongs to a different analysis`);
         }
     });
@@ -80,7 +75,7 @@ export function insertPlan(pool, input) {
  * (mirroring the parent-scope violations, which throw before the INSERT).
  */
 export function upsertPlan(pool, input) {
-    if (!PLAN_ID_PATTERN.test(input.planId)) {
+    if (!PLAN_ID_RE.test(input.planId)) {
         throw new Error(`upsertPlan: invalid plan id "${input.planId}" — expected the pln-<8hex> shape`);
     }
     const upsert = () => {
@@ -115,6 +110,13 @@ export function loadPlan(pool, planId, opts) {
         return result.rows[0]?.plan ?? null;
     });
 }
+/** The `cortex_plans` row of {@link loadPlanRecord}, as the SELECT returns it. */
+const PlanRecordRowSchema = z.object({
+    plan: z.json(),
+    parent_plan_id: z.string().nullable(),
+    created_at: z.string(),
+    superseded_by: z.string().nullable(),
+});
 /**
  * Analysis-scoped read of one plan with its parent and the newest plan that
  * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
@@ -134,9 +136,10 @@ export function loadPlanRecord(pool, planId, opts) {
                WHERE p.plan_id = $1 AND p.analysis_id = $2`,
             values: [planId, opts.analysisId],
         });
-        const row = result.rows[0];
-        if (!row)
+        const raw = result.rows[0];
+        if (!raw)
             return null;
+        const row = PlanRecordRowSchema.parse(raw);
         return { planId, plan: row.plan, parentPlanId: row.parent_plan_id, supersededBy: row.superseded_by, createdAt: row.created_at };
     });
 }