@inflexa-ai/harness 0.4.0 → 0.4.2

package/dist/execution/post-step-pipeline.d.ts

@@ -60,9 +60,20 @@ export declare function generateStepSummaryAndWrite(deps: PostStepPipelineDeps,
  */
 export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<readonly ArtifactManifestEntry[]>;
 /**
- * Vector-index the threaded file descriptions + summary into the per-analysis
- * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
- * without failing the step — the internal try/catch logs + swallows.
+ * Vector-index the threaded file descriptions + the step summary into the
+ * per-analysis pgvector store. Best-effort (see the artifact-manifest spec):
+ * indexing degrades without failing the step.
+ *
+ * Degradation is per-item. Index setup (ensuring the index exists and building
+ * the store) is all-or-nothing — a setup failure logs and skips the stage,
+ * because without an index there is nowhere to index into. Past setup, each
+ * file description and the summary is embedded and upserted under its own
+ * failure boundary, so one rejected input (e.g. an over-length document the
+ * embedding backend rejects) costs only its own entry and every other item is
+ * still attempted. A partial index is invisible at the search surface — it
+ * returns fewer hits, never an error — so each per-item failure logs the item
+ * id and input text length, and when any item fails a final record carries the
+ * indexed/failed counts as the only signal that degradation occurred.
  */
 export declare function vectorIndexStepOutputs(deps: PostStepPipelineDeps, postCtx: PostStepContext, artifacts: PostStepArtifacts): Promise<void>;
 /**

package/dist/execution/post-step-pipeline.js

@@ -144,60 +144,88 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
     return reconciled.manifest;
 }
 /**
- * Vector-index the threaded file descriptions + summary into the per-analysis
- * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
- * without failing the step — the internal try/catch logs + swallows.
+ * Vector-index the threaded file descriptions + the step summary into the
+ * per-analysis pgvector store. Best-effort (see the artifact-manifest spec):
+ * indexing degrades without failing the step.
+ *
+ * Degradation is per-item. Index setup (ensuring the index exists and building
+ * the store) is all-or-nothing — a setup failure logs and skips the stage,
+ * because without an index there is nowhere to index into. Past setup, each
+ * file description and the summary is embedded and upserted under its own
+ * failure boundary, so one rejected input (e.g. an over-length document the
+ * embedding backend rejects) costs only its own entry and every other item is
+ * still attempted. A partial index is invisible at the search surface — it
+ * returns fewer hits, never an error — so each per-item failure logs the item
+ * id and input text length, and when any item fails a final record carries the
+ * indexed/failed counts as the only signal that degradation occurred.
  */
 export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
     const { input } = postCtx;
     const { metadataEntries, summary, reconciledManifest } = artifacts;
+    const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("vector-index").with({ runId: input.runId, stepId: input.stepId });
+    let vectorStore;
+    let indexName;
     try {
+        // Setup is all-or-nothing: without an index there is nothing to index into.
         await ensureSearchIndex(deps.pool, input.analysisId, deps.embedding.dimensions);
-        const vectorStore = createVectorStore(deps.pool);
-        const indexName = searchIndexName(input.analysisId);
-        const embedOne = async (text) => {
-            const [vec] = unwrapOrThrow(await deps.embedding.embed([text], postCtx.session));
-            if (!vec)
-                throw new Error("vectorIndexStepOutputs: empty embedding response");
-            return vec;
-        };
-        const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
-        const survivingPaths = new Set(reconciledManifest.map((a) => a.path));
-        const liveMetadata = metadataEntries.filter((e) => survivingPaths.has(e.dbPath.slice(dbPathPrefix.length)));
-        for (const entry of liveMetadata) {
-            const embedding = await embedOne(entry.description);
-            unwrapOrThrow(await vectorStore.upsert({
-                indexName,
-                vectors: [embedding],
-                metadata: [{ text: entry.description, type: "output", ...entry.metadata }],
-                ids: [`/${input.analysisId}/${entry.dbPath}`],
-            }));
+        vectorStore = createVectorStore(deps.pool);
+        indexName = searchIndexName(input.analysisId);
+    }
+    catch (err) {
+        logger.warn("indexing failed", logger.errorFields(err));
+        return;
+    }
+    const embedOne = async (text) => {
+        const [vec] = unwrapOrThrow(await deps.embedding.embed([text], postCtx.session));
+        if (!vec)
+            throw new Error("vectorIndexStepOutputs: empty embedding response");
+        return vec;
+    };
+    /** Index one item, absorbing its failure so the rest of the step still lands. */
+    const indexOne = async (id, text, metadata) => {
+        try {
+            const embedding = await embedOne(text);
+            unwrapOrThrow(await vectorStore.upsert({ indexName, vectors: [embedding], metadata: [metadata], ids: [id] }));
+            return true;
         }
-        if (summary && summary.markdown.trim().length > 0) {
-            const relPath = `runs/${input.runId}/${input.stepId}/output/summary.md`;
-            const summaryDbPath = `/${input.analysisId}/${relPath}`;
-            const summaryEmbedding = await embedOne(summary.markdown);
-            unwrapOrThrow(await vectorStore.upsert({
-                indexName,
-                vectors: [summaryEmbedding],
-                metadata: [
-                    {
-                        text: summary.markdown,
-                        type: "summary",
-                        stepId: input.stepId,
-                        runId: input.runId,
-                        agentId: input.agentId,
-                        path: relPath,
-                    },
-                ],
-                ids: [summaryDbPath],
-            }));
+        catch (err) {
+            // Text length rides as a field because over-length input is the known
+            // failure driver, and the description/summary itself stays out of logs.
+            logger.warn("indexing failed", { id, textLength: text.length, ...logger.errorFields(err) });
+            return false;
         }
+    };
+    const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
+    const survivingPaths = new Set(reconciledManifest.map((a) => a.path));
+    const liveMetadata = metadataEntries.filter((e) => survivingPaths.has(e.dbPath.slice(dbPathPrefix.length)));
+    let indexed = 0;
+    let failed = 0;
+    for (const entry of liveMetadata) {
+        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, { text: entry.description, type: "output", ...entry.metadata });
+        if (ok)
+            indexed++;
+        else
+            failed++;
     }
-    catch (err) {
-        const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("vector-index");
-        logger.warn("indexing failed", { runId: input.runId, stepId: input.stepId, ...logger.errorFields(err) });
+    if (summary && summary.markdown.trim().length > 0) {
+        const relPath = `runs/${input.runId}/${input.stepId}/output/summary.md`;
+        const ok = await indexOne(`/${input.analysisId}/${relPath}`, summary.markdown, {
+            text: summary.markdown,
+            type: "summary",
+            stepId: input.stepId,
+            runId: input.runId,
+            agentId: input.agentId,
+            path: relPath,
+        });
+        if (ok)
+            indexed++;
+        else
+            failed++;
     }
+    // A partial index is invisible at the search surface — it returns fewer hits,
+    // never an error — so the count of what did not land is the only signal.
+    if (failed > 0)
+        logger.warn("indexed with failures", { indexed, failed });
 }
 /**
  * Assemble the step-detail payload (file tree, summary markdown, output file

package/dist/execution/reconcile-manifest.d.ts

@@ -17,9 +17,9 @@ export interface ReconcileManifestInput {
     /** Collector backing the manifest; mutated to reflect drops/rehashes. */
     collector: ProvenanceCollector;
     /**
-     * Operational logging seam; omitted falls back to no-op. Attestation is
-     * fail-fast, so what this records — which entry was dropped, which input
-     * could not be hashed — is the account of why a step died.
+     * Operational logging seam; omitted falls back to no-op. What this records
+     * — which entry or input was dropped, which input could not be hashed — is
+     * the sole account of why lineage changed or a step died.
      */
     logger?: Logger;
 }

package/dist/execution/reconcile-manifest.js

@@ -23,7 +23,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
-import { artifactReconcileDropped } from "../lib/metrics.js";
+import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -74,7 +74,7 @@ export async function reconcileManifestWithDisk(input) {
         const hash = await computeSha256File(absPath);
         reconciled.push({ ...entry, hash, size: info.size });
     }
-    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger);
+    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, agentId, logger);
     return { manifest: reconciled, droppedCount };
 }
 /**
@@ -87,35 +87,47 @@ export async function reconcileManifestWithDisk(input) {
  *
  * `artifacts`-source reads are the step's OWN files (mutating, dropped by the
  * registration translator), so they are not attested and not hashed here.
- * Lineage attestation is fail-fast: an input we cannot hash (gone, or resolving
- * outside the analysis tree) throws rather than registering a hashless edge.
+ * Lineage attestation is fail-fast for drift: an input that should be on disk
+ * and is not (ENOENT) throws rather than registering a hashless edge. A read
+ * that resolves OUTSIDE the analysis tree is dropped from lineage instead —
+ * the sandbox can legitimately open paths above its mount (`/{resourceId}/..`
+ * is the container root) and a capture layer may report them; that is out of
+ * scope, not drift, and failing the step over it killed real analyses in the
+ * field. Dropping still registers no hashless edge, which is the invariant.
  */
-async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger) {
+async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, agentId, logger) {
     const resourceRoot = path.resolve(workspaceRoot);
     for (const ref of collector.getTrackedInputs()) {
         if (ref.source === "artifacts")
             continue;
         if (hasValidContentHash(ref.hash))
             continue;
-        // Each throw below is logged before it is raised. The thrown message reaches
-        // `failStep` as one opaque string and everything downstream of that is
-        // scrubbed, so naming the site and the offending ref HERE is what makes a
-        // fail-fast attestation distinguishable from a registry rejection after the
-        // fact — the read's `source` in particular says whether the step declared
+        // Every throw below is logged before it is raised, and every drop is
+        // logged as it happens. The thrown message reaches `failStep` as one
+        // opaque string and everything downstream of that is scrubbed, so naming
+        // the site and the offending ref HERE is the only account of why a step
+        // died — the read's `source` in particular says whether the step declared
         // this input at all.
         const attestation = { path: ref.path, source: ref.source, refRunId: ref.runId, refStepId: ref.stepId };
         // `ref.path` is the absolute container path `/{resourceId}/...`; strip the
         // mount segment and map the tail onto the host workspace root. `path.join`
         // normalizes any `..`, and the bound confines the read to the analysis tree.
+        // An out-of-tree resolution is dropped, not thrown: it is not an attestable
+        // lineage edge, but it is also not drift — mirrors the out-of-bounds output
+        // skip in `reconcileManifestWithDisk` and the directory drop below.
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
-            logger.error("input read resolves outside the analysis tree", { ...attestation, throwSite: "container-prefix-bound" });
-            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+            logger.warn("dropping out-of-tree input from lineage", { ...attestation, boundSite: "container-prefix" });
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "container-prefix" });
+            collector.dropInput(ref);
+            continue;
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
-            logger.error("input read resolves outside the analysis tree", { ...attestation, hostPath, throwSite: "workspace-root-bound" });
-            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+            logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "workspace-root" });
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "workspace-root" });
+            collector.dropInput(ref);
+            continue;
         }
         let info;
         try {
@@ -138,6 +150,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
             logger.debug("dropping non-file input from lineage", attestation);
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "directory" });
             collector.dropInput(ref);
             continue;
         }

package/dist/index.d.ts

@@ -103,7 +103,7 @@ export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
-export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset, ReferenceIntegrity, } from "./reference-data/catalog.js";
+export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset, } from "./reference-data/catalog.js";
 export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
 export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";

package/dist/lib/metrics.d.ts

@@ -3,5 +3,7 @@
  *
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
  */
 export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const lineageInputDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;

package/dist/lib/metrics.js

@@ -3,6 +3,7 @@
  *
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
  */
 import { metrics } from "@opentelemetry/api";
 const meter = metrics.getMeter("cortex");
@@ -10,3 +11,8 @@ export const artifactReconcileDropped = meter.createCounter("cortex.artifact.rec
     description: "Manifest entries dropped because their on-disk file was missing at " +
         "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
 });
+export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
+    description: "Tracked input reads dropped from lineage at reconcile because they are " +
+        "not content-attestable files of the analysis (directory reads, " +
+        "out-of-tree resolutions). Tagged by agent_id, step_id, reason.",
+});

package/dist/provenance/collector.d.ts

@@ -86,7 +86,9 @@ export declare class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -124,10 +126,11 @@ export declare class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref: InputRef): void;
     /**

package/dist/provenance/collector.js

@@ -121,7 +121,9 @@ export class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -133,7 +135,12 @@ export class ProvenanceCollector {
             return existing;
         // Use explicit context if provided, otherwise fall back to path classification
         const classification = context ?? classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
-        const fullPath = `${mountPath}/${relativePath}`;
+        // A still-absolute `relativePath` is a report the caller could not
+        // relativize — it names somewhere outside the mount. It rides verbatim:
+        // prepending the mount root would forge an in-tree name for a foreign
+        // path, and reconcile would then see phantom drift (a missing file,
+        // which fails the step) instead of an out-of-tree read (which it drops).
+        const fullPath = relativePath.startsWith("/") ? relativePath : `${mountPath}/${relativePath}`;
         // Resolve fileId for data-source inputs via materialized file metadata map
         let fileId;
         if (classification.source === "data" && this.inputFileIdMap) {
@@ -240,10 +247,11 @@ export class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref) {
         for (const [key, val] of this.inputAccesses) {

package/dist/provenance/exec-frame.d.ts

@@ -14,7 +14,13 @@
  */
 import type { ProvenanceFrame } from "../sandbox/types.js";
 import { type ProvenanceCollector } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export declare function stripMountPrefix(mountRoot: string, absPath: string): string;
 export interface FeedExecFrameArgs {
     readonly collector: ProvenanceCollector;

package/dist/provenance/exec-frame.js

@@ -13,10 +13,16 @@
  * It never throws — provenance is best-effort and must not fail an exec.
  */
 import { classifyReadPath } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export function stripMountPrefix(mountRoot, absPath) {
     const prefix = mountRoot.endsWith("/") ? mountRoot : `${mountRoot}/`;
-    return absPath.startsWith(prefix) ? absPath.slice(prefix.length) : absPath;
+    return absPath.startsWith(prefix) ? absPath.slice(prefix.length).replace(/^\/+/, "") : absPath;
 }
 /**
  * Translate one exec's frame into a collector record. Per-command input

package/dist/providers/errors.d.ts

@@ -10,9 +10,12 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
-export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
+export type ProviderErrorKind = "auth" | "budget" | "tenant-blocked" | "provider";
 /**
  * The provider error value channel — a `DomainError`-conforming
  * discriminated union mirroring `ProviderErrorKind`. `chat` / `embed` return
@@ -23,6 +26,11 @@ export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
  * step boundary.
  */
 export type ProviderError = {
+    readonly type: "auth";
+    readonly retryable: false;
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
     readonly type: "budget";
     readonly retryable: false;
     readonly message: string;
@@ -72,6 +80,7 @@ export interface ProviderErrorClassification {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.

package/dist/providers/errors.js

@@ -10,7 +10,10 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
@@ -22,7 +25,9 @@ export function isProviderError(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const v = value;
-    return (v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") && typeof v.retryable === "boolean" && typeof v.message === "string";
+    return ((v.type === "auth" || v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") &&
+        typeof v.retryable === "boolean" &&
+        typeof v.message === "string");
 }
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
@@ -42,6 +47,14 @@ export function toProviderError(e, workload) {
         return e;
     const { kind, retryable } = classifyProviderError(e);
     const detail = e instanceof Error ? e.message : String(e);
+    if (kind === "auth") {
+        return {
+            type: "auth",
+            retryable: false,
+            message: `Provider rejected the credential for ${workload} — it is expired, revoked, or absent: ${detail}`,
+            cause: e,
+        };
+    }
     if (kind === "budget") {
         return {
             type: "budget",
@@ -109,6 +122,7 @@ function looksLikeConnectionError(err) {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
@@ -116,6 +130,13 @@ function looksLikeConnectionError(err) {
  */
 export function classifyProviderError(e) {
     const status = extractStatus(e);
+    // `auth` is its own kind rather than a plain non-retryable 4xx because the
+    // remedy is categorically different: the request was well-formed and the
+    // credential behind it is not, so no amount of re-issuing or rephrasing
+    // helps — a human has to re-authenticate. Callers surface that; the generic
+    // 4xx branch below would tell them the request was wrong, which is false.
+    if (status === 401)
+        return { kind: "auth", retryable: false };
     if (status === 402)
         return { kind: "budget", retryable: false };
     if (status === 403)

package/dist/reference-data/catalog.d.ts

@@ -6,20 +6,20 @@ export declare const REFERENCE_DATA_CATALOG_VERSION: 1;
 export declare const ReferenceArtifactPathSchema: z.ZodString;
 /** Lowercase SHA-256 digest of one artifact's bytes. */
 export declare const ReferenceSha256Schema: z.ZodString;
-/** One immutable final file distributed for a reference dataset. */
-export declare const ReferenceArtifactSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    integrity: z.ZodLiteral<"pinned">;
-    path: z.ZodString;
-    url: z.ZodURL;
-    bytes: z.ZodNumber;
-    sha256: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
-    integrity: z.ZodLiteral<"unpinned">;
+/**
+ * One final file distributed for a reference dataset: a stable install-relative
+ * path and the third-party https URL it is fetched from. The catalog carries no
+ * size or digest — every upstream is authenticated over TLS at download time,
+ * and the installer records the bytes it actually received in the receipt so
+ * `verify` can later prove the local copy has not changed since install. This is
+ * one uniform trust-on-first-use model; there is deliberately no per-artifact
+ * integrity class, so adding a source is only ever a URL, and no checked-in
+ * digest is ours to maintain or lets go stale when a `current` upstream rebuilds.
+ */
+export declare const ReferenceArtifactSchema: z.ZodObject<{
     path: z.ZodString;
     url: z.ZodURL;
-}, z.core.$strict>], "integrity">;
-/** Which integrity guarantee an artifact can actually offer. */
-export type ReferenceIntegrity = z.infer<typeof ReferenceArtifactSchema>["integrity"];
+}, z.core.$strict>;
 /** Provenance and licensing information for one supported reference dataset. */
 export declare const ReferenceDatasetSchema: z.ZodObject<{
     id: z.ZodString;
@@ -35,17 +35,10 @@ export declare const ReferenceDatasetSchema: z.ZodObject<{
         group: z.ZodString;
         recommended: z.ZodBoolean;
     }, z.core.$strip>;
-    artifacts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        integrity: z.ZodLiteral<"pinned">;
+    artifacts: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         url: z.ZodURL;
-        bytes: z.ZodNumber;
-        sha256: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        integrity: z.ZodLiteral<"unpinned">;
-        path: z.ZodString;
-        url: z.ZodURL;
-    }, z.core.$strict>], "integrity">>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 /** Versioned canonical catalog consumed identically by every harness embedder. */
 export declare const ReferenceDataCatalogSchema: z.ZodObject<{
@@ -64,17 +57,10 @@ export declare const ReferenceDataCatalogSchema: z.ZodObject<{
             group: z.ZodString;
             recommended: z.ZodBoolean;
         }, z.core.$strip>;
-        artifacts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            integrity: z.ZodLiteral<"pinned">;
-            path: z.ZodString;
-            url: z.ZodURL;
-            bytes: z.ZodNumber;
-            sha256: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            integrity: z.ZodLiteral<"unpinned">;
+        artifacts: z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             url: z.ZodURL;
-        }, z.core.$strict>], "integrity">>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
@@ -97,14 +83,14 @@ export declare function referenceArtifactKey(dataset: {
 /**
  * Canonical release catalog. Every artifact is fetched directly from the third
  * party that publishes it; this project hosts, mirrors, and redistributes
- * nothing. Entries are added only with real upstream URLs, provenance, and
- * licensing data — plus a size and digest whenever the upstream publishes
- * immutable bytes we can pin to.
+ * nothing. Entries are added with a real upstream https URL, provenance, and
+ * licensing data — and nothing else per file: no size, no digest to compute or
+ * keep in sync.
  *
  * `version` is the dataset's upstream release identifier. Datasets built on an
  * upstream that has no immutable release — NCBI regenerates `gene_info` daily,
  * Reactome overwrites `current` and deletes prior releases — are versioned
- * `current` and carry `unpinned` artifacts.
+ * `current`; those with an immutable release carry it verbatim.
  */
 export declare const REFERENCE_DATA_CATALOG: ReferenceDataCatalog;
 /** One selected dataset and its host-neutral installation location. */

package/dist/reference-data/catalog.js

@@ -22,34 +22,19 @@ export const ReferenceSha256Schema = z.string().regex(SHA256, "Expected a lowerc
  */
 const ReferenceArtifactUrlSchema = z.url().refine((value) => value.startsWith("https://"), "Reference artifacts must be fetched over https");
 /**
- * An artifact whose upstream publishes immutable, versioned bytes. The catalog
- * carries the size and digest, so a download is verified against *this file*
- * before it is ever activated: a mismatch means the bytes are not what we
- * reviewed, and the install fails.
+ * One final file distributed for a reference dataset: a stable install-relative
+ * path and the third-party https URL it is fetched from. The catalog carries no
+ * size or digest — every upstream is authenticated over TLS at download time,
+ * and the installer records the bytes it actually received in the receipt so
+ * `verify` can later prove the local copy has not changed since install. This is
+ * one uniform trust-on-first-use model; there is deliberately no per-artifact
+ * integrity class, so adding a source is only ever a URL, and no checked-in
+ * digest is ours to maintain or lets go stale when a `current` upstream rebuilds.
  */
-const PinnedReferenceArtifactSchema = z.strictObject({
-    integrity: z.literal("pinned"),
+export const ReferenceArtifactSchema = z.strictObject({
     path: ReferenceArtifactPathSchema,
     url: ReferenceArtifactUrlSchema,
-    bytes: z.number().int().positive(),
-    sha256: ReferenceSha256Schema,
 });
-/**
- * An artifact whose upstream regenerates the same URL in place — NCBI rebuilds
- * `gene_info` continuously and Reactome's `current` release is overwritten and
- * its predecessors deleted. No checked-in digest can survive that, and pinning
- * one would only guarantee a broken download. Integrity is therefore
- * trust-on-first-use: the installer records the bytes it actually received in
- * the receipt, and `verify` proves the files have not changed *since install*.
- * This is a weaker guarantee than `pinned` and is surfaced as such to the user.
- */
-const UnpinnedReferenceArtifactSchema = z.strictObject({
-    integrity: z.literal("unpinned"),
-    path: ReferenceArtifactPathSchema,
-    url: ReferenceArtifactUrlSchema,
-});
-/** One immutable final file distributed for a reference dataset. */
-export const ReferenceArtifactSchema = z.discriminatedUnion("integrity", [PinnedReferenceArtifactSchema, UnpinnedReferenceArtifactSchema]);
 /** Provenance and licensing information for one supported reference dataset. */
 export const ReferenceDatasetSchema = z.object({
     id: z.string().regex(SAFE_ID, "Expected a stable lowercase dataset id"),
@@ -112,14 +97,14 @@ function deepFreeze(value) {
 /**
  * Canonical release catalog. Every artifact is fetched directly from the third
  * party that publishes it; this project hosts, mirrors, and redistributes
- * nothing. Entries are added only with real upstream URLs, provenance, and
- * licensing data — plus a size and digest whenever the upstream publishes
- * immutable bytes we can pin to.
+ * nothing. Entries are added with a real upstream https URL, provenance, and
+ * licensing data — and nothing else per file: no size, no digest to compute or
+ * keep in sync.
  *
  * `version` is the dataset's upstream release identifier. Datasets built on an
  * upstream that has no immutable release — NCBI regenerates `gene_info` daily,
  * Reactome overwrites `current` and deletes prior releases — are versioned
- * `current` and carry `unpinned` artifacts.
+ * `current`; those with an immutable release carry it verbatim.
  */
 export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.parse({
     version: REFERENCE_DATA_CATALOG_VERSION,
@@ -137,7 +122,6 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "gene-identifiers", recommended: true },
             artifacts: [
                 {
-                    integrity: "unpinned",
                     path: "Homo_sapiens.gene_info.gz",
                     url: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/GENE_INFO/Mammalia/Homo_sapiens.gene_info.gz",
                 },
@@ -156,7 +140,6 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "gene-identifiers", recommended: true },
             artifacts: [
                 {
-                    integrity: "unpinned",
                     path: "Mus_musculus.gene_info.gz",
                     url: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/GENE_INFO/Mammalia/Mus_musculus.gene_info.gz",
                 },
@@ -175,12 +158,85 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "gene-identifiers", recommended: true },
             artifacts: [
                 {
-                    integrity: "unpinned",
                     path: "Rattus_norvegicus.gene_info.gz",
                     url: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/GENE_INFO/Mammalia/Rattus_norvegicus.gene_info.gz",
                 },
             ],
         },
+        {
+            // All-species monolithic table (~274 MB), not the per-organism split the gene_info entries use:
+            // NCBI publishes Entrez↔Ensembl only in this one combined file. Opt-in for that reason.
+            id: "ncbi-gene2ensembl",
+            version: "current",
+            title: "NCBI Entrez-to-Ensembl gene mapping (all species)",
+            description: "NCBI Gene's Entrez Gene ID ↔ Ensembl gene/transcript/protein identifier cross-reference for every species (gene2ensembl), tab-separated and gzipped — roughly 274 MB. NCBI rebuilds this file in place, so it is verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/",
+            license: {
+                identifier: "NCBI-Molecular-Data-Usage-Policy",
+                url: "https://www.ncbi.nlm.nih.gov/home/about/policies/",
+            },
+            recommendation: { group: "gene-identifiers", recommended: false },
+            artifacts: [{ path: "gene2ensembl.gz", url: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/gene2ensembl.gz" }],
+        },
+        {
+            // ~2.2 GB all-species monolithic table — the largest catalog entry. Opt-in like reactome-mappings.
+            id: "ncbi-gene2refseq",
+            version: "current",
+            title: "NCBI Entrez-to-RefSeq accession mapping (all species, large)",
+            description: "NCBI Gene's Entrez Gene ID ↔ RefSeq RNA/protein/genomic accession cross-reference for every species (gene2refseq), tab-separated and gzipped — roughly 2.2 GB. NCBI rebuilds this file in place, so it is verified against what you downloaded rather than a checked-in digest. Only needed to join RefSeq accessions onto genes.",
+            sourceUrl: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/",
+            license: {
+                identifier: "NCBI-Molecular-Data-Usage-Policy",
+                url: "https://www.ncbi.nlm.nih.gov/home/about/policies/",
+            },
+            recommendation: { group: "gene-identifiers", recommended: false },
+            artifacts: [{ path: "gene2refseq.gz", url: "https://ftp.ncbi.nlm.nih.gov/gene/DATA/gene2refseq.gz" }],
+        },
+        {
+            id: "uniprot-idmapping-human",
+            version: "current",
+            title: "UniProt human ID mapping",
+            description: "UniProtKB accession ↔ Entrez, Ensembl, RefSeq and other identifiers for Homo sapiens (idmapping_selected, ~61 MB gzipped). UniProt overwrites `current_release` each cycle, so it is verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/",
+            license: { identifier: "CC-BY-4.0", url: "https://www.uniprot.org/help/license" },
+            recommendation: { group: "gene-identifiers", recommended: true },
+            artifacts: [
+                {
+                    path: "HUMAN_9606_idmapping_selected.tab.gz",
+                    url: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/HUMAN_9606_idmapping_selected.tab.gz",
+                },
+            ],
+        },
+        {
+            id: "uniprot-idmapping-mouse",
+            version: "current",
+            title: "UniProt mouse ID mapping",
+            description: "UniProtKB accession ↔ Entrez, Ensembl, RefSeq and other identifiers for Mus musculus (idmapping_selected, ~18 MB gzipped). UniProt overwrites `current_release` each cycle, so it is verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/",
+            license: { identifier: "CC-BY-4.0", url: "https://www.uniprot.org/help/license" },
+            recommendation: { group: "gene-identifiers", recommended: true },
+            artifacts: [
+                {
+                    path: "MOUSE_10090_idmapping_selected.tab.gz",
+                    url: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/MOUSE_10090_idmapping_selected.tab.gz",
+                },
+            ],
+        },
+        {
+            id: "uniprot-idmapping-rat",
+            version: "current",
+            title: "UniProt rat ID mapping",
+            description: "UniProtKB accession ↔ Entrez, Ensembl, RefSeq and other identifiers for Rattus norvegicus (idmapping_selected, ~6 MB gzipped). UniProt overwrites `current_release` each cycle, so it is verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/",
+            license: { identifier: "CC-BY-4.0", url: "https://www.uniprot.org/help/license" },
+            recommendation: { group: "gene-identifiers", recommended: true },
+            artifacts: [
+                {
+                    path: "RAT_10116_idmapping_selected.tab.gz",
+                    url: "https://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/by_organism/RAT_10116_idmapping_selected.tab.gz",
+                },
+            ],
+        },
         {
             id: "reactome-pathways",
             version: "current",
@@ -190,8 +246,8 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             license: { identifier: "CC0-1.0", url: "https://reactome.org/license" },
             recommendation: { group: "pathways", recommended: true },
             artifacts: [
-                { integrity: "unpinned", path: "ReactomePathways.gmt", url: "https://reactome.org/download/current/ReactomePathways.gmt" },
-                { integrity: "unpinned", path: "ReactomePathways.txt", url: "https://reactome.org/download/current/ReactomePathways.txt" },
+                { path: "ReactomePathways.gmt", url: "https://reactome.org/download/current/ReactomePathways.gmt" },
+                { path: "ReactomePathways.txt", url: "https://reactome.org/download/current/ReactomePathways.txt" },
             ],
         },
         {
@@ -208,17 +264,14 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "pathways", recommended: false },
             artifacts: [
                 {
-                    integrity: "unpinned",
                     path: "NCBI2Reactome_All_Levels.txt",
                     url: "https://reactome.org/download/current/NCBI2Reactome_All_Levels.txt",
                 },
                 {
-                    integrity: "unpinned",
                     path: "Ensembl2Reactome_All_Levels.txt",
                     url: "https://reactome.org/download/current/Ensembl2Reactome_All_Levels.txt",
                 },
                 {
-                    integrity: "unpinned",
                     path: "UniProt2Reactome_All_Levels.txt",
                     url: "https://reactome.org/download/current/UniProt2Reactome_All_Levels.txt",
                 },
@@ -234,11 +287,68 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "pathways", recommended: true },
             artifacts: [
                 {
-                    integrity: "pinned",
                     path: "wikipathways_Homo_sapiens.gmt",
                     url: "https://data.wikipathways.org/20260710/gmt/wikipathways-20260710-gmt-Homo_sapiens.gmt",
-                    bytes: 341_474,
-                    sha256: "79615a079246bb0b07cc3505265b1f75ea6cffec88001ce27f644dd86a39c97d",
+                },
+            ],
+        },
+        {
+            id: "wikipathways-mouse",
+            version: "2026.07.10",
+            title: "WikiPathways mouse pathways",
+            description: "Community-curated Mus musculus pathway gene sets (GMT) from the immutable 2026-07-10 WikiPathways snapshot.",
+            sourceUrl: "https://data.wikipathways.org/20260710/gmt/",
+            license: { identifier: "CC0-1.0", url: "https://www.wikipathways.org/about/terms.html" },
+            recommendation: { group: "pathways", recommended: true },
+            artifacts: [
+                {
+                    path: "wikipathways_Mus_musculus.gmt",
+                    url: "https://data.wikipathways.org/20260710/gmt/wikipathways-20260710-gmt-Mus_musculus.gmt",
+                },
+            ],
+        },
+        {
+            id: "wikipathways-rat",
+            version: "2026.07.10",
+            title: "WikiPathways rat pathways",
+            description: "Community-curated Rattus norvegicus pathway gene sets (GMT) from the immutable 2026-07-10 WikiPathways snapshot.",
+            sourceUrl: "https://data.wikipathways.org/20260710/gmt/",
+            license: { identifier: "CC0-1.0", url: "https://www.wikipathways.org/about/terms.html" },
+            recommendation: { group: "pathways", recommended: true },
+            artifacts: [
+                {
+                    path: "wikipathways_Rattus_norvegicus.gmt",
+                    url: "https://data.wikipathways.org/20260710/gmt/wikipathways-20260710-gmt-Rattus_norvegicus.gmt",
+                },
+            ],
+        },
+        {
+            id: "msigdb-hallmark-human",
+            version: "2026.1",
+            title: "MSigDB human hallmark gene sets",
+            description: "The 50 MSigDB hallmark gene sets for Homo sapiens (symbols GMT) — coherent, well-defined biological states and processes for enrichment. From the immutable MSigDB 2026.1 human release.",
+            sourceUrl: "https://data.broadinstitute.org/gsea-msigdb/msigdb/",
+            license: { identifier: "MSigDB-License", url: "https://www.gsea-msigdb.org/gsea/msigdb/license.jsp" },
+            recommendation: { group: "pathways", recommended: true },
+            artifacts: [
+                {
+                    path: "h.all.v2026.1.Hs.symbols.gmt",
+                    url: "https://data.broadinstitute.org/gsea-msigdb/msigdb/release/2026.1.Hs/h.all.v2026.1.Hs.symbols.gmt",
+                },
+            ],
+        },
+        {
+            id: "msigdb-hallmark-mouse",
+            version: "2026.1",
+            title: "MSigDB mouse hallmark gene sets",
+            description: "The MSigDB mouse hallmark gene sets for Mus musculus (symbols GMT) — the murine ortholog-mapped hallmark collection for enrichment. From the immutable MSigDB 2026.1 mouse release.",
+            sourceUrl: "https://data.broadinstitute.org/gsea-msigdb/msigdb/",
+            license: { identifier: "MSigDB-License", url: "https://www.gsea-msigdb.org/gsea/msigdb/license.jsp" },
+            recommendation: { group: "pathways", recommended: true },
+            artifacts: [
+                {
+                    path: "mh.all.v2026.1.Mm.symbols.gmt",
+                    url: "https://data.broadinstitute.org/gsea-msigdb/msigdb/release/2026.1.Mm/mh.all.v2026.1.Mm.symbols.gmt",
                 },
             ],
         },
@@ -252,11 +362,8 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "regulatory-networks", recommended: true },
             artifacts: [
                 {
-                    integrity: "pinned",
                     path: "CollecTRI_regulons.csv",
                     url: "https://zenodo.org/records/8192729/files/CollecTRI_regulons.csv",
-                    bytes: 4_345_649,
-                    sha256: "4473c9189dd53dacc80297709ad1452dda1086a1cc2185f9a56146c261668701",
                 },
             ],
         },
@@ -270,21 +377,25 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "normal-expression", recommended: true },
             artifacts: [
                 {
-                    integrity: "pinned",
                     path: "GTEx_Analysis_2017-06-05_v8_RNASeQCv1.1.9_gene_median_tpm.gct.gz",
                     url: "https://storage.googleapis.com/adult-gtex/bulk-gex/v8/rna-seq/GTEx_Analysis_2017-06-05_v8_RNASeQCv1.1.9_gene_median_tpm.gct.gz",
-                    bytes: 6_952_331,
-                    sha256: "ee7201ff2f280b0de5657d4b08e9a240362d9757efed7f7bd5dba35a5f8617b8",
                 },
                 {
-                    integrity: "pinned",
                     path: "GTEx_Analysis_v8_Annotations_SampleAttributesDS.txt",
                     url: "https://storage.googleapis.com/adult-gtex/annotations/v8/metadata-files/GTEx_Analysis_v8_Annotations_SampleAttributesDS.txt",
-                    bytes: 11_512_258,
-                    sha256: "74f6ab4c34ed2648d708a0ae6e6dff324f6c86ea723ae7d1c37d76f5221148f0",
                 },
             ],
         },
+        {
+            id: "hpa-proteinatlas",
+            version: "current",
+            title: "Human Protein Atlas",
+            description: "The full Human Protein Atlas table (proteinatlas.tsv.zip, ~7 MB): per-gene RNA/protein tissue expression, tissue specificity, subcellular location, secretome and blood-concentration annotations for Homo sapiens. HPA republishes this file per release, so it is verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://www.proteinatlas.org/about/download",
+            license: { identifier: "CC-BY-SA-3.0", url: "https://www.proteinatlas.org/about/licence" },
+            recommendation: { group: "normal-expression", recommended: true },
+            artifacts: [{ path: "proteinatlas.tsv.zip", url: "https://www.proteinatlas.org/download/proteinatlas.tsv.zip" }],
+        },
         {
             id: "celltypist-immune",
             version: "2",
@@ -295,18 +406,112 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             recommendation: { group: "cell-typing", recommended: true },
             artifacts: [
                 {
-                    integrity: "pinned",
                     path: "Immune_All_Low.pkl",
                     url: "https://celltypist.cog.sanger.ac.uk/models/Pan_Immune_CellTypist/v2/Immune_All_Low.pkl",
-                    bytes: 2_824_990,
-                    sha256: "290874d35dac039d4c9218c343fde4aac1077709b72a331ce7266f6828c36502",
                 },
                 {
-                    integrity: "pinned",
                     path: "Immune_All_High.pkl",
                     url: "https://celltypist.cog.sanger.ac.uk/models/Pan_Immune_CellTypist/v2/Immune_All_High.pkl",
-                    bytes: 1_070_426,
-                    sha256: "a715fec36c2c421f7c4e31cf4cb4bea883eedab7fd7b20a4b76f091c22660448",
+                },
+            ],
+        },
+        {
+            id: "celltypist-pan-fetal",
+            version: "2",
+            title: "CellTypist pan-fetal human model",
+            description: "CellTypist Pan_Fetal_Human model — cell-type annotation across human fetal tissues. Load by absolute path; CellTypist's by-name lookup expects its own cache layout, which the reference store deliberately does not impersonate.",
+            sourceUrl: "https://www.celltypist.org/models",
+            license: { identifier: "NOASSERTION" },
+            recommendation: { group: "cell-typing", recommended: true },
+            artifacts: [
+                {
+                    path: "Pan_Fetal_Human.pkl",
+                    url: "https://celltypist.cog.sanger.ac.uk/models/Pan_Fetal_Suo/v2/Pan_Fetal_Human.pkl",
+                },
+            ],
+        },
+        {
+            id: "celltypist-covid19",
+            version: "1",
+            title: "CellTypist COVID-19 immune model",
+            description: "CellTypist COVID19_Immune_Landscape model — immune cell-type annotation trained on the cross-study COVID-19 immune atlas. Load by absolute path; CellTypist's by-name lookup expects its own cache layout, which the reference store deliberately does not impersonate.",
+            sourceUrl: "https://www.celltypist.org/models",
+            license: { identifier: "NOASSERTION" },
+            recommendation: { group: "cell-typing", recommended: true },
+            artifacts: [
+                {
+                    path: "COVID19_Immune_Landscape.pkl",
+                    url: "https://celltypist.cog.sanger.ac.uk/models/COVID19_Immune_Ren/v1/COVID19_Immune_Landscape.pkl",
+                },
+            ],
+        },
+        {
+            id: "panglaodb-markers",
+            version: "2020.03.27",
+            title: "PanglaoDB cell-type markers",
+            description: "PanglaoDB cell-type marker panel (tab-separated, gzipped): curated marker genes per cell type across human and mouse, for marker-based annotation. From the immutable 27 March 2020 PanglaoDB marker release.",
+            sourceUrl: "https://panglaodb.se/markers.html",
+            license: { identifier: "NOASSERTION" },
+            recommendation: { group: "cell-typing", recommended: true },
+            artifacts: [
+                {
+                    path: "PanglaoDB_markers_27_Mar_2020.tsv.gz",
+                    url: "https://panglaodb.se/markers/PanglaoDB_markers_27_Mar_2020.tsv.gz",
+                },
+            ],
+        },
+        {
+            id: "azimuth-pbmc",
+            version: "1.0.0",
+            title: "Azimuth human PBMC reference",
+            description: "Azimuth annotated reference for human peripheral blood mononuclear cells: the Seurat reference object plus its Annoy nearest-neighbour index, for supervised mapping and cell-type label transfer. Immutable Zenodo release 4546839.",
+            sourceUrl: "https://zenodo.org/records/4546839",
+            license: { identifier: "CC-BY-4.0", url: "https://zenodo.org/records/4546839" },
+            recommendation: { group: "cell-typing", recommended: true },
+            artifacts: [
+                {
+                    path: "ref.Rds",
+                    url: "https://zenodo.org/records/4546839/files/ref.Rds",
+                },
+                {
+                    path: "idx.annoy",
+                    url: "https://zenodo.org/records/4546839/files/idx.annoy",
+                },
+            ],
+        },
+        {
+            // ~443 MB (ref + index), so it is opt-in rather than part of a default setup.
+            id: "azimuth-tonsil",
+            version: "1.0.0",
+            title: "Azimuth human tonsil reference",
+            description: "Azimuth annotated reference for human tonsil: the Seurat reference object plus its Annoy nearest-neighbour index, for supervised mapping and cell-type label transfer. Immutable Zenodo release 7032928, roughly 443 MB.",
+            sourceUrl: "https://zenodo.org/records/7032928",
+            license: { identifier: "CC-BY-4.0", url: "https://zenodo.org/records/7032928" },
+            recommendation: { group: "cell-typing", recommended: false },
+            artifacts: [
+                {
+                    path: "ref.Rds",
+                    url: "https://zenodo.org/records/7032928/files/ref.Rds",
+                },
+                {
+                    path: "idx.annoy",
+                    url: "https://zenodo.org/records/7032928/files/idx.annoy",
+                },
+            ],
+        },
+        {
+            // ~842 MB reference genome bundle, PGx-specific, so it is opt-in rather than a default download.
+            id: "pharmcat-grch38-fasta",
+            version: "GRCh38.p13",
+            title: "PharmCAT GRCh38 reference FASTA",
+            description: "The GRCh38.p13 reference genome FASTA that PharmCAT's VCF preprocessor expects (bgzip'd with a .fai/.gzi faidx), bundled as a tar — roughly 842 MB. Immutable Zenodo release 7288118. Needed only for pharmacogenomics (PharmCAT) workflows.",
+            sourceUrl: "https://zenodo.org/records/7288118",
+            license: { identifier: "CC-BY-4.0", url: "https://zenodo.org/records/7288118" },
+            recommendation: { group: "pharmacogenomics", recommended: false },
+            artifacts: [
+                {
+                    path: "PharmCAT_GRCh38_reference_fasta.tar",
+                    url: "https://zenodo.org/records/7288118/files/GRCh38_reference_fasta.tar?download=1",
                 },
             ],
         },

package/dist/reference-data/receipt.d.ts

@@ -3,19 +3,15 @@ import { z } from "zod";
 export declare const REFERENCE_INSTALL_RECEIPT_VERSION: 1;
 /**
  * What was actually written to disk for one artifact. The size and digest are
- * *observed at install*, never copied from the catalog — for a `pinned`
- * artifact they equal the catalog's (the install would have failed otherwise),
- * and for an `unpinned` one they are the only record of what the mutable
- * upstream served, which is what `verify` later checks the files against.
+ * *observed at install* — the catalog carries neither, so this receipt is the
+ * sole record of the bytes the upstream served, and what `verify` later checks
+ * the local files against. A receipt written by an older build may still carry
+ * an `integrity` field; it is simply ignored (unknown keys are stripped).
  */
 declare const ReferenceReceiptArtifactSchema: z.ZodObject<{
     path: z.ZodString;
     bytes: z.ZodNumber;
     sha256: z.ZodString;
-    integrity: z.ZodEnum<{
-        pinned: "pinned";
-        unpinned: "unpinned";
-    }>;
 }, z.core.$strip>;
 /** Optional metadata describing one activated reference dataset version. */
 export declare const ReferenceInstallReceiptSchema: z.ZodObject<{
@@ -27,10 +23,6 @@ export declare const ReferenceInstallReceiptSchema: z.ZodObject<{
         path: z.ZodString;
         bytes: z.ZodNumber;
         sha256: z.ZodString;
-        integrity: z.ZodEnum<{
-            pinned: "pinned";
-            unpinned: "unpinned";
-        }>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReferenceInstallReceipt = z.infer<typeof ReferenceInstallReceiptSchema>;

package/dist/reference-data/receipt.js

@@ -4,16 +4,15 @@ import { ReferenceArtifactPathSchema, ReferenceDatasetSchema, ReferenceSha256Sch
 export const REFERENCE_INSTALL_RECEIPT_VERSION = 1;
 /**
  * What was actually written to disk for one artifact. The size and digest are
- * *observed at install*, never copied from the catalog — for a `pinned`
- * artifact they equal the catalog's (the install would have failed otherwise),
- * and for an `unpinned` one they are the only record of what the mutable
- * upstream served, which is what `verify` later checks the files against.
+ * *observed at install* — the catalog carries neither, so this receipt is the
+ * sole record of the bytes the upstream served, and what `verify` later checks
+ * the local files against. A receipt written by an older build may still carry
+ * an `integrity` field; it is simply ignored (unknown keys are stripped).
  */
 const ReferenceReceiptArtifactSchema = z.object({
     path: ReferenceArtifactPathSchema,
     bytes: z.number().int().nonnegative(),
     sha256: ReferenceSha256Schema,
-    integrity: z.enum(["pinned", "unpinned"]),
 });
 /** Optional metadata describing one activated reference dataset version. */
 export const ReferenceInstallReceiptSchema = z

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",