@inflexa-ai/harness 0.16.0 → 0.17.0

package/dist/memory/thread-store.d.ts

@@ -10,20 +10,24 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Three lifecycle verbs with distinct guarantees. `archiveThread` is
- * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * A thread may name another as its parent, so the rows under one analysis form
+ * a forest rather than a flat list. The three lifecycle verbs each answer that
+ * edge differently, and the differences are the substance of this module.
+ *
+ * `archiveThread` is recoverable: it stamps `deleted_at` on the named thread
+ * and on every descendant, and because `getThread` and the default
  * `listThreads` filter `deleted_at IS NULL` an archived thread is
  * indistinguishable from an absent one while its row and every one of its
- * `messages` rows stay in storage. `unarchiveThread` clears the stamp and the
- * thread reads as it did; a listing widened with `includeArchived` is the only
- * way to obtain the id it takes, so the recovery is reachable by a host that
- * holds no thread ids it obtained elsewhere.
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp on ONE
+ * row and the thread reads as it did; a listing widened with `includeArchived`
+ * is the only way to obtain the id it takes, so the recovery is reachable by a
+ * host that holds no thread ids it obtained elsewhere.
  * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata row in one transaction, so a failure partway leaves both — never a
- * thread stripped of its transcript, nor a transcript with nothing naming it.
- * It is the thread-scoped member of this package's reclamation vocabulary —
- * `purgeAnalysis` reclaims an analysis's whole persisted footprint,
- * `purgeThread` one thread's.
+ * metadata rows of the whole subtree in one transaction, so a failure partway
+ * leaves both — never a thread stripped of its transcript, nor a transcript
+ * with nothing naming it. It is the thread-scoped member of this package's
+ * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
+ * persisted footprint, `purgeThread` one subtree's.
  *
  * A purge creates no orphan of its own, but it is NOT serialized against a
  * concurrent `appendTurn`: `messages` carries no foreign key to
@@ -31,17 +35,51 @@
  * metadata row. A turn committing after the purge therefore persists messages
  * under a `thread_id` that no longer resolves to an analysis, leaving them
  * unreachable by any later thread- or analysis-scoped reclamation. Stop writes
- * to a thread — unbind it from any live conversation — before purging it; this
- * store cannot observe a host's in-flight turns, so it does not enforce that.
+ * to every thread in the subtree — unbind each from any live conversation —
+ * before purging its root; this store cannot observe a host's in-flight turns,
+ * so it does not enforce that.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * The kind of session a thread holds. `conversation` is the analysis
+ * conversation the product has always had; `report` is a report session spawned
+ * from one.
+ *
+ * The set is closed rather than free-form because a thread's type is what
+ * selects the agent that runs it. That resolution is a separate capability, and
+ * it can only be exhaustive over a membership something can enumerate — a
+ * free-form column pushes an unmatched value into a fallback no reader has the
+ * list to write.
+ *
+ * The array is the single declaration and the union is derived from it, so the
+ * run-time check `createThread` needs — for a value that reached the store from
+ * outside the compiler's reach — cannot drift from the type callers program
+ * against.
+ */
+declare const THREAD_TYPES: readonly ["conversation", "report"];
+export type ThreadType = (typeof THREAD_TYPES)[number];
 /** One conversation thread's metadata, as returned by the store. */
 export interface Thread {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title: string | null;
+    /** Which kind of session this row holds. A thread created without one is a `conversation`. */
+    readonly threadType: ThreadType;
+    /** The thread this one was spawned from — `null` on a thread that stands on its own. */
+    readonly parentThreadId: string | null;
+    /**
+     * The parent's `messages.seq` at the moment of the spawn: the frozen point
+     * in the parent's transcript this thread was built on. `null` exactly when
+     * `parentThreadId` is — half the pair names nothing a consumer can resolve.
+     *
+     * It records the spawn point, not a promise that the prefix still reads the
+     * same: `retractLastTurn` can cut the parent's tail behind an anchor, so a
+     * reader must treat an anchor past the parent's current end as a normal
+     * state rather than a corruption.
+     */
+    readonly parentSeq: number | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
     /**
@@ -56,7 +94,51 @@ export interface CreateThreadInput {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title?: string | null;
+    /** Omitted is `conversation` — what a thread is when nothing says otherwise. */
+    readonly type?: ThreadType;
+    /**
+     * The thread this one is spawned from. It must belong to the same analysis
+     * as the child; whether it exists at all is the foreign key's verdict, not
+     * this store's.
+     */
+    readonly parentThreadId?: string;
+    /**
+     * The parent's `messages.seq` at the spawn. Supply it with `parentThreadId`
+     * or neither: the two are one fact — which transcript, and how much of it —
+     * and either half alone describes no place.
+     */
+    readonly parentSeq?: number;
 }
+/**
+ * A create the store refuses on its own, before any row is written. Distinct
+ * from `DbError`: nothing failed at the driver — the request described a thread
+ * the store will not write, and each variant carries the identifiers that say
+ * which values disagreed.
+ *
+ * Only the rules the store enforces itself live here. A `parentThreadId` naming
+ * no row is not one of them: the foreign key refuses that insert and
+ * `tryMutation` classifies the refusal as the `constraint_violation` variant of
+ * `DbError`.
+ */
+export type ThreadInputError = {
+    readonly type: "parent_analysis_mismatch";
+    readonly op: string;
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly parentThreadId: string;
+    readonly parentAnalysisId: string;
+} | {
+    readonly type: "parent_anchor_unpaired";
+    readonly op: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly parentSeq: number | null;
+} | {
+    readonly type: "unknown_thread_type";
+    readonly op: string;
+    readonly threadId: string;
+    readonly threadType: string;
+};
 export interface ListThreadsInput {
     readonly analysisId: string;
     readonly page?: number;
@@ -68,6 +150,20 @@ export interface ListThreadsInput {
      * widened back out of.
      */
     readonly includeArchived?: boolean;
+    /**
+     * Narrow to one kind of session, exact match. Omitting it narrows NOTHING —
+     * a caller that supplies no filter receives every type, which is what a
+     * session picker wants: a user browsing an analysis expects to reach a
+     * report session directly.
+     *
+     * That is the opposite polarity to `includeArchived`, which widens a listing
+     * that is narrow by default, and the difference is deliberate. An archived
+     * thread is hidden state — showing it takes an explicit ask. A report
+     * session is not hidden state, so nothing has to ask for it.
+     */
+    readonly type?: ThreadType;
+    /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
+    readonly parentThreadId?: string;
 }
 export interface ThreadPage {
     readonly threads: Thread[];
@@ -80,9 +176,16 @@ export interface ThreadStore {
     /**
      * Create a thread row. Idempotent on `thread_id` — a second create for an
      * existing id is a no-op that preserves the existing row (including its
-     * `created_at`). Returns the live row.
+     * `created_at`) and reads none of the supplied type, parent, or anchor. A
+     * caller that needs those persisted compares them against the returned row.
+     * Returns the live row.
+     *
+     * Refused with a `ThreadInputError`, no row written: a parent belonging to
+     * another analysis, a parent supplied without its anchor or an anchor
+     * without its parent, and a type outside the closed set. A parent naming no
+     * row is the foreign key's refusal and arrives as a `DbError`.
      */
-    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
+    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError | ThreadInputError>;
     /** The live thread by id, or `null` if absent or archived. */
     getThread(threadId: string): ResultAsync<Thread | null, DbError>;
     /**
@@ -91,26 +194,39 @@ export interface ThreadStore {
      */
     updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
     /**
-     * Soft-delete: stamp `deleted_at` so the thread leaves `getThread` and
-     * `listThreads`. The row and every one of its messages remain, and an
-     * already-archived thread keeps the stamp it got the first time.
+     * Soft-delete the subtree: stamp `deleted_at` on the named thread and on
+     * every descendant reachable through `parent_thread_id`, at any depth, so a
+     * hidden thread never leaves a visible child behind. Every row and every one
+     * of their messages remain, and any thread in the subtree that was already
+     * archived keeps the stamp it got the first time.
      */
     archiveThread(threadId: string): ResultAsync<void, DbError>;
     /**
-     * Clear `deleted_at`, returning the thread and its messages to view exactly
-     * as they read before the archive. No-op on a live or absent thread.
+     * Clear `deleted_at` on the named thread ALONE, returning it and its
+     * messages to view exactly as they read before the archive; every descendant
+     * is left as it was found. No-op on a live or absent thread.
+     *
+     * The asymmetry against `archiveThread` is what keeps the schema honest. A
+     * symmetric cascade would restore a child the user had archived on its own
+     * beforehand, so a row would have to record whether a cascade or a
+     * deliberate action set its tombstone — a fourth column carrying nothing
+     * else. With the asymmetry no row needs that distinction, and every archived
+     * thread is recovered the same way: by naming it, which a listing widened
+     * with `includeArchived` supplies.
      */
     unarchiveThread(threadId: string): ResultAsync<void, DbError>;
     /**
-     * Reclaim the thread's whole footprint: its `messages` rows and its
-     * `cortex_analysis_threads` row, removed together in one transaction.
-     * Unrecoverable — nothing of the thread survives, and no tombstone marks
-     * that it existed. A `thread_id` with no row succeeds as a no-op.
+     * Reclaim the subtree's whole footprint: the named thread, every descendant
+     * reachable through `parent_thread_id` at any depth, and the `messages` rows
+     * of every one of them, removed together in one transaction. Unrecoverable —
+     * nothing survives, and no tombstone marks that any of it existed. A
+     * `thread_id` with no row succeeds as a no-op.
      */
     purgeThread(threadId: string): ResultAsync<void, DbError>;
     /**
      * Threads for one analysis, newest-updated first, paginated. Live threads
-     * only unless `includeArchived` widens the set; `total` and `hasMore`
+     * only unless `includeArchived` widens the set, and every type under every
+     * parent unless `type` / `parentThreadId` narrow it; `total` and `hasMore`
      * always describe whichever set the page was drawn from.
      */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
@@ -121,3 +237,4 @@ export interface ThreadStore {
  * `cortex_analysis_threads` table is provisioned by the state-init DDL.
  */
 export declare function createThreadStore(pool: Pool): ThreadStore;
+export {};

package/dist/memory/thread-store.js

@@ -10,20 +10,24 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Three lifecycle verbs with distinct guarantees. `archiveThread` is
- * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * A thread may name another as its parent, so the rows under one analysis form
+ * a forest rather than a flat list. The three lifecycle verbs each answer that
+ * edge differently, and the differences are the substance of this module.
+ *
+ * `archiveThread` is recoverable: it stamps `deleted_at` on the named thread
+ * and on every descendant, and because `getThread` and the default
  * `listThreads` filter `deleted_at IS NULL` an archived thread is
  * indistinguishable from an absent one while its row and every one of its
- * `messages` rows stay in storage. `unarchiveThread` clears the stamp and the
- * thread reads as it did; a listing widened with `includeArchived` is the only
- * way to obtain the id it takes, so the recovery is reachable by a host that
- * holds no thread ids it obtained elsewhere.
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp on ONE
+ * row and the thread reads as it did; a listing widened with `includeArchived`
+ * is the only way to obtain the id it takes, so the recovery is reachable by a
+ * host that holds no thread ids it obtained elsewhere.
  * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata row in one transaction, so a failure partway leaves both — never a
- * thread stripped of its transcript, nor a transcript with nothing naming it.
- * It is the thread-scoped member of this package's reclamation vocabulary —
- * `purgeAnalysis` reclaims an analysis's whole persisted footprint,
- * `purgeThread` one thread's.
+ * metadata rows of the whole subtree in one transaction, so a failure partway
+ * leaves both — never a thread stripped of its transcript, nor a transcript
+ * with nothing naming it. It is the thread-scoped member of this package's
+ * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
+ * persisted footprint, `purgeThread` one subtree's.
  *
  * A purge creates no orphan of its own, but it is NOT serialized against a
  * concurrent `appendTurn`: `messages` carries no foreign key to
@@ -31,16 +35,66 @@
  * metadata row. A turn committing after the purge therefore persists messages
  * under a `thread_id` that no longer resolves to an analysis, leaving them
  * unreachable by any later thread- or analysis-scoped reclamation. Stop writes
- * to a thread — unbind it from any live conversation — before purging it; this
- * store cannot observe a host's in-flight turns, so it does not enforce that.
+ * to every thread in the subtree — unbind each from any live conversation —
+ * before purging its root; this store cannot observe a host's in-flight turns,
+ * so it does not enforce that.
  */
-import { okAsync } from "neverthrow";
+import { errAsync, okAsync } from "neverthrow";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+/**
+ * The kind of session a thread holds. `conversation` is the analysis
+ * conversation the product has always had; `report` is a report session spawned
+ * from one.
+ *
+ * The set is closed rather than free-form because a thread's type is what
+ * selects the agent that runs it. That resolution is a separate capability, and
+ * it can only be exhaustive over a membership something can enumerate — a
+ * free-form column pushes an unmatched value into a fallback no reader has the
+ * list to write.
+ *
+ * The array is the single declaration and the union is derived from it, so the
+ * run-time check `createThread` needs — for a value that reached the store from
+ * outside the compiler's reach — cannot drift from the type callers program
+ * against.
+ */
+const THREAD_TYPES = ["conversation", "report"];
+function isThreadType(value) {
+    return THREAD_TYPES.some((known) => known === value);
+}
+const _assertDomainError = true;
+/**
+ * The projection every read of a thread row shares. Fixed text, never caller
+ * input, and written once so no statement can return a row that is short a
+ * column `toThread` reads — a gap that would surface as an `undefined` field on
+ * a `Thread`, not as a failure.
+ */
+const THREAD_COLUMNS = "thread_id, analysis_id, title, thread_type, parent_thread_id, parent_seq::text AS parent_seq, created_at, updated_at, deleted_at";
+/**
+ * The named thread plus every descendant reachable through `parent_thread_id`,
+ * at any depth. Fixed text taking the thread id as `$1`, and the single
+ * definition the subtree statements share, so archive and purge cannot come to
+ * walk to different depths.
+ *
+ * `UNION`, not `UNION ALL`: deduplicating against the rows already collected
+ * makes the walk terminate even if a row ever came to name an ancestor as its
+ * parent — a shape no write path here produces, and one the column does not
+ * forbid either.
+ */
+const SUBTREE_CTE = `WITH RECURSIVE subtree(thread_id) AS (
+     SELECT thread_id FROM cortex_analysis_threads WHERE thread_id = $1
+     UNION
+     SELECT child.thread_id
+       FROM cortex_analysis_threads child
+       JOIN subtree ON child.parent_thread_id = subtree.thread_id
+   )`;
 function toThread(row) {
     return {
         threadId: row.thread_id,
         analysisId: row.analysis_id,
         title: row.title,
+        threadType: row.thread_type,
+        parentThreadId: row.parent_thread_id,
+        parentSeq: row.parent_seq === null ? null : Number(row.parent_seq),
         createdAt: row.created_at,
         updatedAt: row.updated_at,
         deletedAt: row.deleted_at,
@@ -54,22 +108,100 @@ const MAX_PER_PAGE = 200;
  * `cortex_analysis_threads` table is provisioned by the state-init DDL.
  */
 export function createThreadStore(pool) {
-    function createThread(input) {
-        return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title)
-         VALUES ($1, $2, $3)
+    /**
+     * The parent's own analysis scope, or `null` when no such row exists.
+     *
+     * Absence is deliberately not a verdict here: a `parentThreadId` naming no
+     * row falls through to the insert, where the foreign key refuses it and
+     * `tryMutation` classifies that refusal as the `constraint_violation`
+     * variant of `DbError`. Pre-empting the constraint with an existence query
+     * would buy a round trip and a window between the check and the insert in
+     * which the parent could vanish, for a verdict the constraint already
+     * reaches on its own.
+     *
+     * The lookup does not filter `deleted_at IS NULL`: an archived parent is a
+     * real row holding a real transcript, so a child anchored into it is
+     * describing something that exists.
+     */
+    function parentAnalysisOf(parentThreadId) {
+        return tryQuery("thread-store.createThread.parentScope", () => pool.query("SELECT analysis_id FROM cortex_analysis_threads WHERE thread_id = $1", [parentThreadId])).map(({ rows }) => rows[0]?.analysis_id ?? null);
+    }
+    /**
+     * The write itself, past the rules the store enforces before it.
+     *
+     * Idempotency wins over everything the caller supplied: `ON CONFLICT
+     * (thread_id) DO NOTHING` short-circuits before any constraint is evaluated
+     * and reads no supplied parent, so a repeat create returns the existing row
+     * unchanged — even one naming a parent that does not exist. A caller that
+     * needs its type, parent, or anchor persisted compares them against the
+     * returned row.
+     */
+    function insertThread(input) {
+        return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title, thread_type, parent_thread_id, parent_seq)
+         VALUES ($1, $2, $3, $4, $5, $6)
          ON CONFLICT (thread_id) DO NOTHING
-         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
+         RETURNING ${THREAD_COLUMNS}`, [input.threadId, input.analysisId, input.title ?? null, input.type ?? "conversation", input.parentThreadId ?? null, input.parentSeq ?? null])).andThen(({ rows }) => {
             if (rows[0])
                 return okAsync(toThread(rows[0]));
             // Row already existed — ON CONFLICT DO NOTHING returns nothing. Read it
             // back (it may be archived; return it regardless so the caller sees
             // the existing row's identity).
-            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
-           FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
+            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT ${THREAD_COLUMNS} FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
+        });
+    }
+    function createThread(input) {
+        // Widened on purpose: the compile-time union covers a caller inside this
+        // package's type graph, and this check is for the value that reached the
+        // store from outside it — across a package boundary, out of a JSON body,
+        // off a row some other writer put there.
+        const requestedType = input.type;
+        if (requestedType !== undefined && !isThreadType(requestedType)) {
+            return errAsync({
+                type: "unknown_thread_type",
+                op: "thread-store.createThread",
+                threadId: input.threadId,
+                threadType: requestedType,
+            });
+        }
+        const parentThreadId = input.parentThreadId ?? null;
+        const parentSeq = input.parentSeq ?? null;
+        // Both halves of the edge or neither: the anchor is the point in the
+        // parent's transcript this thread was spawned from, and an edge without
+        // one leaves a consumer no way to tell which prefix of the parent the
+        // child stands on. Every rule below is gated on a value being supplied,
+        // so a create that names neither reaches none of them and takes the same
+        // path a first-turn conversation has always taken.
+        if ((parentThreadId === null) !== (parentSeq === null)) {
+            return errAsync({
+                type: "parent_anchor_unpaired",
+                op: "thread-store.createThread",
+                threadId: input.threadId,
+                parentThreadId,
+                parentSeq,
+            });
+        }
+        if (parentThreadId === null)
+            return insertThread(input);
+        // A data-integrity rule, not an authorization one: it keeps a parent edge
+        // inside a single analysis, so a subtree walk can never cross into
+        // another analysis's rows. The store never compares a caller's request
+        // scope against a row.
+        return parentAnalysisOf(parentThreadId).andThen((parentAnalysisId) => {
+            if (parentAnalysisId !== null && parentAnalysisId !== input.analysisId) {
+                return errAsync({
+                    type: "parent_analysis_mismatch",
+                    op: "thread-store.createThread",
+                    threadId: input.threadId,
+                    analysisId: input.analysisId,
+                    parentThreadId,
+                    parentAnalysisId,
+                });
+            }
+            return insertThread(input);
         });
     }
     function getThread(threadId) {
-        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
+        return tryQuery("thread-store.getThread", () => pool.query(`SELECT ${THREAD_COLUMNS}
          FROM cortex_analysis_threads
          WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
@@ -86,19 +218,42 @@ export function createThreadStore(pool) {
         `UPDATE cortex_analysis_threads
          SET title = $2, updated_at = GREATEST(updated_at, clock_timestamp())
          WHERE thread_id = $1 AND deleted_at IS NULL
-         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
+         RETURNING ${THREAD_COLUMNS}`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
     function archiveThread(threadId) {
         return tryMutation("thread-store.archiveThread", () => pool.query(
+        // The stamp reaches the whole subtree because a hidden thread must
+        // not leave a visible child behind — and to any depth, since the
+        // column permits a grandchild and a one-level sweep would leave one
+        // listed under a parent the user can no longer see.
+        //
         // The tombstone guard is what makes a second archive change nothing:
-        // the stamp records when the thread left view, and re-stamping it
-        // would push that moment forward on every repeat.
-        `UPDATE cortex_analysis_threads
+        // the stamp records when a thread left view, and re-stamping it would
+        // push that moment forward on every repeat. It sits on the UPDATE and
+        // not on the walk, because a walk that stopped at an already-archived
+        // child would never reach the live grandchild underneath it.
+        //
+        // `NOW()` is the transaction's clock, so every row this sweep reaches
+        // carries the same stamp — one archive action reads back as one moment.
+        //
+        // `updated_at` is untouched, for the reason `unarchiveThread` carries:
+        // it orders the listing by conversation activity, and moving a thread
+        // out of view is not activity.
+        `${SUBTREE_CTE}
+         UPDATE cortex_analysis_threads
          SET deleted_at = NOW()
-         WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(() => undefined);
+         WHERE thread_id IN (SELECT thread_id FROM subtree) AND deleted_at IS NULL`, [threadId])).map(() => undefined);
     }
     function unarchiveThread(threadId) {
         return tryMutation("thread-store.unarchiveThread", () => pool.query(
+        // One row, against an archive that sweeps the subtree. The asymmetry
+        // is what keeps the schema honest: a symmetric cascade would restore
+        // a child the user had archived on its own before the parent was, so
+        // a row would have to record whether a cascade or a deliberate action
+        // set its tombstone — a fourth column carrying nothing else. With the
+        // asymmetry no row carries that distinction, and every archived
+        // thread is recovered the same way, by naming it.
+        //
         // `updated_at` is untouched on purpose: it orders the listing by
         // conversation activity, and restoring a thread to view is not
         // activity — a restored thread lands back where its last turn left it.
@@ -111,8 +266,21 @@ export function createThreadStore(pool) {
         // analysis only by joining through `cortex_analysis_threads`, so a metadata
         // row removed without its messages strands them beyond the reach of any
         // later reclamation. Either the pair goes or neither does.
-        return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query("DELETE FROM messages WHERE thread_id = $1", [threadId]))
-            .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query("DELETE FROM cortex_analysis_threads WHERE thread_id = $1", [threadId])))
+        //
+        // The explicit message delete must reach the same depth the database
+        // cascade reaches. The cascade on `parent_thread_id` removes a
+        // descendant's row recursively, but it cannot touch that descendant's
+        // `messages` — no foreign key connects them — so a one-level delete here
+        // would strand a grandchild's transcript exactly as a bare cascade strands
+        // a child's.
+        //
+        // Messages go first: the walk both statements share reads the very rows
+        // the second one removes, so the reverse order would leave the subtree
+        // unresolvable by the time its transcripts were named.
+        return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query(`${SUBTREE_CTE}
+         DELETE FROM messages WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId]))
+            .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query(`${SUBTREE_CTE}
+         DELETE FROM cortex_analysis_threads WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             .map(() => undefined));
     }
     function listThreads(input) {
@@ -121,25 +289,45 @@ export function createThreadStore(pool) {
         const offset = page * perPage;
         // The count and the page are two statements over what has to be one set:
         // a total drawn from a different predicate than the page's would report a
-        // size the caller can never page to. Writing the row scope once — one of
-        // two fixed fragments, never caller text — makes them unable to disagree.
+        // size the caller can never page to. Building the row scope once — the
+        // fragment AND the values it binds — makes them unable to disagree. Every
+        // predicate is fixed text and every value rides as a bound parameter, so
+        // no caller string ever reaches the SQL.
         //
-        // The widened scope is the one that cannot use the table's index, which is
-        // partial on `deleted_at IS NULL`: dropping the predicate drops the index
-        // with it, so an archived-inclusive listing scans. Deliberate — the live
-        // listing is the hot path and keeps its index, while widening is a rare,
-        // user-initiated recovery. A deployment that made it routine would want a
-        // plain `analysis_id` index beside the partial one, not this listing changed.
-        const scope = input.includeArchived ? "analysis_id = $1" : "analysis_id = $1 AND deleted_at IS NULL";
+        // The widened scope is the one that cannot use the `analysis_id` index,
+        // which is partial on `deleted_at IS NULL`: dropping the predicate drops
+        // the index with it, so an archived-inclusive listing scans. Deliberate —
+        // the live listing is the hot path and keeps its index, while widening is a
+        // rare, user-initiated recovery. A deployment that made it routine would
+        // want a plain `analysis_id` index beside the partial one, not this listing
+        // changed. A listing narrowed by parent is indexed either way: the
+        // `parent_thread_id` index carries no predicate, for the subtree walk's sake.
+        const scopeValues = [input.analysisId];
+        const predicates = ["analysis_id = $1"];
+        if (!input.includeArchived)
+            predicates.push("deleted_at IS NULL");
+        if (input.type !== undefined) {
+            scopeValues.push(input.type);
+            predicates.push(`thread_type = $${scopeValues.length}`);
+        }
+        if (input.parentThreadId !== undefined) {
+            scopeValues.push(input.parentThreadId);
+            predicates.push(`parent_thread_id = $${scopeValues.length}`);
+        }
+        const scope = predicates.join(" AND ");
+        // The page's two extra placeholders sit past the scope's, so a filter
+        // added to the scope shifts them rather than colliding with them.
+        const limitPlaceholder = scopeValues.length + 1;
+        const offsetPlaceholder = scopeValues.length + 2;
         return tryQuery("thread-store.listThreads.count", () => pool.query(`SELECT COUNT(*)::text AS count
          FROM cortex_analysis_threads
-         WHERE ${scope}`, [input.analysisId])).andThen((totalResult) => {
+         WHERE ${scope}`, scopeValues)).andThen((totalResult) => {
             const total = Number(totalResult.rows[0].count);
-            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
+            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT ${THREAD_COLUMNS}
            FROM cortex_analysis_threads
            WHERE ${scope}
            ORDER BY updated_at DESC, thread_id
-           LIMIT $2 OFFSET $3`, [input.analysisId, perPage, offset])).map(({ rows }) => ({
+           LIMIT $${limitPlaceholder} OFFSET $${offsetPlaceholder}`, [...scopeValues, perPage, offset])).map(({ rows }) => ({
                 threads: rows.map(toThread),
                 total,
                 page,

package/dist/prompts/literature-reviewer.d.ts

@@ -1 +1 @@
-export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 MUST be called with `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## Investigation Process\n\nFor each gene, pathway, or feature in the brief:\n\n1. **Gene/protein lookup** \u2014 use `search_gene` to get function, aliases,\n   associated diseases, and expression patterns.\n2. **Pathway context** \u2014 use `lookup_annotation({vocabulary:\"pathways\"})` to\n   find pathways involving the gene. Note which pathways connect multiple\n   genes from the brief.\n3. **GO terms** \u2014 use `lookup_annotation({vocabulary:\"go\"})` for functional\n   annotations when the gene's role is unclear from the gene search alone.\n4. **Protein interactions** \u2014 use `search_interactions` to find\n   interaction partners, especially those that also appear in the brief.\n5. **Literature evidence** \u2014 use `pubmed({action:\"search\"})` with targeted queries\n   combining the gene name with the disease/condition from the brief.\n   Use `pubmed({action:\"details\"})` for the most relevant hits. Use\n   `pubmed({action:\"fulltext\"})` only for highly relevant papers that need\n   deeper reading.\n6. **Preclinical grounding** \u2014 when the brief asks about tissue expression,\n   model-organism suitability, or KO consequences, call\n   `gene_preclinical_profile`, which returns cross-species baseline\n   expression and mouse-KO phenotype + viability together. It takes a single\n   human gene symbol and tolerates \"no data\" cleanly.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified):\n  Full investigation \u2014 all 5 steps above.\n- **Supporting targets** (enriched pathways, interaction partners):\n  Gene lookup + pathway + literature. Skip GO terms and interactions\n  unless results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";
+export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 MUST be called with `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n- `resolve_citation` \u2014 verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: `inconclusive` is not `not_found`, and an unavailable authority is not proof of fabrication.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## Investigation Process\n\nFor each gene, pathway, or feature in the brief:\n\n1. **Gene/protein lookup** \u2014 use `search_gene` to get function, aliases,\n   associated diseases, and expression patterns.\n2. **Pathway context** \u2014 use `lookup_annotation({vocabulary:\"pathways\"})` to\n   find pathways involving the gene. Note which pathways connect multiple\n   genes from the brief.\n3. **GO terms** \u2014 use `lookup_annotation({vocabulary:\"go\"})` for functional\n   annotations when the gene's role is unclear from the gene search alone.\n4. **Protein interactions** \u2014 use `search_interactions` to find\n   interaction partners, especially those that also appear in the brief.\n5. **Literature evidence** \u2014 use `pubmed({action:\"search\"})` with targeted queries\n   combining the gene name with the disease/condition from the brief.\n   Use `pubmed({action:\"details\"})` for the most relevant hits. Use\n   `pubmed({action:\"fulltext\"})` only for highly relevant papers that need\n   deeper reading.\n6. **Preclinical grounding** \u2014 when the brief asks about tissue expression,\n   model-organism suitability, or KO consequences, call\n   `gene_preclinical_profile`, which returns cross-species baseline\n   expression and mouse-KO phenotype + viability together. It takes a single\n   human gene symbol and tolerates \"no data\" cleanly.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified):\n  Full investigation \u2014 all 5 steps above.\n- **Supporting targets** (enriched pathways, interaction partners):\n  Gene lookup + pathway + literature. Skip GO terms and interactions\n  unless results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";

package/dist/prompts/literature-reviewer.js

@@ -26,6 +26,7 @@ turn and forces a retry.
   valid "no data" outcomes (Bgee may have no calls for dog or macaque; many
   human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.
 - \`pubmed({action:"fulltext"})\` — single \`pmcId\` per call (from a \`details\` result). Use sparingly.
+- \`resolve_citation\` — verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: \`inconclusive\` is not \`not_found\`, and an unavailable authority is not proof of fabrication.
 
 Batching beats truncation: if you have 300 identifiers to look up in
 \`search_interactions\`, make three calls of 100 rather than one call of 100
@@ -98,6 +99,7 @@ For each investigated target:
 ## Do NOT
 
 - **Fabricate results.** If a search returns no results, say so.
+- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.
 - **Skip tool calls.** Do not claim knowledge about a gene without
   looking it up. Your value is in systematic, verified investigation.
 - **Over-read articles.** Use \`pubmed({action:"fulltext"})\` sparingly — abstracts