@inflexa-ai/harness 0.1.1

package/dist/lib/regulatory-corpus/fetch-fda-guidance.d.ts

@@ -0,0 +1,35 @@
+export type FdaCenter = "CDER" | "CBER";
+export interface FdaDocStub {
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    center: FdaCenter;
+    metadata?: {
+        year?: string;
+        category?: string;
+    };
+}
+export interface FdaDoc {
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    text: string;
+    metadata: {
+        center: FdaCenter;
+        year?: string;
+        category?: string;
+    };
+}
+/**
+ * Return the curated FDA guidance stubs for `center`. The catalog is
+ * static; this function exists for parity with `fetchIchListing()` and as
+ * the seam where a future contributor can swap in dynamic discovery
+ * (e.g., headless-browser scraping or a vetted third-party index).
+ */
+export declare function fetchFdaGuidanceListing(center: FdaCenter): Promise<FdaDocStub[]>;
+/**
+ * Download a single FDA guidance document and extract its text. Handles
+ * both HTML and PDF formats (FDA serves a mix). Returns normalized
+ * whitespace-collapsed text suitable for chunking.
+ */
+export declare function fetchAndExtractFdaDoc(stub: FdaDocStub): Promise<FdaDoc>;

package/dist/lib/regulatory-corpus/fetch-fda-guidance.js

@@ -0,0 +1,107 @@
+import { load } from "cheerio";
+import { PDFParse } from "pdf-parse";
+/**
+ * Curated catalog of FDA guidance documents to index into the corpus.
+ *
+ * The FDA listing page (`/regulatory-information/search-fda-guidance-documents`)
+ * is a Drupal datatable rendered client-side from
+ * `/datatables-json/search-for-guidance.json`, and Akamai's edge returns
+ * 503 to non-browser fetches. Rather than scraping behind a headless
+ * browser, we maintain a hand-picked list of canonical guidances most
+ * relevant to the safety, translational, and clinical-evaluation work
+ * Cortex agents do.
+ *
+ * Each entry is keyed by the FDA media ID at `https://www.fda.gov/media/{id}/download`.
+ * Media IDs are stable: once issued they don't get renumbered when the
+ * underlying PDF is revised. To add an entry, open the guidance's
+ * `/regulatory-information/search-fda-guidance-documents/{slug}` page and
+ * grab the `Download` link's `/media/{id}/download` href.
+ */
+const FDA_GUIDANCES = [
+    {
+        center: "CDER",
+        doc_id: "fda-cder-bioanalytical-method-validation",
+        doc_title: "Bioanalytical Method Validation Guidance for Industry",
+        media_id: "70858",
+        year: "2018",
+    },
+    {
+        center: "CDER",
+        doc_id: "fda-cder-safety-testing-of-drug-metabolites",
+        doc_title: "Safety Testing of Drug Metabolites",
+        media_id: "72279",
+        year: "2020",
+    },
+    {
+        center: "CDER",
+        doc_id: "fda-cder-estimating-maximum-safe-starting-dose",
+        doc_title: "Estimating the Maximum Safe Starting Dose in Initial Clinical Trials for Therapeutics in Adult Healthy Volunteers",
+        media_id: "72309",
+        year: "2005",
+    },
+    {
+        center: "CDER",
+        doc_id: "fda-cder-drug-induced-liver-injury",
+        doc_title: "Drug-Induced Liver Injury: Premarketing Clinical Evaluation",
+        media_id: "116737",
+        year: "2009",
+    },
+];
+/**
+ * Return the curated FDA guidance stubs for `center`. The catalog is
+ * static; this function exists for parity with `fetchIchListing()` and as
+ * the seam where a future contributor can swap in dynamic discovery
+ * (e.g., headless-browser scraping or a vetted third-party index).
+ */
+export async function fetchFdaGuidanceListing(center) {
+    return FDA_GUIDANCES.filter((g) => g.center === center).map((g) => ({
+        doc_id: g.doc_id,
+        doc_title: g.doc_title,
+        doc_url: `https://www.fda.gov/media/${g.media_id}/download`,
+        center: g.center,
+        metadata: { year: g.year },
+    }));
+}
+/**
+ * Download a single FDA guidance document and extract its text. Handles
+ * both HTML and PDF formats (FDA serves a mix). Returns normalized
+ * whitespace-collapsed text suitable for chunking.
+ */
+export async function fetchAndExtractFdaDoc(stub) {
+    const res = await fetch(stub.doc_url);
+    if (!res.ok) {
+        throw new Error(`fetch ${stub.doc_url}: ${res.status} ${res.statusText}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+    let text;
+    if (ct.includes("pdf") || stub.doc_url.toLowerCase().endsWith(".pdf")) {
+        const parser = new PDFParse({ data: buf });
+        const result = await parser.getText();
+        await parser.destroy();
+        text = result.text;
+    }
+    else {
+        const $ = load(buf.toString("utf-8"));
+        // Prefer <main> when present; fall back to body.
+        text = ($("main").length > 0 ? $("main") : $("body")).text();
+    }
+    return {
+        doc_id: stub.doc_id,
+        doc_title: stub.doc_title,
+        doc_url: stub.doc_url,
+        text: normalizeWhitespace(text),
+        metadata: {
+            center: stub.center,
+            year: stub.metadata?.year,
+            category: stub.metadata?.category,
+        },
+    };
+}
+function normalizeWhitespace(s) {
+    return s
+        .replace(/[ \t]+/g, " ")
+        .replace(/\r/g, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/dist/lib/regulatory-corpus/fetch-ich.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Fetcher for ICH (International Council for Harmonisation) guidelines.
+ * Returns a curated catalog of canonical guidelines and downloads each PDF.
+ *
+ * Series:
+ *   S — Safety (nonclinical safety pharmacology, toxicology)
+ *   E — Efficacy (clinical study design, statistical principles)
+ *   M — Multidisciplinary
+ *   Q — Quality (CMC)
+ *
+ * Codes look like S7A, E14, M3(R2), Q1A. The doc_id we emit is
+ * `ich-<code>` with non-word chars sanitized.
+ */
+export type IchSeries = "S" | "E" | "M" | "Q";
+export interface IchStub {
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    code: string;
+    series: IchSeries;
+    metadata?: {
+        year?: string;
+    };
+}
+export interface IchDoc {
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    text: string;
+    metadata: {
+        code: string;
+        series: IchSeries;
+        year?: string;
+    };
+}
+/**
+ * Return the curated ICH guideline stubs. The catalog is static; this
+ * function exists for parity with `fetchFdaGuidanceListing()` and as the
+ * seam where a future contributor can swap in dynamic discovery.
+ */
+export declare function fetchIchListing(): Promise<IchStub[]>;
+/**
+ * Download a single ICH guideline PDF and extract its text. Returns
+ * normalized whitespace-collapsed text suitable for chunking.
+ */
+export declare function fetchAndExtractIchDoc(stub: IchStub): Promise<IchDoc>;

package/dist/lib/regulatory-corpus/fetch-ich.js

@@ -0,0 +1,173 @@
+/**
+ * Fetcher for ICH (International Council for Harmonisation) guidelines.
+ * Returns a curated catalog of canonical guidelines and downloads each PDF.
+ *
+ * Series:
+ *   S — Safety (nonclinical safety pharmacology, toxicology)
+ *   E — Efficacy (clinical study design, statistical principles)
+ *   M — Multidisciplinary
+ *   Q — Quality (CMC)
+ *
+ * Codes look like S7A, E14, M3(R2), Q1A. The doc_id we emit is
+ * `ich-<code>` with non-word chars sanitized.
+ */
+import { PDFParse } from "pdf-parse";
+/**
+ * Curated catalog of ICH guidelines to index into the corpus.
+ *
+ * The ICH guidelines listing at ich.org is an Angular SPA (the server
+ * returns 687 bytes of `<app-root>` shell), and the admin REST API
+ * (`admin.ich.org/api/v1/nodes`) does not expose paragraph entities, so
+ * the per-section guideline lists never reach a `fetch + cheerio` consumer.
+ * Rather than scraping behind a headless browser, we maintain a hand-picked
+ * list of canonical guidelines covering the safety, efficacy, and quality
+ * ground that Cortex agents most often need to cite.
+ *
+ * URLs target the stable PDFs at `database.ich.org/sites/default/files/...`.
+ * Filenames are inconsistent across guidelines (some include a Step-4
+ * date, some are bare); add new entries by visiting the corresponding
+ * `/page/<series>-guidelines` page in a browser, copying the PDF link,
+ * and verifying it returns `application/pdf`.
+ */
+const ICH_GUIDELINES = [
+    // Safety
+    {
+        code: "S7A",
+        series: "S",
+        doc_title: "Safety Pharmacology Studies for Human Pharmaceuticals",
+        url: "https://database.ich.org/sites/default/files/S7A_Guideline.pdf",
+    },
+    {
+        code: "S7B",
+        series: "S",
+        doc_title: "Nonclinical Evaluation of the Potential for Delayed Ventricular Repolarization (QT Interval Prolongation) by Human Pharmaceuticals",
+        url: "https://database.ich.org/sites/default/files/S7B_Guideline.pdf",
+    },
+    {
+        code: "S9",
+        series: "S",
+        doc_title: "Nonclinical Evaluation for Anticancer Pharmaceuticals",
+        url: "https://database.ich.org/sites/default/files/S9_Guideline.pdf",
+    },
+    // Multidisciplinary
+    {
+        code: "M3(R2)",
+        series: "M",
+        doc_title: "Nonclinical Safety Studies for the Conduct of Human Clinical Trials and Marketing Authorization for Pharmaceuticals",
+        url: "https://database.ich.org/sites/default/files/M3_R2__Guideline.pdf",
+    },
+    // Efficacy
+    {
+        code: "E14",
+        series: "E",
+        doc_title: "Clinical Evaluation of QT/QTc Interval Prolongation and Proarrhythmic Potential for Non-Antiarrhythmic Drugs",
+        url: "https://database.ich.org/sites/default/files/E14_Guideline.pdf",
+    },
+    {
+        code: "E6(R3)",
+        series: "E",
+        doc_title: "Good Clinical Practice (GCP)",
+        url: "https://database.ich.org/sites/default/files/ICH_E6%28R3%29_Step4_FinalGuideline_2025_0106.pdf",
+    },
+    {
+        code: "E8(R1)",
+        series: "E",
+        doc_title: "General Considerations for Clinical Studies",
+        url: "https://database.ich.org/sites/default/files/ICH_E8-R1_Guideline_Step4_2021_1006.pdf",
+    },
+    {
+        code: "E9(R1)",
+        series: "E",
+        doc_title: "Statistical Principles for Clinical Trials (Addendum: Estimands and Sensitivity Analysis)",
+        url: "https://database.ich.org/sites/default/files/E9-R1_Step4_Guideline_2019_1203.pdf",
+    },
+    {
+        code: "E11(R1)",
+        series: "E",
+        doc_title: "Clinical Investigation of Medicinal Products in the Pediatric Population (Addendum)",
+        url: "https://database.ich.org/sites/default/files/E11_R1_Addendum.pdf",
+    },
+    // Quality
+    {
+        code: "Q1A(R2)",
+        series: "Q",
+        doc_title: "Stability Testing of New Drug Substances and Products",
+        url: "https://database.ich.org/sites/default/files/Q1A%28R2%29%20Guideline.pdf",
+    },
+    {
+        code: "Q3D(R2)",
+        series: "Q",
+        doc_title: "Guideline for Elemental Impurities",
+        url: "https://database.ich.org/sites/default/files/Q3D-R2_Guideline_Step4_2022_0308.pdf",
+    },
+    {
+        code: "Q8(R2)",
+        series: "Q",
+        doc_title: "Pharmaceutical Development",
+        url: "https://database.ich.org/sites/default/files/Q8%28R2%29%20Guideline.pdf",
+    },
+    {
+        code: "Q9",
+        series: "Q",
+        doc_title: "Quality Risk Management",
+        url: "https://database.ich.org/sites/default/files/Q9%20Guideline.pdf",
+    },
+    {
+        code: "Q10",
+        series: "Q",
+        doc_title: "Pharmaceutical Quality System",
+        url: "https://database.ich.org/sites/default/files/Q10%20Guideline.pdf",
+    },
+];
+/**
+ * Return the curated ICH guideline stubs. The catalog is static; this
+ * function exists for parity with `fetchFdaGuidanceListing()` and as the
+ * seam where a future contributor can swap in dynamic discovery.
+ */
+export async function fetchIchListing() {
+    return ICH_GUIDELINES.map((g) => ({
+        doc_id: `ich-${slugify(g.code)}`,
+        doc_title: g.doc_title,
+        doc_url: g.url,
+        code: g.code,
+        series: g.series,
+    }));
+}
+/**
+ * Download a single ICH guideline PDF and extract its text. Returns
+ * normalized whitespace-collapsed text suitable for chunking.
+ */
+export async function fetchAndExtractIchDoc(stub) {
+    const res = await fetch(stub.doc_url);
+    if (!res.ok) {
+        throw new Error(`fetch ${stub.doc_url}: ${res.status} ${res.statusText}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const parser = new PDFParse({ data: buf });
+    const result = await parser.getText();
+    await parser.destroy();
+    return {
+        doc_id: stub.doc_id,
+        doc_title: stub.doc_title,
+        doc_url: stub.doc_url,
+        text: normalizeWhitespace(result.text),
+        metadata: {
+            code: stub.code,
+            series: stub.series,
+            year: stub.metadata?.year,
+        },
+    };
+}
+function normalizeWhitespace(s) {
+    return s
+        .replace(/[ \t]+/g, " ")
+        .replace(/\r/g, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}

package/dist/lib/regulatory-corpus.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Helpers for the FDA/ICH regulatory corpus stored in cortex_regulatory_chunks.
+ *
+ * Three responsibilities:
+ *  1. chunkText — split a normalized document into (~1000-token, 200-token-overlap)
+ *     chunks, preserving section headings where the doc uses `## Heading` markers.
+ *  2. upsertChunks — replace-by-(source, doc_id) write of a document's chunks +
+ *     embeddings + metadata.
+ *  3. searchByEmbedding — top-K cosine similarity over the corpus, with optional
+ *     source / indication / modality filters.
+ *
+ * Embedding dim is 1536 (openai/text-embedding-3-small). The schema's vector
+ * column is fixed at vector(1536) — passing other-dim arrays will fail at
+ * insert time.
+ */
+import { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "./db-result.js";
+export interface ChunkOptions {
+    maxTokens?: number;
+    overlapTokens?: number;
+}
+export interface RawChunk {
+    section: string | null;
+    index: number;
+    text: string;
+}
+/**
+ * Split `text` into overlapping chunks bounded by `maxTokens` (word-count
+ * approximation), respecting `## Heading` section boundaries where present.
+ *
+ * When the document has `## Heading` markers the text is split at those
+ * boundaries first; each resulting section is then sliced into fixed-size
+ * windows with the requested overlap. Sections with no body content are
+ * silently skipped.
+ *
+ * When no `## Heading` markers are present the entire text is treated as a
+ * single anonymous section (section: null).
+ *
+ * The returned chunks have globally monotone `index` values so consumers
+ * can reassemble the document order without inspecting section names.
+ */
+export declare function chunkText(text: string, opts?: ChunkOptions): RawChunk[];
+export interface ChunkRow {
+    source: "FDA-CDER" | "FDA-CBER" | "ICH";
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    chunks: Array<RawChunk & {
+        embedding: number[];
+    }>;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Replace-by-(source, doc_id): delete all existing chunks for the document
+ * then insert the new set in a single transaction.
+ *
+ * Embedding dimension is validated before the transaction opens — a mismatch
+ * is a programmer/data error, thrown verbatim (no DB touched, nothing to roll
+ * back), not a `DbError`.
+ */
+export declare function upsertChunks(pool: Pool, row: ChunkRow): ResultAsync<void, DbError>;
+export interface SearchFilters {
+    source?: "FDA-CDER" | "FDA-CBER" | "ICH";
+    topK?: number;
+}
+export interface SearchHit {
+    source: string;
+    doc_id: string;
+    doc_title: string;
+    doc_url: string;
+    section: string | null;
+    excerpt: string;
+    score: number;
+}
+/**
+ * Top-K cosine similarity search over cortex_regulatory_chunks.
+ *
+ * Uses pgvector's `<=>` (cosine distance) operator. Score is `1 - distance`
+ * so higher scores = more similar. The `source` filter narrows results to
+ * a single corpus subset (FDA-CDER, FDA-CBER, or ICH).
+ *
+ * Embedding dimension is validated before the query. Indication/modality
+ * filters are intentionally absent — the ingestion pipeline does not yet
+ * tag those keys on chunk metadata, and a filter that always returns zero
+ * rows would silently defeat consumer expectations.
+ */
+export declare function searchByEmbedding(pool: Pool, embedding: number[], filters?: SearchFilters): ResultAsync<SearchHit[], DbError>;

package/dist/lib/regulatory-corpus.js

@@ -0,0 +1,141 @@
+/**
+ * Helpers for the FDA/ICH regulatory corpus stored in cortex_regulatory_chunks.
+ *
+ * Three responsibilities:
+ *  1. chunkText — split a normalized document into (~1000-token, 200-token-overlap)
+ *     chunks, preserving section headings where the doc uses `## Heading` markers.
+ *  2. upsertChunks — replace-by-(source, doc_id) write of a document's chunks +
+ *     embeddings + metadata.
+ *  3. searchByEmbedding — top-K cosine similarity over the corpus, with optional
+ *     source / indication / modality filters.
+ *
+ * Embedding dim is 1536 (openai/text-embedding-3-small). The schema's vector
+ * column is fixed at vector(1536) — passing other-dim arrays will fail at
+ * insert time.
+ */
+import { tryMutation, tryQuery, withTransaction } from "./db-result.js";
+/**
+ * Split `text` into overlapping chunks bounded by `maxTokens` (word-count
+ * approximation), respecting `## Heading` section boundaries where present.
+ *
+ * When the document has `## Heading` markers the text is split at those
+ * boundaries first; each resulting section is then sliced into fixed-size
+ * windows with the requested overlap. Sections with no body content are
+ * silently skipped.
+ *
+ * When no `## Heading` markers are present the entire text is treated as a
+ * single anonymous section (section: null).
+ *
+ * The returned chunks have globally monotone `index` values so consumers
+ * can reassemble the document order without inspecting section names.
+ */
+export function chunkText(text, opts = {}) {
+    const maxTokens = opts.maxTokens ?? 1000;
+    const overlapTokens = opts.overlapTokens ?? 200;
+    // Normalise so every `## Heading` is preceded by `\n`, then split.
+    // This ensures a heading at position 0 (no preceding newline) is caught
+    // the same way as headings mid-document.
+    const normalised = text.startsWith("##") ? `\n${text}` : text;
+    const parts = normalised.split(/\n##\s+/);
+    // parts[0] is always the lead-in text before the first heading (may be
+    // empty when the document opens with a heading).
+    const sections = parts.length > 1
+        ? parts.map((p, i) => {
+            if (i === 0)
+                return { heading: null, body: p };
+            const nl = p.indexOf("\n");
+            if (nl === -1)
+                return { heading: p.trim(), body: "" };
+            return { heading: p.slice(0, nl).trim(), body: p.slice(nl + 1) };
+        })
+        : [{ heading: null, body: text }];
+    const out = [];
+    let globalIdx = 0;
+    for (const sec of sections) {
+        const tokens = sec.body.split(/\s+/).filter(Boolean);
+        if (tokens.length === 0)
+            continue;
+        // Slide a window of maxTokens tokens with advance = maxTokens - overlapTokens.
+        // The last window may be shorter than maxTokens (trailing partial slice).
+        const advance = Math.max(1, maxTokens - overlapTokens);
+        let i = 0;
+        while (i < tokens.length) {
+            const slice = tokens.slice(i, i + maxTokens).join(" ");
+            out.push({ section: sec.heading, index: globalIdx++, text: slice });
+            // If this window didn't fill maxTokens it was the final slice.
+            if (i + maxTokens >= tokens.length)
+                break;
+            i += advance;
+        }
+    }
+    return out;
+}
+/**
+ * Replace-by-(source, doc_id): delete all existing chunks for the document
+ * then insert the new set in a single transaction.
+ *
+ * Embedding dimension is validated before the transaction opens — a mismatch
+ * is a programmer/data error, thrown verbatim (no DB touched, nothing to roll
+ * back), not a `DbError`.
+ */
+export function upsertChunks(pool, row) {
+    for (const ch of row.chunks) {
+        if (ch.embedding.length !== 1536) {
+            throw new Error(`chunk embedding dim ${ch.embedding.length} != 1536 ` + `(source=${row.source} doc_id=${row.doc_id} index=${ch.index})`);
+        }
+    }
+    return withTransaction(pool, "regulatoryCorpus.upsertChunks", (client) => tryMutation("regulatoryCorpus.upsertChunks", async () => {
+        await client.query("DELETE FROM cortex_regulatory_chunks WHERE source = $1 AND doc_id = $2", [row.source, row.doc_id]);
+        for (const ch of row.chunks) {
+            await client.query(`INSERT INTO cortex_regulatory_chunks
+           (source, doc_id, doc_title, doc_url, section, chunk_index, chunk_text, embedding, metadata)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8::vector, $9)`, [row.source, row.doc_id, row.doc_title, row.doc_url, ch.section, ch.index, ch.text, `[${ch.embedding.join(",")}]`, row.metadata]);
+        }
+    }));
+}
+/**
+ * Top-K cosine similarity search over cortex_regulatory_chunks.
+ *
+ * Uses pgvector's `<=>` (cosine distance) operator. Score is `1 - distance`
+ * so higher scores = more similar. The `source` filter narrows results to
+ * a single corpus subset (FDA-CDER, FDA-CBER, or ICH).
+ *
+ * Embedding dimension is validated before the query. Indication/modality
+ * filters are intentionally absent — the ingestion pipeline does not yet
+ * tag those keys on chunk metadata, and a filter that always returns zero
+ * rows would silently defeat consumer expectations.
+ */
+export function searchByEmbedding(pool, embedding, filters = {}) {
+    if (embedding.length !== 1536) {
+        throw new Error(`query embedding dim ${embedding.length} != 1536`);
+    }
+    const topK = filters.topK ?? 8;
+    const wheres = [];
+    const params = [`[${embedding.join(",")}]`];
+    if (filters.source) {
+        params.push(filters.source);
+        wheres.push(`source = $${params.length}`);
+    }
+    const whereClause = wheres.length ? `WHERE ${wheres.join(" AND ")}` : "";
+    params.push(topK);
+    const sql = `
+    SELECT source, doc_id, doc_title, doc_url, section, chunk_text,
+           1 - (embedding <=> $1::vector) AS score
+    FROM cortex_regulatory_chunks
+    ${whereClause}
+    ORDER BY embedding <=> $1::vector
+    LIMIT $${params.length}
+  `;
+    return tryQuery("regulatoryCorpus.searchByEmbedding", async () => {
+        const res = await pool.query(sql, params);
+        return res.rows.map((r) => ({
+            source: r.source,
+            doc_id: r.doc_id,
+            doc_title: r.doc_title,
+            doc_url: r.doc_url,
+            section: r.section,
+            excerpt: r.chunk_text,
+            score: Number(r.score),
+        }));
+    });
+}

package/dist/lib/result.d.ts

@@ -0,0 +1,87 @@
+/**
+ * neverthrow conventions for cortex.
+ *
+ * The agent loop and execution boundary model failure as values, not throws.
+ * The house rules:
+ *
+ *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
+ *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
+ *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
+ *     Everything above them flows `Result` / `ResultAsync`.
+ *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
+ *     data variant (`ok({ found: false })`), never an `err`. `err` is
+ *     reserved for what used to be `throw`n — an unexpected upstream failure.
+ *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
+ *     dialect of failure:
+ *       - HTTP routes `.match(...)` a `Result` into a response.
+ *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
+ *         `resultStep` in `loop/run-step.ts`): durability records a step as
+ *         failed — and retries / fails fast — ONLY on a thrown exception, so
+ *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - Tool dispatch maps `err` into an `is_error` `tool_result`
+ *         (`loop/run-agent.ts`).
+ *
+ * Control-flow exceptions (DBOS cancellation, `AbortError`) are NOT failures
+ * and live OUTSIDE the `Result` error channel — they are thrown verbatim and
+ * must never be captured as an `err`.
+ *
+ * Sites import `ok`/`err`/`Result`/`ResultAsync`/`fromPromise`/`fromThrowable`
+ * directly from `neverthrow`; this module owns only the cortex-specific glue.
+ */
+import { type Result } from "neverthrow";
+/**
+ * The shape every per-subsystem error union shares: a string `type`
+ * discriminant plus an optional underlying `cause`. Concrete modules narrow
+ * `type` to their own literals and add typed fields (e.g. `DbError`,
+ * `SandboxError`), and ship a `describe*Error` formatter that turns one into
+ * a user-facing line. A step body's error channel is some `DomainError`.
+ */
+export interface DomainError {
+    readonly type: string;
+    readonly cause?: unknown;
+}
+/**
+ * A thrown wrapper for a structured error value that is not already an
+ * `Error`. The original value rides on `.cause`, so the cause-walking
+ * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
+ * `status` / `code` signals they look for after a `Result` is rethrown at a
+ * boundary.
+ */
+export declare class ResultError extends Error {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * Bridge a `Result` error value into a thrown `Error` at a boundary that
+ * speaks exceptions. An error that is already an `Error` is thrown verbatim
+ * (its class, `.cause`, and any `status` survive); anything else is wrapped
+ * in `ResultError` with the structured value on `.cause`.
+ */
+export declare function toThrowable(value: unknown): Error;
+/**
+ * Unwrap a `Result`, throwing on `err`. The canonical Result→throw bridge for
+ * the DBOS step edge and any other boundary whose failure protocol is an
+ * exception (a driver's throw-to-rollback). The throw is isolated here so the
+ * rest of the code stays Result-shaped.
+ *
+ * Use it ONLY where a throw is the boundary's failure contract:
+ *
+ *  - **DBOS workflow/step bodies** (directly, or composed via `resultStep` in
+ *    `loop/run-step.ts`). DBOS records a step as failed — and retries / fails
+ *    fast — only on a thrown exception; a *returned* `err` would be durably
+ *    cached as a successful step output and replayed as success forever.
+ *  - **Tool `execute` bodies**, where the loop's dispatch catch maps the
+ *    throw into a model-visible error tool result (`loop/run-agent.ts`).
+ *  - **Driver edges whose protocol is a throw** (e.g. throw-to-rollback).
+ *
+ * Anywhere else, keep the `Result` flowing: return it, chain
+ * `.andThen`/`.map`/`.mapErr`, or `.match` both branches. Never reach for
+ * this to dodge error handling in composable domain logic.
+ *
+ * The `must-use-result` lint rule recognizes `unwrapOrThrow(...)` as
+ * consuming its Result (see the plugin patch in `eslint.config.js`) — do not
+ * rewrite call sites into inline `.match`+throw forms to appease lint.
+ */
+export declare function unwrapOrThrow<T, E>(result: Result<T, E>): T;
+/** Runtime brand check — is this value a neverthrow `Result`? */
+export declare function isResult(value: unknown): value is Result<unknown, unknown>;