agent-bober 0.17.1 → 0.19.0

package/dist/medical/retrieval/grounding-critic.d.ts

@@ -0,0 +1,34 @@
+/** GroundingCritic — fail-closed faithfulness+completeness judge for medical synthesis output. */
+import { z } from "zod";
+import type { LLMClient } from "../../providers/types.js";
+import type { Passage } from "./medline-source.js";
+export declare const GROUNDING_PARSE_MAX_RETRIES = 1;
+export declare const GROUNDING_MAX_LLM_CALLS: number;
+export declare const GroundingVerdictSchema: z.ZodObject<{
+    verdict: z.ZodEnum<["approve", "reject"]>;
+    feedback: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    feedback: string;
+    verdict: "approve" | "reject";
+}, {
+    feedback: string;
+    verdict: "approve" | "reject";
+}>;
+export type GroundingVerdict = z.infer<typeof GroundingVerdictSchema>;
+export type ValidateGroundingResult = {
+    ok: true;
+    verdict: GroundingVerdict;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateGroundingVerdict(rawText: string): ValidateGroundingResult;
+export declare function buildGroundingSystemPrompt(question: string, answerBody: string, passages: Passage[]): string;
+export declare function getGroundingVerdict(input: {
+    llm: LLMClient;
+    model: string;
+    question: string;
+    answerBody: string;
+    passages: Passage[];
+}): Promise<GroundingVerdict>;
+//# sourceMappingURL=grounding-critic.d.ts.map

package/dist/medical/retrieval/grounding-critic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-critic.d.ts","sourceRoot":"","sources":["../../../src/medical/retrieval/grounding-critic.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAkBvE,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAIjC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CAgDjF;AAYD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAeR;AAmDD,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+B5B"}

package/dist/medical/retrieval/grounding-critic.js

@@ -0,0 +1,153 @@
+/** GroundingCritic — fail-closed faithfulness+completeness judge for medical synthesis output. */
+import { z } from "zod";
+// ── Constants ────────────────────────────────────────────────────────
+export const GROUNDING_PARSE_MAX_RETRIES = 1;
+export const GROUNDING_MAX_LLM_CALLS = 1 + GROUNDING_PARSE_MAX_RETRIES;
+// ── Prompts ──────────────────────────────────────────────────────────
+const GROUNDING_COERCION_INSTRUCTION = `Your previous response was not a valid grounding verdict.
+Output ONLY a single JSON object (no prose, no markdown fences, no tool calls) with EXACTLY this shape:
+{
+  "verdict": "approve" | "reject",
+  "feedback": "<concise feedback; empty string if approving>"
+}
+
+Rules:
+- "verdict" must be exactly "approve" or "reject".
+- "feedback" must be a string.
+- Output the JSON object and nothing else.`;
+// ── Schema + types ───────────────────────────────────────────────────
+export const GroundingVerdictSchema = z.object({
+    verdict: z.enum(["approve", "reject"]),
+    feedback: z.string(),
+});
+// ── validateGroundingVerdict (NEVER throws) ──────────────────────────
+export function validateGroundingVerdict(rawText) {
+    let parsed;
+    // Try direct parse first
+    try {
+        parsed = JSON.parse(rawText.trim());
+    }
+    catch {
+        // Try extracting JSON from markdown code fences
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(rawText);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // Try finding the first { ... } block
+        if (!parsed) {
+            const braceStart = rawText.indexOf("{");
+            const braceEnd = rawText.lastIndexOf("}");
+            if (braceStart !== -1 && braceEnd > braceStart) {
+                try {
+                    parsed = JSON.parse(rawText.slice(braceStart, braceEnd + 1));
+                }
+                catch {
+                    return {
+                        ok: false,
+                        error: `No valid JSON object found in response. Raw: ${rawText.slice(0, 200)}`,
+                    };
+                }
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `No JSON object found in response. Raw: ${rawText.slice(0, 200)}`,
+                };
+            }
+        }
+    }
+    const result = GroundingVerdictSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        return { ok: false, error: issues };
+    }
+    return { ok: true, verdict: result.data };
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function formatPassageBlock(passages) {
+    return passages
+        .map((p, i) => `[${i + 1}] ${p.title}\n${p.text}\nSource: ${p.url}`)
+        .join("\n\n");
+}
+// ── buildGroundingSystemPrompt ────────────────────────────────────────
+export function buildGroundingSystemPrompt(question, answerBody, passages) {
+    const passageBlock = formatPassageBlock(passages);
+    return (`You are an independent reviewer. The answer below was produced by another assistant ` +
+        `from ONLY the retrieved passages listed here. ` +
+        `Approve ONLY if EVERY claim in the answer is directly supported by a cited passage ` +
+        `AND the answer addresses the core of the question. ` +
+        `Reject if any claim is unsupported (faithfulness) OR the answer omits the central part ` +
+        `of the question (completeness). ` +
+        `Output ONLY {"verdict":"approve"|"reject","feedback":"..."}\n\n` +
+        `Question: ${question}\n\n` +
+        `Answer to review:\n${answerBody}\n\n` +
+        `Retrieved passages:\n${passageBlock}`);
+}
+// ── Internal: one grounding-critic call ─────────────────────────────
+async function callGroundingCritic(input) {
+    const { llm, model, question, answerBody, passages, priorText, formattedError } = input;
+    // Fresh message array — NEVER extends the prior synthesis conversation (LOCK1)
+    const firstUserContent = `Review this answer as an independent reviewer.\n\n` +
+        `Question: ${question}\n\n` +
+        `Answer to review:\n${answerBody}\n\n` +
+        `Cited passages:\n${formatPassageBlock(passages)}`;
+    let messages;
+    if (priorText !== undefined && formattedError !== undefined) {
+        // Coercion retry: 3-message shape [user, assistant, user]
+        messages = [
+            { role: "user", content: firstUserContent },
+            { role: "assistant", content: priorText },
+            {
+                role: "user",
+                content: `${GROUNDING_COERCION_INSTRUCTION}\n\nPrevious validation error:\n${formattedError}`,
+            },
+        ];
+    }
+    else {
+        // First turn: single user message
+        messages = [{ role: "user", content: firstUserContent }];
+    }
+    const response = await llm.chat({
+        model,
+        system: buildGroundingSystemPrompt(question, answerBody, passages),
+        messages,
+        jsonObjectMode: true,
+    });
+    return response.text;
+}
+// ── getGroundingVerdict (FAIL-CLOSED on parse exhaustion) ────────────
+export async function getGroundingVerdict(input) {
+    const { llm, model, question, answerBody, passages } = input;
+    const maxAttempts = GROUNDING_MAX_LLM_CALLS;
+    let lastError = "Unknown error";
+    let priorText;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const rawText = await callGroundingCritic({
+            llm,
+            model,
+            question,
+            answerBody,
+            passages,
+            priorText: attempt > 0 ? priorText : undefined,
+            formattedError: attempt > 0 ? lastError : undefined,
+        });
+        const validated = validateGroundingVerdict(rawText);
+        if (validated.ok) {
+            return validated.verdict;
+        }
+        lastError = validated.error;
+        priorText = rawText;
+    }
+    // FAIL-CLOSED inversion of critic-deep.ts:199-201 (which returns approve on exhaustion).
+    // bober: reject on parse exhaustion; this is intentional for medical safety — Sprint 2
+    //        maps a reject to re-synthesis / abstain rather than letting an unverified answer through.
+    return { verdict: "reject", feedback: "<unparseable critic output>" };
+}
+//# sourceMappingURL=grounding-critic.js.map

package/dist/medical/retrieval/grounding-critic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-critic.js","sourceRoot":"","sources":["../../../src/medical/retrieval/grounding-critic.ts"],"names":[],"mappings":"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"}

package/dist/medical/retrieval/literature.d.ts

@@ -0,0 +1,78 @@
+/** LiteratureRetriever — checks the literature-retrieval axis; returns {disabled} sync when off (ADR-6). */
+import type { EgressGuard } from "../egress.js";
+import { MedlineSource, type RetrievalOutcome } from "./medline-source.js";
+import type { LLMClient } from "../../providers/types.js";
+import type { MedicalAnswer, CriticVerdict } from "../types.js";
+/**
+ * Orchestrates literature retrieval behind the literature-retrieval egress gate.
+ *
+ * SYNCHRONOUS short-circuit: if the axis is off, return {disabled} — NO network
+ * attempt and NO MedlineSource method is called. This is the zero-egress proof.
+ */
+export declare class LiteratureRetriever {
+    private readonly egress;
+    private readonly source;
+    constructor(egress: EgressGuard, source?: MedlineSource);
+    /**
+     * Retrieve literature passages for the given query.
+     *
+     * When literature-retrieval is OFF: returns { kind: "disabled" } IMMEDIATELY,
+     * before MedlineSource is consulted — guarantees zero outbound bytes.
+     *
+     * When literature-retrieval is ON: delegates to MedlineSource.fetchPassages.
+     * Any throw from the source is caught and maps to abstain{source-error} (belt-and-braces;
+     * MedlineSource.fetchPassages itself is already fail-closed).
+     */
+    retrieve(query: string): Promise<RetrievalOutcome>;
+}
+/** Return type for synthesizeGrounded — widens MedicalAnswer with the critic gate verdict (Sprint 3). */
+export interface GroundedResult {
+    answer: MedicalAnswer;
+    verdict: CriticVerdict;
+}
+/**
+ * synthesize — single LLM call that grounds the answer in retrieved passages.
+ *
+ * Rules (non-negotiable, enforced here):
+ * - disabled/abstain outcome => abstained MedicalAnswer, citations: [], no clinical assertion.
+ * - grounded outcome => one llm.chat call; if the model abstains or returns empty => abstained.
+ * - Every non-abstained answer carries >= 1 citation derived from the passages.
+ * - LLM error (e.g. Ollama unreachable) => abstained + "model unavailable" footer, NO cloud fallback.
+ * - Never emits an uncited clinical claim.
+ *
+ * @param query - The original user question.
+ * @param outcome - The RetrievalOutcome from LiteratureRetriever.retrieve.
+ * @param llm - Injectable LLMClient (tests pass {chat: vi.fn()}).
+ * @param footer - DisclaimerComposer footer string included in every answer.
+ * @param model - Model identifier to use for synthesis (default: SYNTHESIS_MODEL).
+ */
+export declare function synthesize(query: string, outcome: RetrievalOutcome, llm: LLMClient, footer: string, model?: string): Promise<MedicalAnswer>;
+/**
+ * Worst-case LLM call budget for the grounded gate:
+ *   1 synth + GROUNDING_MAX_LLM_CALLS critic + 1 re-synth + GROUNDING_MAX_LLM_CALLS re-critic
+ * Computed from the imported constant so it tracks future changes to the critic budget.
+ */
+export declare const GROUNDED_GATE_MAX_LLM_CALLS: number;
+/**
+ * synthesizeGrounded — fail-closed gate: synthesize → critic → one re-synth → abstain.
+ *
+ * For non-grounded outcomes, delegates to synthesize (disabled/abstain handled there).
+ * For grounded outcomes:
+ *   1. synthesize → if abstained, return it
+ *   2. getGroundingVerdict → if approve, return answer
+ *   3. synthesizeWithFeedback (one re-synth with critic feedback)
+ *   4. getGroundingVerdict again → if approve, return re-synth answer
+ *   5. else → return abstainAnswer (fail-closed)
+ *
+ * Any thrown error from synthesize or the critic maps to abstainAnswer (fail-closed).
+ * Bounded by GROUNDED_GATE_MAX_LLM_CALLS (= 6 worst case today).
+ *
+ * Returns { answer, verdict } where verdict is one of:
+ *   'approve'          — gate returned an approved answer
+ *   'reject-abstained' — gate abstained after a critic reject (second reject)
+ *   'error-abstained'  — gate abstained due to a thrown error or model unavailable
+ *
+ * @param model - Model identifier to use (default: SYNTHESIS_MODEL for back-compat).
+ */
+export declare function synthesizeGrounded(query: string, outcome: RetrievalOutcome, llm: LLMClient, footer: string, model?: string): Promise<GroundedResult>;
+//# sourceMappingURL=literature.d.ts.map

package/dist/medical/retrieval/literature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literature.d.ts","sourceRoot":"","sources":["../../../src/medical/retrieval/literature.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAgB,MAAM,qBAAqB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAY,aAAa,EAAE,MAAM,aAAa,CAAC;AAK1E;;;;;GAKG;AACH,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,MAAM,EAAE,WAAW,EACnB,MAAM,gBAA4B;IAGrD;;;;;;;;;OASG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAWzD;AAQD,yGAAyG;AACzG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;CACxB;AAqCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAwB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA0ExB;AAID;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QACmB,CAAC;AA0D5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAwB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAyDzB"}

package/dist/medical/retrieval/literature.js

@@ -0,0 +1,292 @@
+import { MedlineSource } from "./medline-source.js";
+import { getGroundingVerdict, GROUNDING_MAX_LLM_CALLS } from "./grounding-critic.js";
+// ── LiteratureRetriever ──────────────────────────────────────────────
+/**
+ * Orchestrates literature retrieval behind the literature-retrieval egress gate.
+ *
+ * SYNCHRONOUS short-circuit: if the axis is off, return {disabled} — NO network
+ * attempt and NO MedlineSource method is called. This is the zero-egress proof.
+ */
+export class LiteratureRetriever {
+    egress;
+    source;
+    constructor(egress, source = new MedlineSource(egress)) {
+        this.egress = egress;
+        this.source = source;
+    }
+    /**
+     * Retrieve literature passages for the given query.
+     *
+     * When literature-retrieval is OFF: returns { kind: "disabled" } IMMEDIATELY,
+     * before MedlineSource is consulted — guarantees zero outbound bytes.
+     *
+     * When literature-retrieval is ON: delegates to MedlineSource.fetchPassages.
+     * Any throw from the source is caught and maps to abstain{source-error} (belt-and-braces;
+     * MedlineSource.fetchPassages itself is already fail-closed).
+     */
+    async retrieve(query) {
+        // isAllowed check MUST precede source call — proves zero-egress when axis is off.
+        if (!this.egress.isAllowed("literature-retrieval")) {
+            return { kind: "disabled" };
+        }
+        try {
+            return await this.source.fetchPassages(query);
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" };
+        }
+    }
+}
+// ── synthesize ───────────────────────────────────────────────────────
+const SYNTHESIS_MODEL = "ollama/llama3";
+const SYNTHESIS_MAX_TOKENS = 512;
+/**
+ * Build the system prompt that pins the model to the retrieved passages.
+ * The model is instructed to reply with exactly "ABSTAIN" if the passages
+ * do not support the query — synthesize treats that as an abstain signal.
+ */
+function buildSynthesisSystem(passages) {
+    const passageBlock = passages
+        .map((p, i) => `[${i + 1}] ${p.title}\n${p.text}\nSource: ${p.url}`)
+        .join("\n\n");
+    return ("You are a medical information assistant. Answer the user's question using ONLY " +
+        "the following retrieved passages from MedlinePlus. " +
+        "If the passages do not contain information that supports a specific answer, " +
+        "reply with exactly the single word: ABSTAIN\n\n" +
+        "Retrieved passages:\n" +
+        passageBlock);
+}
+/**
+ * Derive citations from grounded passages that were actually used in synthesis.
+ * For simplicity (all passages are pinned in the system prompt), all passages
+ * become citations when the model produces a non-abstained answer.
+ * This ensures citations.length >= 1 for every non-abstained answer.
+ */
+function passagesToCitations(passages) {
+    return passages.map((p) => ({
+        title: p.title,
+        url: p.url,
+        source: "medlineplus",
+    }));
+}
+/**
+ * synthesize — single LLM call that grounds the answer in retrieved passages.
+ *
+ * Rules (non-negotiable, enforced here):
+ * - disabled/abstain outcome => abstained MedicalAnswer, citations: [], no clinical assertion.
+ * - grounded outcome => one llm.chat call; if the model abstains or returns empty => abstained.
+ * - Every non-abstained answer carries >= 1 citation derived from the passages.
+ * - LLM error (e.g. Ollama unreachable) => abstained + "model unavailable" footer, NO cloud fallback.
+ * - Never emits an uncited clinical claim.
+ *
+ * @param query - The original user question.
+ * @param outcome - The RetrievalOutcome from LiteratureRetriever.retrieve.
+ * @param llm - Injectable LLMClient (tests pass {chat: vi.fn()}).
+ * @param footer - DisclaimerComposer footer string included in every answer.
+ * @param model - Model identifier to use for synthesis (default: SYNTHESIS_MODEL).
+ */
+export async function synthesize(query, outcome, llm, footer, model = SYNTHESIS_MODEL) {
+    // ── Abstain immediately on disabled / no-passages ────────────────
+    if (outcome.kind === "disabled" || outcome.kind === "abstain") {
+        return {
+            body: "I cannot ground an answer in retrieved literature. " +
+                "For evidence-based guidance, please consult a licensed healthcare professional.",
+            abstained: true,
+            citations: [],
+            disclaimerFooter: footer,
+            shortCircuit: false,
+        };
+    }
+    // outcome.kind === "grounded"
+    const passages = outcome.passages;
+    if (passages.length === 0) {
+        return {
+            body: "No supporting passages were retrieved. " +
+                "For evidence-based guidance, please consult a licensed healthcare professional.",
+            abstained: true,
+            citations: [],
+            disclaimerFooter: footer,
+            shortCircuit: false,
+        };
+    }
+    // ── Single LLM call ──────────────────────────────────────────────
+    let responseText;
+    try {
+        const response = await llm.chat({
+            model,
+            system: buildSynthesisSystem(passages),
+            messages: [{ role: "user", content: query }],
+            maxTokens: SYNTHESIS_MAX_TOKENS,
+        });
+        responseText = response.text.trim();
+    }
+    catch {
+        // Local model unavailable — abstain, NO cloud fallback.
+        return {
+            body: "I cannot ground an answer at this time (model unavailable). " +
+                "For evidence-based guidance, please consult a licensed healthcare professional.",
+            abstained: true,
+            citations: [],
+            disclaimerFooter: footer,
+            shortCircuit: false,
+        };
+    }
+    // ── Abstain if the model said so or returned empty ───────────────
+    if (!responseText || responseText.toUpperCase() === "ABSTAIN") {
+        return {
+            body: "The retrieved passages do not sufficiently support a specific answer to your question. " +
+                "For evidence-based guidance, please consult a licensed healthcare professional.",
+            abstained: true,
+            citations: [],
+            disclaimerFooter: footer,
+            shortCircuit: false,
+        };
+    }
+    // ── Non-abstained: attach citations (>= 1 guaranteed by passages.length > 0) ─
+    const citations = passagesToCitations(passages);
+    return {
+        body: responseText,
+        abstained: false,
+        citations,
+        disclaimerFooter: footer,
+        shortCircuit: false,
+    };
+}
+// ── synthesizeGrounded ────────────────────────────────────────────────
+/**
+ * Worst-case LLM call budget for the grounded gate:
+ *   1 synth + GROUNDING_MAX_LLM_CALLS critic + 1 re-synth + GROUNDING_MAX_LLM_CALLS re-critic
+ * Computed from the imported constant so it tracks future changes to the critic budget.
+ */
+export const GROUNDED_GATE_MAX_LLM_CALLS = 1 + GROUNDING_MAX_LLM_CALLS + 1 + GROUNDING_MAX_LLM_CALLS; // = 6 today (1+2+1+2)
+/**
+ * Canned abstain answer used throughout the gate when the answer cannot be
+ * sufficiently grounded in the retrieved literature.
+ */
+function abstainAnswer(footer) {
+    return {
+        body: "I cannot provide a sufficiently-supported answer grounded in the retrieved literature. " +
+            "For evidence-based guidance, please consult a licensed healthcare professional.",
+        abstained: true,
+        citations: [],
+        disclaimerFooter: footer,
+        shortCircuit: false,
+    };
+}
+/**
+ * Re-synthesize with critic feedback appended to the system prompt.
+ * A near-copy of the grounded branch inside synthesize, with one extra instruction line.
+ * Module-private — only synthesizeGrounded calls this.
+ */
+async function synthesizeWithFeedback(query, outcome, llm, footer, feedback, model = SYNTHESIS_MODEL) {
+    const passages = outcome.passages;
+    if (passages.length === 0)
+        return abstainAnswer(footer); // mirrors synthesize:120-130
+    const system = buildSynthesisSystem(passages) +
+        `\n\nAddress this reviewer feedback while staying grounded ONLY in the passages: ${feedback}`;
+    let responseText;
+    try {
+        const response = await llm.chat({
+            model,
+            system,
+            messages: [{ role: "user", content: query }],
+            maxTokens: SYNTHESIS_MAX_TOKENS,
+        });
+        responseText = response.text.trim();
+    }
+    catch {
+        return abstainAnswer(footer);
+    }
+    if (!responseText || responseText.toUpperCase() === "ABSTAIN")
+        return abstainAnswer(footer);
+    return {
+        body: responseText,
+        abstained: false,
+        citations: passagesToCitations(passages),
+        disclaimerFooter: footer,
+        shortCircuit: false,
+    };
+}
+/**
+ * synthesizeGrounded — fail-closed gate: synthesize → critic → one re-synth → abstain.
+ *
+ * For non-grounded outcomes, delegates to synthesize (disabled/abstain handled there).
+ * For grounded outcomes:
+ *   1. synthesize → if abstained, return it
+ *   2. getGroundingVerdict → if approve, return answer
+ *   3. synthesizeWithFeedback (one re-synth with critic feedback)
+ *   4. getGroundingVerdict again → if approve, return re-synth answer
+ *   5. else → return abstainAnswer (fail-closed)
+ *
+ * Any thrown error from synthesize or the critic maps to abstainAnswer (fail-closed).
+ * Bounded by GROUNDED_GATE_MAX_LLM_CALLS (= 6 worst case today).
+ *
+ * Returns { answer, verdict } where verdict is one of:
+ *   'approve'          — gate returned an approved answer
+ *   'reject-abstained' — gate abstained after a critic reject (second reject)
+ *   'error-abstained'  — gate abstained due to a thrown error or model unavailable
+ *
+ * @param model - Model identifier to use (default: SYNTHESIS_MODEL for back-compat).
+ */
+export async function synthesizeGrounded(query, outcome, llm, footer, model = SYNTHESIS_MODEL) {
+    // Non-grounded outcomes are already handled by synthesize (disabled/abstain → abstained).
+    if (outcome.kind !== "grounded") {
+        const answer = await synthesize(query, outcome, llm, footer, model);
+        return { answer, verdict: "error-abstained" };
+    }
+    // 1) First synthesis.
+    let answer;
+    try {
+        answer = await synthesize(query, outcome, llm, footer, model);
+    }
+    catch {
+        return { answer: abstainAnswer(footer), verdict: "error-abstained" };
+    }
+    if (answer.abstained)
+        return { answer, verdict: "error-abstained" }; // synthesize abstained (empty/ABSTAIN/no-passages/model-unavailable)
+    // 2) First critique. getGroundingVerdict PROPAGATES transport errors → wrap.
+    let verdict;
+    try {
+        verdict = await getGroundingVerdict({
+            llm,
+            model,
+            question: query,
+            answerBody: answer.body,
+            passages: outcome.passages,
+        });
+    }
+    catch {
+        return { answer: abstainAnswer(footer), verdict: "error-abstained" };
+    }
+    if (verdict.verdict === "approve")
+        return { answer, verdict: "approve" };
+    // 3) ONE re-synthesis with critic feedback appended to the system prompt.
+    let answer2;
+    try {
+        answer2 = await synthesizeWithFeedback(query, outcome, llm, footer, verdict.feedback, model);
+    }
+    catch {
+        return { answer: abstainAnswer(footer), verdict: "error-abstained" };
+    }
+    if (answer2.abstained)
+        return { answer: answer2, verdict: "error-abstained" };
+    // 4) Re-critique.
+    let verdict2;
+    try {
+        verdict2 = await getGroundingVerdict({
+            llm,
+            model,
+            question: query,
+            answerBody: answer2.body,
+            passages: outcome.passages,
+        });
+    }
+    catch {
+        return { answer: abstainAnswer(footer), verdict: "error-abstained" };
+    }
+    // Approved on re-critique => 'approve'. Not approved => 'reject-abstained' (critic ran and rejected).
+    return verdict2.verdict === "approve"
+        ? { answer: answer2, verdict: "approve" }
+        : { answer: abstainAnswer(footer), verdict: "reject-abstained" };
+}
+//# sourceMappingURL=literature.js.map

package/dist/medical/retrieval/literature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"literature.js","sourceRoot":"","sources":["../../../src/medical/retrieval/literature.ts"],"names":[],"mappings":"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"}

package/dist/medical/retrieval/medline-source.d.ts

@@ -0,0 +1,72 @@
+/** MedlineSource — the ONLY medical file allowed network imports (ADR-6 exception). S7 adds the real call. */
+import type { EgressGuard } from "../egress.js";
+/**
+ * A single retrieved passage from MedlinePlus.
+ * title + url form the citation; text is the passage body for synthesis grounding.
+ */
+export interface Passage {
+    title: string;
+    url: string;
+    text: string;
+    source: "medlineplus";
+}
+/**
+ * Discriminated union for retrieval outcomes.
+ * disabled — the egress axis is off; no attempt was made.
+ * abstain  — the axis is on but the source could not produce passages (error or empty).
+ * grounded — passages retrieved from MedlinePlus (Sprint 7).
+ */
+export type RetrievalOutcome = {
+    kind: "disabled";
+} | {
+    kind: "abstain";
+    reason: string;
+} | {
+    kind: "grounded";
+    passages: Passage[];
+};
+/**
+ * Injectable transport type — a minimal fetch-like function.
+ * Tests pass a fake returning recorded fixture data; production defaults to the global fetch.
+ * Using a plain duck-typed return rather than the global Response to stay testable
+ * without the global fetch in test files (global fetch is banned in other medical files).
+ * No AbortSignal in the signature — tests inject synchronous fakes that don't need it.
+ */
+export type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/**
+ * MedlinePlus retrieval source.
+ *
+ * This is the ONE file the ESLint no-restricted-imports exception permits to hold
+ * network imports (src/medical/retrieval/medline-source.ts — ADR-6).
+ *
+ * assertAllowed("literature-retrieval") is called BEFORE any fetch attempt — this
+ * is the runtime defense-in-depth that backs the static ESLint boundary.
+ *
+ * The injectable fetchImpl transport means tests NEVER reach the live MedlinePlus
+ * endpoint — they pass a fake FetchLike returning committed fixture data.
+ *
+ * bober: single source (MedlinePlus/NIH, no-auth); add PubMed in a future sprint
+ *        if multi-source support is needed — keep each source in its own file.
+ */
+export declare class MedlineSource {
+    private readonly egress;
+    private readonly fetchImpl;
+    constructor(egress: EgressGuard, fetchImpl?: FetchLike);
+    /**
+     * Fetch passages from MedlinePlus for the given query.
+     *
+     * Order:
+     * 1. assertAllowed — throws (and is caught below) if the axis is off.
+     * 2. fetchImpl(url) — injectable transport; default = global fetch.
+     * 3. Parse response into Passage[].
+     * 4. Return grounded | abstain{no-passages} | abstain{source-error}.
+     *
+     * NEVER throws out of this method — all errors map to abstain{source-error}.
+     */
+    fetchPassages(query: string): Promise<RetrievalOutcome>;
+}
+//# sourceMappingURL=medline-source.d.ts.map