@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -6,13 +6,6 @@ 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;
-/**
- * Logical content format, independent of compression: a `.txt.gz` mapping table
- * is `tsv`, not `gz`. Agents pick a reader from this rather than guessing from
- * the extension, so it stays a free token instead of an enum — a new source must
- * remain cheap to add, and an unrecognized format degrades to "unknown reader"
- * rather than failing catalog validation.
- */
 export declare const ReferenceArtifactFormatSchema: z.ZodString;
 /**
  * One final file distributed for a reference dataset: a stable install-relative
@@ -35,12 +28,6 @@ export declare const ReferenceArtifactSchema: z.ZodObject<{
     format: z.ZodString;
     contents: z.ZodString;
 }, z.core.$strict>;
-/**
- * Common-name organism the dataset describes, lowercase (`human`, `mouse`, `rat`).
- * Omitted for species-agnostic or multi-species sources. This is the axis a wrong
- * choice is most silently wrong on — human regulons over mouse counts still run —
- * so it is a first-class field rather than something inferred from the id suffix.
- */
 export declare const ReferenceOrganismSchema: z.ZodString;
 /** Provenance and licensing information for one supported reference dataset. */
 export declare const ReferenceDatasetSchema: z.ZodObject<{
@@ -128,10 +115,10 @@ export type ReferenceInstallPlanDataset = ReferenceDataset & {
     readonly installPath: string;
 };
 /** Deterministic plan; every artifact carries the upstream URL it is fetched from. */
-export interface ReferenceInstallPlan {
+export type ReferenceInstallPlan = {
     readonly catalogVersion: typeof REFERENCE_DATA_CATALOG_VERSION;
     readonly datasets: readonly ReferenceInstallPlanDataset[];
-}
+};
 /** A requested dataset id was not present in the selected catalog. */
 export declare class UnknownReferenceDatasetError extends Error {
     readonly code: "unknown_reference_dataset";

package/dist/reference-data/catalog.js

@@ -1,10 +1,16 @@
 import { posix as posixPath } from "node:path";
 import { err, ok } from "neverthrow";
+import { presentGet } from "../lib/present.js";
+import { isUnknownArray } from "../lib/unknown-array.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { z } from "zod";
 /** Schema version for the checked-in reference-data catalog. */
 export const REFERENCE_DATA_CATALOG_VERSION = 1;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a dataset id is lowercase segments joined by one separator; the shape is the stable-id rule.
 const SAFE_ID = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a version is alphanumeric segments joined by one separator; the shape is the path-segment rule.
 const SAFE_VERSION = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a lowercase SHA-256 digest is 64 hex digits, the fixed digest shape.
 const SHA256 = /^[a-f0-9]{64}$/;
 function isSafeRelativePath(value) {
     if (value.length === 0 || value.includes("\\") || value.startsWith("/"))
@@ -28,7 +34,9 @@ const ReferenceArtifactUrlSchema = z.url().refine((value) => value.startsWith("h
  * remain cheap to add, and an unrecognized format degrades to "unknown reader"
  * rather than failing catalog validation.
  */
-export const ReferenceArtifactFormatSchema = z.string().regex(/^[a-z0-9]+(?:[+-][a-z0-9]+)*$/, "Expected a lowercase format token");
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a format token is lowercase segments joined by one plus sign, the free-token rule the reader table keys on.
+const FORMAT_TOKEN_RE = /^[a-z0-9]+(?:[+-][a-z0-9]+)*$/;
+export const ReferenceArtifactFormatSchema = z.string().regex(FORMAT_TOKEN_RE, "Expected a lowercase format token");
 /**
  * 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
@@ -56,7 +64,9 @@ export const ReferenceArtifactSchema = z.strictObject({
  * choice is most silently wrong on — human regulons over mouse counts still run —
  * so it is a first-class field rather than something inferred from the id suffix.
  */
-export const ReferenceOrganismSchema = z.string().regex(/^[a-z][a-z0-9]*(?:[ -][a-z0-9]+)*$/, "Expected a lowercase organism common name");
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- an organism common name is lowercase words joined by a space or hyphen; the shape keeps the search axis one canonical form.
+const ORGANISM_NAME_RE = /^[a-z][a-z0-9]*(?:[ -][a-z0-9]+)*$/;
+export const ReferenceOrganismSchema = z.string().regex(ORGANISM_NAME_RE, "Expected a lowercase organism common name");
 /** 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"),
@@ -109,12 +119,19 @@ export const ReferenceDataCatalogSchema = z
 export function referenceArtifactKey(dataset, artifact) {
     return `${dataset.id}/${dataset.version}/${artifact.path}`;
 }
+// The walk freezes the original container: a rebuild would freeze a copy and
+// leave the real value mutable. z.custom passes the value through on success, so
+// the check decides "record or array" without producing a second object.
+const FreezableContainer = z.custom((value) => isUnknownArray(value) || parseUnknownRecord(value) !== undefined);
 function deepFreeze(value) {
-    if (value && typeof value === "object" && !Object.isFrozen(value)) {
-        for (const nested of Object.values(value))
-            deepFreeze(nested);
-        Object.freeze(value);
-    }
+    const parsed = FreezableContainer.safeParse(value);
+    if (!parsed.success)
+        return value;
+    if (Object.isFrozen(parsed.data))
+        return value;
+    for (const nested of Object.values(parsed.data))
+        deepFreeze(nested);
+    Object.freeze(parsed.data);
     return value;
 }
 /**
@@ -294,6 +311,30 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
                 },
             ],
         },
+        {
+            // Two species in one table: no organism field, like omnipath-interactions.
+            id: "mgi-mouse-human-homology",
+            version: "current",
+            title: "MGI mouse-human homology classes",
+            description: "The Mouse Genome Informatics homology reports: the one-to-one mouse-to-human orthologs of the protein-coding genes, and the full homology classes with the sequence identifiers. MGI rebuilds the reports weekly, so they are verified against what you downloaded rather than a checked-in digest.",
+            sourceUrl: "https://www.informatics.jax.org/downloads/reports/index.html",
+            license: { identifier: "CC-BY-4.0", url: "https://www.informatics.jax.org/mgihome/other/copyright.shtml" },
+            recommendation: { group: "gene-identifiers", recommended: false },
+            artifacts: [
+                {
+                    path: "HOM_ProteinCoding.rpt",
+                    url: "https://www.informatics.jax.org/downloads/reports/HOM_ProteinCoding.rpt",
+                    format: "tsv",
+                    contents: "Tab-separated, NO header, about 780 KB, one row per mouse protein-coding gene with a one-to-one human ortholog. Positional columns: 1 MGI accession id, 2 mouse symbol, 3 mouse NCBI gene id, 4 HGNC id, 5 human symbol, 6 human NCBI gene id. The first choice for a mouse-to-human map.",
+                },
+                {
+                    path: "HOM_MouseHumanSequence.rpt",
+                    url: "https://www.informatics.jax.org/downloads/reports/HOM_MouseHumanSequence.rpt",
+                    format: "tsv",
+                    contents: "Tab-separated with a header, about 15 MB, one row per gene. The rows that share a 'DB Class Key' are one homology class across the two species, and a class can hold more than one gene of one species. Key columns: 'Common Organism Name' (mouse, laboratory or human), 'NCBI Taxon ID', Symbol, 'EntrezGene ID', 'Mouse MGI ID', 'HGNC ID'. Use it for a gene absent from the one-to-one file, and report the class size.",
+                },
+            ],
+        },
         {
             id: "reactome-pathways",
             version: "current",
@@ -802,7 +843,7 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
             id: "string-ppi-human",
             version: "12.0",
             title: "STRING human protein-protein interaction network",
-            description: "STRING v12.0 functional protein association network for Homo sapiens: every protein pair with a combined confidence score, the genome-scale graph network-proximity methods measure distances over. Roughly 85 MB across two files — the network itself and the identifier mapping it cannot be read without. Immutable v12.0 release.",
+            description: "STRING v12.0 functional protein association network for Homo sapiens: every protein pair with a combined confidence score, the genome-scale graph network-proximity methods measure distances over. Roughly 85 MB across two files — the network itself and the identifier mapping it cannot be read without. For an exact join to an Ensembl-keyed table, add `string-aliases-human`. Immutable v12.0 release.",
             organism: "human",
             sourceUrl: "https://string-db.org/cgi/access",
             license: { identifier: "CC-BY-4.0", url: "https://creativecommons.org/licenses/by/4.0/" },
@@ -818,7 +859,28 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
                     path: "9606.protein.info.v12.0.txt.gz",
                     url: "https://stringdb-downloads.org/download/protein.info.v12.0/9606.protein.info.v12.0.txt.gz",
                     format: "tsv",
-                    contents: "Gzipped TSV, ~19,700 rows, header '#string_protein_id preferred_name protein_size annotation'. Mandatory rather than supplementary: preferred_name is the gene symbol for each STRING id in the links file, and without this join the network cannot be connected to a gene list, a drug-target set, or any other dataset here.",
+                    contents: "Gzipped TSV, ~19,700 rows, header '#string_protein_id preferred_name protein_size annotation'. Mandatory rather than supplementary: preferred_name is the only name this dataset gives each STRING id of the links file, so without this join the network carries no gene names at all. preferred_name is a symbol, and a symbol join silently drops a renamed gene: for an exact identifier join, add `string-aliases-human` and key on its Ensembl gene id rows instead.",
+                },
+            ],
+        },
+        {
+            // The companion of string-ppi-human. It is its own dataset because a new
+            // artifact on an installed dataset at the same version invalidates the
+            // receipt of every existing install and forces a full re-download.
+            id: "string-aliases-human",
+            version: "12.0",
+            title: "STRING human protein aliases",
+            description: "The STRING v12.0 alias table for Homo sapiens: every external identifier of each STRING protein, with its source. The companion of `string-ppi-human`: its Ensembl gene id rows give the exact join from the STRING network to a GTEx or a GENCODE table, which the symbol of the info file does not give for a renamed gene. About 20 MB. Immutable v12.0 release.",
+            organism: "human",
+            sourceUrl: "https://string-db.org/cgi/access",
+            license: { identifier: "CC-BY-4.0", url: "https://creativecommons.org/licenses/by/4.0/" },
+            recommendation: { group: "interaction-networks", recommended: false },
+            artifacts: [
+                {
+                    path: "9606.protein.aliases.v12.0.txt.gz",
+                    url: "https://stringdb-downloads.org/download/protein.aliases.v12.0/9606.protein.aliases.v12.0.txt.gz",
+                    format: "tsv",
+                    contents: "Gzipped TSV, about 20 MB, header '#string_protein_id alias source', many rows per protein. Filter source == 'Ensembl_gene' to get one Ensembl gene id (ENSG) per STRING protein id: the exact join key to a GTEx or a GENCODE table, which the symbol of the info file does not give for a renamed gene.",
                 },
             ],
         },
@@ -864,6 +926,100 @@ export const REFERENCE_DATA_CATALOG = deepFreeze(ReferenceDataCatalogSchema.pars
                 },
             ],
         },
+        {
+            id: "impc-phenotyping",
+            version: "release-24.0",
+            title: "IMPC mouse knockout phenotyping, data release 24.0",
+            description: "The International Mouse Phenotyping Consortium data release 24.0 reports: the significant genotype-to-phenotype assertions, the viability calls, and the procedure completeness of each phenotyped colony. Immutable release directory.",
+            organism: "mouse",
+            sourceUrl: "https://ftp.ebi.ac.uk/pub/databases/impc/all-data-releases/release-24.0/results/",
+            license: { identifier: "CC-BY-4.0", url: "https://www.mousephenotype.org/help/faqs/is-impc-data-freely-available/" },
+            recommendation: { group: "phenotype-annotations", recommended: false },
+            artifacts: [
+                {
+                    path: "genotype-phenotype-assertions-ALL.csv.gz",
+                    url: "https://ftp.ebi.ac.uk/pub/databases/impc/all-data-releases/release-24.0/results/genotype-phenotype-assertions-ALL.csv.gz",
+                    format: "csv",
+                    contents: "Gzipped CSV with a header, about 4.8 MB, one row per significant genotype-phenotype association. Key columns: marker_accession_id (MGI id), marker_symbol, zygosity, top_level_mp_term_id, top_level_mp_term_name, mp_term_id, mp_term_name, p_value, effect_size, resource_name (IMPC, EuroPhenome, MGP, 3i, pwg — matched case-sensitively). zygosity is hemizygote, heterozygote, or homozygote. top_level_mp_term_id holds a comma-separated list on 13,643 of its 67,350 rows, so split it and test membership: equality against MP:0005370 (liver and biliary system) returns 509 rows over 322 genes, membership returns 612 over 351. A gene absent here was either clean or never tested: the completeness file tells which.",
+                },
+                {
+                    path: "procedureCompletenessAndPhenotypeHits.csv.gz",
+                    url: "https://ftp.ebi.ac.uk/pub/databases/impc/all-data-releases/release-24.0/results/procedureCompletenessAndPhenotypeHits.csv.gz",
+                    format: "csv",
+                    contents: "Gzipped CSV with a quoted header, about 24 MB, one row per gene, colony, zygosity, and life stage. The '|'-separated columns 'Procedure Stable Id: Successful' and 'Parameter Name: Successful' say what was tested (the clinical chemistry procedure ids share the prefix IMPC_CBC_, with versions such as IMPC_CBC_001, and parameter names written out in full — 'Alanine aminotransferase', 'Aspartate aminotransferase', 'Alkaline phosphatase', 'Total bilirubin' — never abbreviated to ALT or AST); 'Top-level MP Accession Id: Significant' and 'MP Accession Id: Significant' say what was found. 'Life Stage' is one of seven values, 'Early adult' among them, and 'Zygosity' includes hemizygote beside homozygote and heterozygote. The only file that separates a gene tested with no hit from a gene never tested.",
+                },
+                {
+                    path: "viability.csv.gz",
+                    url: "https://ftp.ebi.ac.uk/pub/databases/impc/all-data-releases/release-24.0/results/viability.csv.gz",
+                    format: "csv",
+                    contents: "Gzipped CSV with a quoted header, about 470 KB, one row per colony and zygosity. Key columns: 'Gene Accession Id' (MGI id), 'Gene Symbol', 'Zygosity', 'Viability Phenotype HOMs/HEMIs' (lowercase: lethal, subviable, viable), 'Supporting Data' (the long form, for example 'Homozygous - Viable'), 'Viability Call Method' (curated or computed). 'Zygosity' is homozygote or hemizygote, so an X-linked knockout carries a hemizygous call and no homozygous one. One gene can hold different calls on different colonies — 14 genes hold both a lethal and a viable call — so lethal takes precedence over subviable and over viable within one gene.",
+                },
+            ],
+        },
+        {
+            id: "hpo-annotations",
+            version: "2026-09-01",
+            title: "Human Phenotype Ontology gene-to-phenotype annotations",
+            description: "The HPO release 2026-09-01: the gene-to-phenotype annotation table derived from OMIM and Orphanet, with the ontology file that gives the term hierarchy. Immutable GitHub release assets.",
+            organism: "human",
+            sourceUrl: "https://github.com/obophenotype/human-phenotype-ontology/releases/tag/v2026-09-01",
+            // The HPO license has no SPDX identifier. Its page gives three conditions: cite the
+            // HPO Consortium, show the version of each HPO file in a public display, and do not
+            // change the files. The installer fetches the files from the upstream and changes
+            // nothing; the acknowledgement in a product is the concern of the product.
+            license: { identifier: "LicenseRef-HPO", url: "https://hpo.jax.org/app/license" },
+            recommendation: { group: "phenotype-annotations", recommended: false },
+            artifacts: [
+                {
+                    path: "genes_to_phenotype.txt",
+                    url: "https://github.com/obophenotype/human-phenotype-ontology/releases/download/v2026-09-01/genes_to_phenotype.txt",
+                    format: "tsv",
+                    contents: "Tab-separated with a header, about 20 MB. Columns: ncbi_gene_id (Entrez), gene_symbol, hpo_id, hpo_name, frequency, disease_id (OMIM or ORPHA). One row per gene, term, and disease, thus a gene repeats. The rows carry the annotated terms only, not their ancestors: take the descendant closure of a root term from hp.obo before a filter.",
+                },
+                {
+                    path: "hp.obo",
+                    url: "https://github.com/obophenotype/human-phenotype-ontology/releases/download/v2026-09-01/hp.obo",
+                    format: "obo",
+                    contents: "The ontology in OBO format, about 11 MB: one [Term] stanza per HP term with id, name, and is_a parents. Walk the is_a edges to take the descendants of a root term, for example HP:0001392 (Abnormality of the liver) or HP:0004297 (Abnormality of the biliary system).",
+                },
+            ],
+        },
+        {
+            // Mouse phenotypes keyed on human Ensembl ids: no single organism, like omnipath-interactions.
+            id: "opentargets-mouse-phenotype",
+            version: "26.09",
+            title: "Open Targets mouse model phenotypes mapped to human targets",
+            description: "The mouse_phenotype dataset of Open Targets Platform 26.09: the IMPC and the MGI literature phenotypes of mouse models, with the human target that Open Targets mapped each mouse gene to. One zstd parquet part. Immutable release.",
+            sourceUrl: "https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/26.09/output/mouse_phenotype/",
+            license: { identifier: "CC0-1.0", url: "https://platform-docs.opentargets.org/licence" },
+            recommendation: { group: "phenotype-annotations", recommended: false },
+            artifacts: [
+                {
+                    path: "mouse_phenotype.parquet",
+                    url: "https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/26.09/output/mouse_phenotype/part-00000-5e904527-9bf6-4fd5-9fc4-5f272954b1f8-c000.zstd.parquet",
+                    format: "parquet",
+                    contents: "Zstd parquet, about 6.5 MB, 203,583 rows, one row per human target, mouse gene, and phenotype term. Columns: targetFromSourceId (human Ensembl gene id), targetInModel (mouse symbol), targetInModelMgiId, targetInModelEnsemblId, modelPhenotypeId (MP id), modelPhenotypeLabel, modelPhenotypeClasses (list of top-level MP id and label), biologicalModels (allele, background, literature). Read with pandas and pyarrow. The mouse-to-human map is the one of Open Targets, which can differ from the MGI homology tables.",
+                },
+            ],
+        },
+        {
+            id: "opentargets-target-safety-event",
+            version: "26.09",
+            title: "Open Targets target safety events",
+            description: "The target_safety_event dataset of Open Targets Platform 26.09: curated safety liabilities per target from the published panels, ToxCast, AOP-Wiki, and ClinPGx, each with the organ or tissue of the event. One zstd parquet part. Immutable release.",
+            organism: "human",
+            sourceUrl: "https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/26.09/output/target_safety_event/",
+            license: { identifier: "CC0-1.0", url: "https://platform-docs.opentargets.org/licence" },
+            recommendation: { group: "phenotype-annotations", recommended: false },
+            artifacts: [
+                {
+                    path: "target_safety_event.parquet",
+                    url: "https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/26.09/output/target_safety_event/part-00000-e457d966-d50e-4afc-841d-547765a1e4d7-c000.zstd.parquet",
+                    format: "parquet",
+                    contents: "Zstd parquet, about 120 KB, 4,387 rows, one row per target and safety event. Columns: targetId (Ensembl gene id), event, eventId (EFO), effects (direction, dosing), biosamples (tissueLabel, tissueId as UBERON, cell fields), datasource, literature (PMID), studies. biosamples is null on 1,786 rows, so guard the test. tissueId carries one term in two spellings — UBERON_0002107 on 74 rows, UBERON:0002107 on 6 — and event is free text in mixed case ('Hepatotoxicity', 'Increased, Liver Steatosis'), so match both spellings and ignore case: a liver filter then flags 88 targets rather than 57. The sources are curated panels, not an exhaustive list: absence is not safety.",
+                },
+            ],
+        },
         {
             id: "celltypist-immune",
             version: "2",
@@ -1964,7 +2120,7 @@ export function resolveReferenceInstallPlanFromCatalogForTesting(datasetIds, cat
     return ok({
         catalogVersion: catalog.version,
         datasets: selectedIds.map((id) => {
-            const dataset = byId.get(id);
+            const dataset = presentGet(byId, id, "the selected dataset");
             return { ...dataset, installPath: `${dataset.id}/${dataset.version}` };
         }),
     });

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

@@ -13,11 +13,11 @@ declare const ReferenceReceiptArtifactSchema: z.ZodObject<{
     sha256: z.ZodString;
 }, z.core.$strip>;
 /** The fields of a receipt that identify the installed content. */
-export interface ReferenceReceiptContent {
+export type ReferenceReceiptContent = {
     readonly datasetId: string;
     readonly datasetVersion: string;
     readonly artifacts: readonly ReferenceReceiptArtifact[];
-}
+};
 /**
  * The identity of the installed bytes, independent of the install time. Consumers outside the
  * harness recompute it, so the input bytes are a contract: the SHA-256 of the compact JSON array

package/dist/report-model/assert-rules.js

@@ -93,5 +93,5 @@ export function checkCitationAssertion(reference, expected, resolved) {
     if (expected === undefined || expected === resolved) {
         return undefined;
     }
-    return { reference, reason: "assertion-failed", detail: `expected ${String(expected)} but resolved citation ${resolved}` };
+    return { reference, reason: "assertion-failed", detail: `expected ${expected} but resolved citation ${resolved}` };
 }