@inflexa-ai/harness 0.16.0 → 0.18.0

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

package/dist/prompts/target-assessment/briefs/executive-recommendation.d.ts

@@ -1 +1 @@
-export declare const executiveRecommendationBrief = "# Section: Executive recommendation\n\nIntegrate the Phase-4 dossier and the per-section synthesis outputs\n(liability bullets, target-organ liabilities trail, translational\ncommentary) into a disposition with cited rationale, key strengths, key\nrisks, and a coverage qualifier.\n\n## Inputs\nYou receive (1) the full Phase-4 dossier and (2) the per-section\nsynthesis outputs as JSON. Cite at least three section paths from the\ndossier in the rationale.\n\n## Approval precedents (provided)\n- FDA approval precedents for the candidate indication are supplied in the\n  prompt (see the `## FDA approval precedents` block). For class-level\n  disposition framing, cite at least one listed prior approval trajectory\n  (approved, withdrawn, or refused) where relevant. Do not assert\n  precedents absent from that block.\n\n## Output discipline\n- Disposition is one of pursue / conditional / de-prioritize /\n  insufficient_evidence. Confidence is one of high / medium / low.\n- Rationale \u2265 600 chars (the existing length probe enforces this).\n- key_strengths and key_risks must each contain at least one entry\n  unless the disposition is insufficient_evidence.\n- coverage_qualifier.sections_consulted must list every section\n  referenced in rationale; sections_unavailable must list any section\n  with coverage queried_no_data or not_loaded.\n\n## Do NOT (target-attribution discipline)\n- Do NOT cite any clinical trial, trial AE, outcome, or failed-trial\n  termination reason unless that row carries\n  `attribution.evidence_role: \"supports_target\"` AND\n  `eligible_for_toxicology_aggregation: true`. Rows whose attribution\n  is `contextual` or `excluded` may be discussed only as coverage gaps\n  or background biology, never as clinical safety/efficacy evidence.\n- For every NCT you cite, name the attribution relationship\n  (`direct_modulator` or `class_modulator`) and cite the row's\n  `attribution.basis[]` source. Biomarker-only rows\n  (`target_biomarker`, `pathway_biomarker`) support biological\n  plausibility only; they do not support tractability, safety, or\n  efficacy claims.\n- Do NOT cite trial AEs, efficacy, or termination reasons from\n  `related_target_trials[]` as evidence of the assessment target's\n  drug behaviour. These trials are on related receptors (e.g.,\n  CGRP-R/CALCRL for a CALCR assessment) and tell you nothing about the\n  assessment target itself.\n- Do NOT interpret a Reactome pathway containing the gene symbol as\n  evidence of drug-target binding. Reactome pathways list participating\n  genes, not drug interactions. Drug-binding evidence comes from\n  `drug_interactions.data.rows` and\n  `safety_profile.off_target_panel.data.rows` only.\n- Do NOT cite a dossier path for a fact that does not appear at that\n  path. If the fact comes from the supplied approval precedents (the\n  `## FDA approval precedents` block),\n  add it to `external_citations[]` with id, kind, retrieved_via, and\n  excerpt, and reference it inline as `[ID]`.\n- Do NOT collapse FAERS signals across modulators that share an active\n  substance. The deduplicated\n  `safety_profile.faers.data.per_modulator` is the source of truth for\n  distinct-substance counts.\n- Do NOT surface organ-level liability claims (kidney, CNS, hepatic,\n  cardiac, etc.) unless they appear in\n  `safety_profile.target_organ_liabilities`. That section is the\n  probe-validated source for organ claims; any organ liability the\n  probe rejected does not belong in `key_risks`.\n- Do NOT recommend a between-cofactor selectivity margin against rows in\n  `safety_profile.off_target_panel.data.excluded_rows[]` that carry\n  `relationship: \"obligate_cofactor\"`. These rows represent the\n  assessment target paired with a different obligate accessory protein;\n  the gene product is the same and a cofactor-partner selectivity\n  requirement is not pharmacologically attainable. Frame any clinical\n  consequence of the cofactor partner (e.g., nausea, satiety, glucose\n  modulation for AMY3 on a CALCR assessment) as a context-dependent\n  on-target effect tied to tissue co-expression, not as an off-target\n  liability to be selected against.\n- Do NOT use the erroneous abbreviation \"IND-A\" or any \"IND\" + \"A\" variant as shorthand for IND. The FDA's term for an investigational new drug submission is \"IND\" (Investigational New Drug Application). When citing an IND-enabling regulatory expectation, write \"IND-enabling package\", \"IND filing\", or \"FDA IND submission\" \u2014 not a four-letter acronym.\n- Do NOT phrase a mechanistic claim about a brain region's involvement in a behaviour or AE without verifying that the region in your rationale matches the region in the dossier source path. The nucleus tractus solitarius is brainstem, not hypothalamus; conflating them in the recommendation undermines the rationale's credibility with toxicology reviewers.\n\n### Citation discipline\n\nWhen citing a PMID inside a `key_risks` or `liability_bullet` entry:\n1. The cited paper's stated conclusion MUST be directionally consistent with the way it is cited. If the paper concluded that an exposure *reduced* a risk, do NOT cite it as evidence FOR that risk \u2014 even if it was historically discussed alongside the risk in regulatory reviews.\n2. When unsure of a paper's directional conclusion, omit the citation and use a different evidence source from the dossier body.\n3. Every NCT cited must appear in the dossier's clinical_development.trials, failed_trials, or analytics.discovery_trials sections AND must have an intervention referencing a drug from drug_interactions. NCTs whose interventions are outside the on-target class (e.g., SGLT2 inhibitors in a GLP-1R dossier) must not be cited.";
+export declare const executiveRecommendationBrief = "# Section: Executive recommendation\n\nIntegrate the Phase-4 dossier and the per-section synthesis outputs\n(liability bullets, target-organ liabilities trail, translational\ncommentary) into a disposition with cited rationale, key strengths, key\nrisks, and a coverage qualifier.\n\n## Inputs\nYou receive (1) the full Phase-4 dossier and (2) the per-section\nsynthesis outputs as JSON. Cite at least three section paths from the\ndossier in the rationale.\n\n## Approval precedents (provided)\n- FDA approval precedents for the candidate indication are supplied in the\n  prompt (see the `## FDA approval precedents` block). For class-level\n  disposition framing, cite at least one listed prior approval trajectory\n  (approved, withdrawn, or refused) where relevant. Do not assert\n  precedents absent from that block.\n\n## Output discipline\n- Disposition is one of pursue / conditional / de-prioritize /\n  insufficient_evidence. Confidence is one of high / medium / low.\n- Rationale \u2265 600 chars (the existing length probe enforces this).\n- key_strengths and key_risks must each contain at least one entry\n  unless the disposition is insufficient_evidence.\n- coverage_qualifier.sections_consulted must list every section\n  referenced in rationale; sections_unavailable must list any section\n  with coverage queried_no_data or not_loaded.\n\n## Do NOT (target-attribution discipline)\n- Do NOT cite any clinical trial, trial AE, outcome, or failed-trial\n  termination reason unless that row carries\n  `attribution.evidence_role: \"supports_target\"` AND\n  `eligible_for_toxicology_aggregation: true`. Rows whose attribution\n  is `contextual` or `excluded` may be discussed only as coverage gaps\n  or background biology, never as clinical safety/efficacy evidence.\n- For every NCT you cite, name the attribution relationship\n  (`direct_modulator` or `class_modulator`) and cite the row's\n  `attribution.basis[]` source. Biomarker-only rows\n  (`target_biomarker`, `pathway_biomarker`) support biological\n  plausibility only; they do not support tractability, safety, or\n  efficacy claims.\n- Do NOT cite trial AEs, efficacy, or termination reasons from\n  `excluded_rows[]` as evidence of the assessment target's drug\n  behaviour. Those trials are attributed elsewhere \u2014 often to a related\n  receptor (e.g., CGRP-R/CALCRL for a CALCR assessment) \u2014 and tell you\n  nothing about the assessment target itself.\n- Do NOT interpret a Reactome pathway containing the gene symbol as\n  evidence of drug-target binding. Reactome pathways list participating\n  genes, not drug interactions. Drug-binding evidence comes from\n  `drug_interactions.data.rows` and\n  `safety_profile.off_target_panel.data.rows` only.\n- Do NOT cite a dossier path for a fact that does not appear at that\n  path. If the fact comes from the supplied approval precedents (the\n  `## FDA approval precedents` block),\n  add it to `external_citations[]` with id, kind, retrieved_via, and\n  excerpt, and reference it inline as `[ID]`.\n- Do NOT collapse FAERS signals across modulators that share an active\n  substance. The deduplicated\n  `safety_profile.faers.data.per_modulator` is the source of truth for\n  distinct-substance counts.\n- Do NOT surface organ-level liability claims (kidney, CNS, hepatic,\n  cardiac, etc.) unless they appear in\n  `safety_profile.target_organ_liabilities.data.rows`. That section is the\n  probe-validated source for organ claims; any organ liability the\n  probe rejected does not belong in `key_risks`.\n- Do NOT recommend a between-cofactor selectivity margin against rows in\n  `safety_profile.off_target_panel.data.excluded_rows[]` that carry\n  `relationship: \"obligate_cofactor\"`. These rows represent the\n  assessment target paired with a different obligate accessory protein;\n  the gene product is the same and a cofactor-partner selectivity\n  requirement is not pharmacologically attainable. Frame any clinical\n  consequence of the cofactor partner (e.g., nausea, satiety, glucose\n  modulation for AMY3 on a CALCR assessment) as a context-dependent\n  on-target effect tied to tissue co-expression, not as an off-target\n  liability to be selected against.\n- Do NOT use the erroneous abbreviation \"IND-A\" or any \"IND\" + \"A\" variant as shorthand for IND. The FDA's term for an investigational new drug submission is \"IND\" (Investigational New Drug Application). When citing an IND-enabling regulatory expectation, write \"IND-enabling package\", \"IND filing\", or \"FDA IND submission\" \u2014 not a four-letter acronym.\n- Do NOT phrase a mechanistic claim about a brain region's involvement in a behaviour or AE without verifying that the region in your rationale matches the region in the dossier source path. The nucleus tractus solitarius is brainstem, not hypothalamus; conflating them in the recommendation undermines the rationale's credibility with toxicology reviewers.\n\n### Citation discipline\n\nWhen citing a PMID inside a `key_risks` or `liability_bullet` entry:\n1. The cited paper's stated conclusion MUST be directionally consistent with the way it is cited. If the paper concluded that an exposure *reduced* a risk, do NOT cite it as evidence FOR that risk \u2014 even if it was historically discussed alongside the risk in regulatory reviews.\n2. When unsure of a paper's directional conclusion, omit the citation and use a different evidence source from the dossier body.\n3. Every NCT cited must appear in the dossier's clinical_development.trials, failed_trials, or analytics.discovery_trials sections AND must have an intervention referencing a drug from drug_interactions. NCTs whose interventions are outside the on-target class (e.g., SGLT2 inhibitors in a GLP-1R dossier) must not be cited.";

package/dist/prompts/target-assessment/briefs/executive-recommendation.js

@@ -41,10 +41,10 @@ dossier in the rationale.
   plausibility only; they do not support tractability, safety, or
   efficacy claims.
 - Do NOT cite trial AEs, efficacy, or termination reasons from
-  \`related_target_trials[]\` as evidence of the assessment target's
-  drug behaviour. These trials are on related receptors (e.g.,
-  CGRP-R/CALCRL for a CALCR assessment) and tell you nothing about the
-  assessment target itself.
+  \`excluded_rows[]\` as evidence of the assessment target's drug
+  behaviour. Those trials are attributed elsewhere — often to a related
+  receptor (e.g., CGRP-R/CALCRL for a CALCR assessment) — and tell you
+  nothing about the assessment target itself.
 - Do NOT interpret a Reactome pathway containing the gene symbol as
   evidence of drug-target binding. Reactome pathways list participating
   genes, not drug interactions. Drug-binding evidence comes from
@@ -61,7 +61,7 @@ dossier in the rationale.
   distinct-substance counts.
 - Do NOT surface organ-level liability claims (kidney, CNS, hepatic,
   cardiac, etc.) unless they appear in
-  \`safety_profile.target_organ_liabilities\`. That section is the
+  \`safety_profile.target_organ_liabilities.data.rows\`. That section is the
   probe-validated source for organ claims; any organ liability the
   probe rejected does not belong in \`key_risks\`.
 - Do NOT recommend a between-cofactor selectivity margin against rows in

package/dist/prompts/target-assessment/briefs/liability-bullets.d.ts

@@ -1 +1 @@
-export declare const liabilityBulletsBrief = "# Section: Liability bullets\n\nWrite evidence-cited liability bullets in toxicologist voice. Each bullet\ncovers one organ-or-axis with severity, the supporting evidence pointer,\nand a rationale that names the mechanism hypothesis.\n\n## Inputs\nYou receive the full Phase-4 dossier as JSON. Cite section paths and\ncounts (FAERS n=NN, IMPC p=...) verbatim from the dossier.\n\n## Approval precedents (provided)\n- FDA approval precedents for the target's candidate indication are\n  supplied in the prompt \u2014 queried once from openFDA / Drugs@FDA (see the\n  `## FDA approval precedents` block). For class precedents not present\n  in the dossier, cite a listed NDA/BLA application number + label section.\n  Do not assert precedents absent from that block and the dossier.\n\n## Output discipline\n- Severity is one of high / medium / low.\n- Each rationale must include either a hedge phrase, a literature\n  citation, or a regulatory reference for every efficacy/safety claim.\n- Do not fabricate counts. If the dossier lacks evidence, mark it\n  explicitly (\"the data do not support a conclusion\") rather than\n  generating filler.\n- Trial AEs, failed-trial reasons, and outcomes may be used as\n  toxicology evidence only when the row has\n  `eligible_for_toxicology_aggregation: true` and\n  `attribution.evidence_role: \"supports_target\"`. Rows marked\n  `contextual` or `excluded` are coverage/context only; do not cite\n  them as safety evidence.\n\n## Category vocabulary\nEach bullet's `category` MUST be exactly one of:\n- `fatal_post_market` \u2014 class-defining contraindication / fatal\n  post-market signal (e.g., anaphylaxis-with-death on a class label).\n  When `safety_profile.regulatory_actions.coverage === \"available\"`, every\n  row in that array is a confirmed regulatory event (EMA referral, FDA\n  safety communication, REMS, withdrawal). Emit one\n  `fatal_post_market` bullet per row, naming the `agency`, `action_date`,\n  and quoting the `finding` verbatim. Do NOT phrase regulatory\n  actions as inferences from FAERS counts.\n- `class_liability` \u2014 formal class-precedent organ liability meeting\n  the 3-drug threshold (sourced from\n  `safety_profile.class_precedent.data.per_organ`).\n- `off_target_safety` \u2014 selectivity-driven liability at a related\n  receptor (sourced from\n  `safety_profile.off_target_panel.data.rows`).\n- `high_safety_organ_expression` \u2014 expression-driven on-target\n  liability at a safety-relevant tissue (sourced from\n  `off_tissue_risk.data.rows` and the\n  `safety_profile.target_organ_liabilities` probe).\n- `broad_expression` \u2014 expression spread across many tissues without a\n  single-organ driver (sourced from\n  `derived.liability_summary.expression_breadth`).\n- `other` \u2014 uncategorisable safety observation worth flagging; use\n  only when none of the above fit.\n\n## Obligate-cofactor rows\n\n`safety_profile.off_target_panel.data.excluded_rows[]` may contain rows\nwith `relationship: \"obligate_cofactor\"`. These represent the\nassessment target heterodimerised with a different obligate accessory\nprotein (e.g., a CALCR/RAMP3 entry on a CALCR assessment is the AMY3\namylin receptor \u2014 same gene product, different RAMP partner).\n\n- Do NOT generate an `off_target_safety` liability bullet for these\n  rows. Selectivity between cofactor partners of the same gene product\n  is not pharmacologically attainable; the protein is the same.\n- Do NOT recommend a between-cofactor selectivity margin (e.g., \"\u2265N-fold\n  over <gene>/RAMP<N>\") against an obligate-cofactor row. The\n  pharmacology is context-dependent on cofactor co-expression in the\n  target tissue, which is an on-target property, not a selectivity\n  property.\n- If the row carries a `clinical_consequence` annotation (e.g.,\n  satiety, nausea), fold that consequence into an\n  `high_safety_organ_expression` or `broad_expression` bullet where\n  the cofactor's tissue distribution makes the engagement clinically\n  relevant. Do not invent a selectivity liability.\n\n## Mechanism-claim discipline\n\nWhen stating a mechanism for an adverse-event signal, the mechanism must operate at the same biological scale as the AE.\n\n- Do NOT cite developmental, regenerative, or homeostatic biology (e.g., satellite-cell quiescence, stem-cell niche maintenance, tissue homeostasis) as the mechanism for a clinical AE signal like arthralgia, myalgia, or fatigue. Those papers describe tissue-level processes, not AE-producing pathways. If the only mechanistic candidate in the dossier is at the tissue-homeostasis level, omit the mechanism claim and report the AE signal alone (the rationale can still cite the AE prevalence number).\n\n- Respect anatomical boundaries. The nucleus tractus solitarius (NTS) is brainstem, not hypothalamus. The nucleus accumbens is basal ganglia, not hypothalamus. The amygdala is subcortical, not hypothalamus. When binning a CNS expression signal under a region category, the region in the rationale must match the region in the dossier source path. Do not conflate \"neural circuit involving X\" with \"expressed in X\" \u2014 the latter is the only on-target claim supported by tissue expression data.\n\n- For `category: \"high_safety_organ_expression\"` bullets, the cited brain region must be one of: hypothalamus, brainstem (medulla / pons / midbrain), cerebellum, basal ganglia (caudate / putamen / nucleus accumbens / globus pallidus), thalamus, hippocampus, amygdala, or cortex (frontal / temporal / parietal / occipital / cingulate). Do not invent new region categories.\n\n### Source counters for bullet rationale\n\nEach bullet rationale MUST cite at least one numeric counter from one of:\n  - safety_profile.faers.data.top_signals[].report_count (preferred when available)\n  - safety_profile.faers.data.per_modulator[].report_count\n  - safety_profile.class_precedent.data.per_organ[].top_aes[].report_count (use when target-level FAERS is queried_no_data)\n  - safety_profile.trial_aes.data.serious[].incidence_pct / non_serious[].incidence_pct\n  - safety_profile.off_target_panel.data.rows[].pchembl with the off_target_name\nA bullet that cites a numeric counter from class_precedent.per_organ.top_aes.report_count is valid;\ndo NOT delete it for \"no source\" if a class_precedent counter is present.\n\n### Tissue-expression unit discipline\n\nWhen citing tissue-expression values, ALWAYS use the unit string from `reference_biology.normal_tissue_expression.data.unit` (one of: \"tpm\",\n\"ntpm\", \"consensus_normalized\"). Do not assume \"TPM\" \u2014 Open Targets'\nhpa_consensus source emits \"consensus_normalized\" (nTPM-like).\nRender as e.g. \"217 nTPM\" or \"217 (consensus_normalized)\", never \"217 TPM\"\nunless the unit field is \"tpm\".\n\n### Citation discipline\n\nWhen citing a PMID inside a `key_risks` or `liability_bullet` entry:\n1. The cited paper's stated conclusion MUST be directionally consistent with the way it is cited. If the paper concluded that an exposure *reduced* a risk, do NOT cite it as evidence FOR that risk \u2014 even if it was historically discussed alongside the risk in regulatory reviews.\n2. When unsure of a paper's directional conclusion, omit the citation and use a different evidence source from the dossier body.\n3. Every NCT cited must appear in the dossier's clinical_development.trials, failed_trials, or analytics.discovery_trials sections AND must have an intervention referencing a drug from drug_interactions. NCTs whose interventions are outside the on-target class (e.g., SGLT2 inhibitors in a GLP-1R dossier) must not be cited.";
+export declare const liabilityBulletsBrief = "# Section: Liability bullets\n\nWrite evidence-cited liability bullets in toxicologist voice. Each bullet\ncovers one organ-or-axis with severity, the supporting evidence pointer,\nand a rationale that names the mechanism hypothesis.\n\n## Inputs\nYou receive the full Phase-4 dossier as JSON. Cite section paths and\ncounts (FAERS n=NN, IMPC p=...) verbatim from the dossier.\n\n## Approval precedents (provided)\n- FDA approval precedents for the target's candidate indication are\n  supplied in the prompt \u2014 queried once from openFDA / Drugs@FDA (see the\n  `## FDA approval precedents` block). For class precedents not present\n  in the dossier, cite a listed NDA/BLA application number + label section.\n  Do not assert precedents absent from that block and the dossier.\n\n## Output discipline\n- Severity is one of high / medium / low.\n- Each rationale must include either a hedge phrase, a literature\n  citation, or a regulatory reference for every efficacy/safety claim.\n- Do not fabricate counts. If the dossier lacks evidence, mark it\n  explicitly (\"the data do not support a conclusion\") rather than\n  generating filler.\n- Trial AEs, failed-trial reasons, and outcomes may be used as\n  toxicology evidence only when the row has\n  `eligible_for_toxicology_aggregation: true` and\n  `attribution.evidence_role: \"supports_target\"`. Rows marked\n  `contextual` or `excluded` are coverage/context only; do not cite\n  them as safety evidence.\n\n## Category vocabulary\nEach bullet's `category` MUST be exactly one of:\n- `fatal_post_market` \u2014 class-defining contraindication / fatal\n  post-market signal (e.g., anaphylaxis-with-death on a class label).\n  When `safety_profile.regulatory_actions.coverage === \"available\"`, every\n  row in that array is a confirmed regulatory event (EMA referral, FDA\n  safety communication, REMS, withdrawal). Emit one\n  `fatal_post_market` bullet per row, naming the `agency`, `action_date`,\n  and quoting the `finding` verbatim. Do NOT phrase regulatory\n  actions as inferences from FAERS counts.\n- `class_liability` \u2014 formal class-precedent organ liability meeting\n  the 3-drug threshold (sourced from\n  `safety_profile.class_precedent.data.per_organ`).\n- `off_target_safety` \u2014 selectivity-driven liability at a related\n  receptor (sourced from\n  `safety_profile.off_target_panel.data.rows`).\n- `high_safety_organ_expression` \u2014 expression-driven on-target\n  liability at a safety-relevant tissue (sourced from\n  `off_tissue_risk.data.rows` and the\n  `safety_profile.target_organ_liabilities.data.rows` probe).\n- `broad_expression` \u2014 expression spread across many tissues without a\n  single-organ driver (sourced from\n  `derived.liability_summary.expression_breadth`).\n- `other` \u2014 uncategorisable safety observation worth flagging; use\n  only when none of the above fit.\n\n## Obligate-cofactor rows\n\n`safety_profile.off_target_panel.data.excluded_rows[]` may contain rows\nwith `relationship: \"obligate_cofactor\"`. These represent the\nassessment target heterodimerised with a different obligate accessory\nprotein (e.g., a CALCR/RAMP3 entry on a CALCR assessment is the AMY3\namylin receptor \u2014 same gene product, different RAMP partner).\n\n- Do NOT generate an `off_target_safety` liability bullet for these\n  rows. Selectivity between cofactor partners of the same gene product\n  is not pharmacologically attainable; the protein is the same.\n- Do NOT recommend a between-cofactor selectivity margin (e.g., \"\u2265N-fold\n  over <gene>/RAMP<N>\") against an obligate-cofactor row. The\n  pharmacology is context-dependent on cofactor co-expression in the\n  target tissue, which is an on-target property, not a selectivity\n  property.\n- If the row carries a `clinical_consequence` annotation (e.g.,\n  satiety, nausea), fold that consequence into an\n  `high_safety_organ_expression` or `broad_expression` bullet where\n  the cofactor's tissue distribution makes the engagement clinically\n  relevant. Do not invent a selectivity liability.\n\n## Mechanism-claim discipline\n\nWhen stating a mechanism for an adverse-event signal, the mechanism must operate at the same biological scale as the AE.\n\n- Do NOT cite developmental, regenerative, or homeostatic biology (e.g., satellite-cell quiescence, stem-cell niche maintenance, tissue homeostasis) as the mechanism for a clinical AE signal like arthralgia, myalgia, or fatigue. Those papers describe tissue-level processes, not AE-producing pathways. If the only mechanistic candidate in the dossier is at the tissue-homeostasis level, omit the mechanism claim and report the AE signal alone (the rationale can still cite the AE prevalence number).\n\n- Respect anatomical boundaries. The nucleus tractus solitarius (NTS) is brainstem, not hypothalamus. The nucleus accumbens is basal ganglia, not hypothalamus. The amygdala is subcortical, not hypothalamus. When binning a CNS expression signal under a region category, the region in the rationale must match the region in the dossier source path. Do not conflate \"neural circuit involving X\" with \"expressed in X\" \u2014 the latter is the only on-target claim supported by tissue expression data.\n\n- For `category: \"high_safety_organ_expression\"` bullets, the cited brain region must be one of: hypothalamus, brainstem (medulla / pons / midbrain), cerebellum, basal ganglia (caudate / putamen / nucleus accumbens / globus pallidus), thalamus, hippocampus, amygdala, or cortex (frontal / temporal / parietal / occipital / cingulate). Do not invent new region categories.\n\n### Source counters for bullet rationale\n\nEach bullet rationale MUST cite at least one numeric counter from one of:\n  - safety_profile.faers.data.top_signals[].report_count (preferred when available)\n  - safety_profile.faers.data.per_modulator[].report_count\n  - safety_profile.class_precedent.data.per_organ[].top_aes[].report_count (use when target-level FAERS is queried_no_data)\n  - safety_profile.trial_aes.data.serious[].incidence_pct / non_serious[].incidence_pct\n  - safety_profile.off_target_panel.data.rows[].pchembl with the off_target_name\nA bullet that cites a numeric counter from class_precedent.per_organ.top_aes.report_count is valid;\ndo NOT delete it for \"no source\" if a class_precedent counter is present.\n\n### Tissue-expression unit discipline\n\nWhen citing tissue-expression values, ALWAYS use the unit string from `reference_biology.normal_tissue_expression.data.unit` (one of: \"tpm\",\n\"ntpm\", \"consensus_normalized\"). Do not assume \"TPM\" \u2014 Open Targets'\nhpa_consensus source emits \"consensus_normalized\" (nTPM-like).\nRender as e.g. \"217 nTPM\" or \"217 (consensus_normalized)\", never \"217 TPM\"\nunless the unit field is \"tpm\".\n\n### Citation discipline\n\nWhen citing a PMID inside a `key_risks` or `liability_bullet` entry:\n1. The cited paper's stated conclusion MUST be directionally consistent with the way it is cited. If the paper concluded that an exposure *reduced* a risk, do NOT cite it as evidence FOR that risk \u2014 even if it was historically discussed alongside the risk in regulatory reviews.\n2. When unsure of a paper's directional conclusion, omit the citation and use a different evidence source from the dossier body.\n3. Every NCT cited must appear in the dossier's clinical_development.trials, failed_trials, or analytics.discovery_trials sections AND must have an intervention referencing a drug from drug_interactions. NCTs whose interventions are outside the on-target class (e.g., SGLT2 inhibitors in a GLP-1R dossier) must not be cited.";

package/dist/prompts/target-assessment/briefs/liability-bullets.js

@@ -48,7 +48,7 @@ Each bullet's \`category\` MUST be exactly one of:
 - \`high_safety_organ_expression\` — expression-driven on-target
   liability at a safety-relevant tissue (sourced from
   \`off_tissue_risk.data.rows\` and the
-  \`safety_profile.target_organ_liabilities\` probe).
+  \`safety_profile.target_organ_liabilities.data.rows\` probe).
 - \`broad_expression\` — expression spread across many tissues without a
   single-organ driver (sourced from
   \`derived.liability_summary.expression_breadth\`).

package/dist/prompts/target-assessment/briefs/target-organ-liabilities.d.ts

@@ -1 +1 @@
-export declare const targetOrganLiabilitiesBrief = "# Section: Target-organ liabilities (audit trail)\n\nFor each implicated organ system, write a per-organ trail that connects\ngenetic, expression, FAERS, and class-precedent evidence to a stated\nmechanism hypothesis.\n\n## Inputs\nYou receive the full Phase-4 dossier as JSON. Cite section paths and\ncounts verbatim. Anchor every organ name to the canonical\norgan-system vocabulary (hepatobiliary, renal, cardiac, etc.) \u2014 colloquial\nsubstitutes are rejected by the voice probe.\n\n## Approval precedents (provided)\n- FDA approval precedents for the candidate indication are supplied in the\n  prompt (see the `## FDA approval precedents` block). For class\n  precedents withdrawn or labelled for the same liability, cite a listed\n  Drugs@FDA NDA/BLA \u00A7<section>. Do not assert precedents absent from that block.\n\n## Output discipline\n- Trail format is study-summary cadence: claim, evidence with counts,\n  qualifier on human relevance.\n- Mechanism hypothesis can be null if the data do not support one \u2014 say\n  so rather than guessing.\n- Trial AEs, failed-trial reasons, and outcomes may be used as\n  organ-liability evidence only when the row has\n  `eligible_for_toxicology_aggregation: true` and\n  `attribution.evidence_role: \"supports_target\"`. Rows marked\n  `contextual` or `excluded` are coverage/context only; do not cite\n  them as safety evidence.";
+export declare const targetOrganLiabilitiesBrief: string;

package/dist/prompts/target-assessment/briefs/target-organ-liabilities.js

@@ -1,3 +1,7 @@
+import { ORGAN_SYSTEMS } from "../../../contracts/organ-system.js";
+// Interpolated rather than restated, so the prompt cannot name an organ the
+// schema will reject.
+const organTokens = ORGAN_SYSTEMS.join(", ");
 export const targetOrganLiabilitiesBrief = `# Section: Target-organ liabilities (audit trail)
 
 For each implicated organ system, write a per-organ trail that connects
@@ -6,9 +10,9 @@ mechanism hypothesis.
 
 ## Inputs
 You receive the full Phase-4 dossier as JSON. Cite section paths and
-counts verbatim. Anchor every organ name to the canonical
-organ-system vocabulary (hepatobiliary, renal, cardiac, etc.) — colloquial
-substitutes are rejected by the voice probe.
+counts verbatim. The \`organ\` field of every row MUST be exactly one of
+these tokens: ${organTokens}. Anything else is rejected. Trail prose may
+use the reader-facing name for that organ; the \`organ\` field may not.
 
 ## Approval precedents (provided)
 - FDA approval precedents for the candidate indication are supplied in the
@@ -19,6 +23,10 @@ substitutes are rejected by the voice probe.
 ## Output discipline
 - Trail format is study-summary cadence: claim, evidence with counts,
   qualifier on human relevance.
+- \`severity\` is your own read of the liability for that organ — \`high\`,
+  \`medium\`, or \`low\` — and must follow from the trail you wrote.
+- Cite a PMID inline (\`PMID:12345678\`) for every literature claim in the
+  trail; a trail that cites none is recorded as having no citable support.
 - Mechanism hypothesis can be null if the data do not support one — say
   so rather than guessing.
 - Trial AEs, failed-trial reasons, and outcomes may be used as

package/dist/prompts/target-assessment/investigation/adversarial-critique.d.ts

@@ -0,0 +1 @@
+export declare const adversarialCritiquePrompt = "You are the adversarial critic in a target-assessment claim investigation.\n\nYou are handed one organ liability claim about an assessed target, the mechanism\nproposed for it, and the evidence the assessment collected for that organ. Your\njob is to argue that the claim does NOT hold.\n\nYou are not a reviewer and you are not a second opinion. Nobody is asking you\nwhether the claim looks reasonable. Build the strongest available case against\nit, and then say how strong that case actually turned out to be.\n\n## Where a claim breaks\n\nWork through the ways a corroborated organ signal can still be wrong:\n\n- **Correlated sources.** Several sources agreeing is only evidence when they are\n  independent. Curated databases routinely re-import the same primary study.\n- **Species and model.** A knockout phenotype in a mouse is not a human organ\n  liability, and a whole-body knockout is not pharmacological inhibition.\n- **Confounded clinical signal.** Adverse events attributed to a drug can belong\n  to the indication, the comorbidity, the co-medication, or the trial population.\n- **Expression is not consequence.** Presence in a tissue does not establish that\n  modulating the target there produces harm.\n- **Wrong scale.** A mechanism drawn from developmental or homeostatic biology\n  does not explain an acute clinical event.\n- **Direction.** A cited paper may conclude the opposite of the way it is used.\n- **Better explanation.** Something other than the target may account for the\n  signal \u2014 an off-target, a metabolite, a class effect, a formulation.\n\n## How to work\n\nSearch the literature for records that would disconfirm the claim: contradicting\nfindings, negative results, reanalyses, populations where the effect is absent.\nUse the tools you were given. Read enough of a hit to know what it concluded\nbefore you cite it \u2014 a title is not a conclusion.\n\nIf a search returns nothing useful, that is information: it means the objection\nyou were building has no published support, and you should say that rather than\nassert it anyway.\n\n## Finishing\n\nReport your outcome by calling `record_critique` exactly once. Prose replies are\ndiscarded \u2014 a critique that is not recorded through that tool did not happen.\n\nIts `support` carries your counter-evidence:\n\n- Use `scored` only with records you actually retrieved, each carrying a real\n  publication identifier, digital object identifier, or accession.\n- Use `unknown` with a one-line reason whenever you could not find such a\n  record. This is a complete and expected answer, and it is always the right one\n  when the alternative is a citation you are not sure of. An objection with\n  unknown support is still recorded and still read.\n\n## Do NOT\n\n- Do NOT endorse the claim. If the case against it is weak, say the case is weak\n  \u2014 do not convert your turn into a confirmation.\n- Do NOT invent a publication identifier, accession, or trial number, and do not\n  cite one from memory that you did not retrieve in this run.\n- Do NOT report support as `scored` while noting in the objection that the\n  evidence is indirect. Indirect is `unknown` with that as the reason.\n- Do NOT object on grounds you cannot state concretely. \"The evidence is limited\"\n  is not an objection; \"the three contributing sources all trace to one 2011\n  curation of the same cohort\" is.\n- Do NOT raise an objection about a different organ than the one you were given.\n- Do NOT assume anything about what ran before you or what will run after, and do\n  not ask for more context \u2014 argue from what you were handed plus what you find.";

package/dist/prompts/target-assessment/investigation/adversarial-critique.js

@@ -0,0 +1,67 @@
+export const adversarialCritiquePrompt = `You are the adversarial critic in a target-assessment claim investigation.
+
+You are handed one organ liability claim about an assessed target, the mechanism
+proposed for it, and the evidence the assessment collected for that organ. Your
+job is to argue that the claim does NOT hold.
+
+You are not a reviewer and you are not a second opinion. Nobody is asking you
+whether the claim looks reasonable. Build the strongest available case against
+it, and then say how strong that case actually turned out to be.
+
+## Where a claim breaks
+
+Work through the ways a corroborated organ signal can still be wrong:
+
+- **Correlated sources.** Several sources agreeing is only evidence when they are
+  independent. Curated databases routinely re-import the same primary study.
+- **Species and model.** A knockout phenotype in a mouse is not a human organ
+  liability, and a whole-body knockout is not pharmacological inhibition.
+- **Confounded clinical signal.** Adverse events attributed to a drug can belong
+  to the indication, the comorbidity, the co-medication, or the trial population.
+- **Expression is not consequence.** Presence in a tissue does not establish that
+  modulating the target there produces harm.
+- **Wrong scale.** A mechanism drawn from developmental or homeostatic biology
+  does not explain an acute clinical event.
+- **Direction.** A cited paper may conclude the opposite of the way it is used.
+- **Better explanation.** Something other than the target may account for the
+  signal — an off-target, a metabolite, a class effect, a formulation.
+
+## How to work
+
+Search the literature for records that would disconfirm the claim: contradicting
+findings, negative results, reanalyses, populations where the effect is absent.
+Use the tools you were given. Read enough of a hit to know what it concluded
+before you cite it — a title is not a conclusion.
+
+If a search returns nothing useful, that is information: it means the objection
+you were building has no published support, and you should say that rather than
+assert it anyway.
+
+## Finishing
+
+Report your outcome by calling \`record_critique\` exactly once. Prose replies are
+discarded — a critique that is not recorded through that tool did not happen.
+
+Its \`support\` carries your counter-evidence:
+
+- Use \`scored\` only with records you actually retrieved, each carrying a real
+  publication identifier, digital object identifier, or accession.
+- Use \`unknown\` with a one-line reason whenever you could not find such a
+  record. This is a complete and expected answer, and it is always the right one
+  when the alternative is a citation you are not sure of. An objection with
+  unknown support is still recorded and still read.
+
+## Do NOT
+
+- Do NOT endorse the claim. If the case against it is weak, say the case is weak
+  — do not convert your turn into a confirmation.
+- Do NOT invent a publication identifier, accession, or trial number, and do not
+  cite one from memory that you did not retrieve in this run.
+- Do NOT report support as \`scored\` while noting in the objection that the
+  evidence is indirect. Indirect is \`unknown\` with that as the reason.
+- Do NOT object on grounds you cannot state concretely. "The evidence is limited"
+  is not an objection; "the three contributing sources all trace to one 2011
+  curation of the same cohort" is.
+- Do NOT raise an objection about a different organ than the one you were given.
+- Do NOT assume anything about what ran before you or what will run after, and do
+  not ask for more context — argue from what you were handed plus what you find.`;

package/dist/prompts/target-assessment/investigation/claim-reverification.d.ts

@@ -0,0 +1 @@
+export declare const claimReverificationBrief = "# Task: re-verify one organ liability claim\n\nYou are given a corroborated organ liability claim, the mechanism proposed for\nit, the objection raised against it, and the evidence the assessment collected\nfor that organ. Decide what survives.\n\nYou are adjudicating, not summarising. Weigh the objection against the evidence\nand say which of them the record actually supports.\n\n## The verdict vocabulary\n\n- `upheld` \u2014 the objection was answered by the evidence, and the claim stands as\n  proposed.\n- `weakened` \u2014 the objection lands, but the claim is not eliminated: it holds in\n  a narrower form, or with lower confidence in its mechanism.\n- `overturned` \u2014 the objection is decisive; the evidence does not support the\n  claim as stated.\n- `undetermined` \u2014 the record settles neither side. This is a real verdict, not a\n  refusal to answer, and it is correct whenever the evidence is genuinely silent.\n\nThe verdict is your read of the record in words. There is no score, no\nthreshold, and no arithmetic \u2014 do not attempt to derive one, and do not describe\nthe claim as passing or failing a bar.\n\nNothing you return removes a claim from the assessment. An `overturned` verdict\nis recorded and read; it does not delete the organ, and you should therefore\nnever soften a verdict to protect a liability from disappearing.\n\n## Support for the verdict\n\nCite the records that carry your verdict \u2014 the ones you actually relied on, from\nthe evidence you were given or from the objection's counter-evidence.\n\nIf nothing in the record carries the verdict, return support state `unknown`\nwith a one-line reason. That is a complete answer, expected often, and always\npreferable to a locator you are not certain of. The verdict itself is still\nrecorded.\n\n## Do NOT\n\n- Do NOT cite a publication identifier, accession, or regulatory reference that\n  was not in the material you were given.\n- Do NOT report support as `scored` while noting the evidence is thin. Thin is\n  `unknown` with that as the reason.\n- Do NOT restate the objection as the verdict. Say what the record supports.\n- Do NOT return `upheld` merely because the claim was corroborated by several\n  sources \u2014 whether those sources are independent is exactly what the objection\n  may be contesting.\n- Do NOT assume anything about what ran before you or what will run after.";