@inflexa-ai/harness 0.48.3 → 0.48.4

package/dist/memory/conversation-display-storage.js

@@ -19,7 +19,7 @@ import { textOf } from "../lib/unknown-text.js";
 import { isDataUIPart, validateUIMessages } from "ai";
 import { z } from "zod";
 import { parseUnknownRecord } from "../lib/unknown-containers.js";
-import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, ModelRefusalPayloadSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
+import { AnalogyReportPartSchema, AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, ModelRefusalPayloadSchema, PausePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
 import { ToolCallOutcomeSchema, ToolCallValueSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
 const DisplayEnvelopeHeaderSchema = z.object({
@@ -69,6 +69,7 @@ const ToolCallDisplaySchema = z.object({
 const dataSchemas = {
     "tool-call": ToolCallDisplaySchema,
     presentation: PresentationPartSchema.omit({ type: true }),
+    "analogy-report": AnalogyReportPartSchema.omit({ type: true }),
     plan: PlanPartSchema.omit({ type: true }),
     "run-card": RunCardPartSchema.omit({ type: true }),
     "plan-approval": PlanApprovalPartSchema.omit({ type: true }),
@@ -78,6 +79,7 @@ const dataSchemas = {
     "report-rendered": ReportRenderedPartSchema.omit({ type: true }),
     compaction: CompactionPartSchema.omit({ type: true }),
     "model-refusal": ModelRefusalPayloadSchema,
+    pause: PausePartSchema.omit({ type: true }),
     "subagent-activity": SubAgentActivityPartSchema.omit({ type: true }).extend({
         entries: z.array(SubAgentActivityEntrySchema.extend({ outcome: ToolCallOutcomeSchema })),
     }),
@@ -175,6 +177,7 @@ export async function parseStoredDisplayEnvelope(value, identity, logger) {
 const STORED_SOURCE_TYPES = [
     "tool-call",
     "data-presentation",
+    "data-analogy-report",
     "data-plan",
     "data-run-card",
     "data-plan-approval",
@@ -184,6 +187,7 @@ const STORED_SOURCE_TYPES = [
     "data-report-rendered",
     "data-compaction",
     "data-model-refusal",
+    "data-pause",
     "data-subagent-activity",
 ];
 const STORED_SOURCE_TYPE_SET = new Set(STORED_SOURCE_TYPES);
@@ -225,6 +229,10 @@ export function conversationDisplayPart(part) {
             const { type: _type, ...data } = part;
             return { type: "data-presentation", id, data };
         }
+        case "data-analogy-report": {
+            const { type: _type, ...data } = part;
+            return { type: "data-analogy-report", id, data };
+        }
         case "data-plan": {
             const { type: _type, ...data } = part;
             return { type: "data-plan", id, data };
@@ -261,6 +269,10 @@ export function conversationDisplayPart(part) {
             const { type: _type, ...data } = part;
             return { type: "data-model-refusal", id, data };
         }
+        case "data-pause": {
+            const { type: _type, ...data } = part;
+            return { type: "data-pause", id, data };
+        }
         case "data-subagent-activity": {
             const { type: _type, ...payload } = part;
             return { type: "data-subagent-activity", id, data: { ...payload, entries: part.entries.map(closedEntry) } };
@@ -297,6 +309,9 @@ export function conversationUIToChatMessages(messages) {
                     case "data-presentation":
                         parts.push({ type: "data-presentation", ...part.data });
                         break;
+                    case "data-analogy-report":
+                        parts.push({ type: "data-analogy-report", ...part.data });
+                        break;
                     case "data-plan":
                         parts.push({ type: "data-plan", ...part.data });
                         break;
@@ -324,6 +339,9 @@ export function conversationUIToChatMessages(messages) {
                     case "data-model-refusal":
                         parts.push({ type: "data-model-refusal", ...part.data });
                         break;
+                    case "data-pause":
+                        parts.push({ type: "data-pause", ...part.data });
+                        break;
                     case "data-subagent-activity":
                         parts.push({ type: "data-subagent-activity", ...part.data });
                         break;

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion of a bioinformatics analysis platform. You\nhelp researchers understand their data, run analyses, interpret results, and\ndevelop testable hypotheses.\n\nYour tool results stay in this conversation across turns. Reuse what you\nalready read or searched, and look again only for something new, for example\na run that completed since.\n\n## Data and Files\n\nYou can read the files of this analysis. `inspect_data_profile` is the record\nof what the dataset is. `workspace_search` finds files by their description,\nand `read_file` gives the values.\n\nWhen the user names data that is not yet an input of this analysis, add it with\nthe input tool if you hold one; its call asks the user. Without one, say that\nthe data must be added as an input. Never tell the user to copy files into a\nfolder to make them visible.\n\n## Analysis Runs\n\nA run starts a sandbox with a specialist agent, and it takes minutes to hours.\nStart one only for computation on the data that needs that environment:\nstatistics, models, R or Python packages, reference data, a table over 16 MiB.\nA lookup, a file read or write, a summary of results that you can read, and\nlight work on a table (a filter, a join, a count, a small test, a reshape, a\nderived file or chart) are not runs. Do them yourself, with `run_script` for\nthe tables.\n\n- **One sandbox computation that the user explicitly asks for** \u2192\n  `execute_analysis` in ad hoc mode, with the request in their words. The\n  request is the consent: do not plan it and do not ask again. Keep one request\n  in one call.\n- **Work of several dependent steps** \u2192 `generate_plan`. It shows the plan\n  card. Explain the plan, and ask for approval. On approval, call\n  `execute_analysis` in plan mode. A thread record that says that the person\n  approved a plan means that its run started already.\n- **A computation that only you suggest** \u2192 ask first.\n\nRuns are asynchronous. Read their results on a later turn with `inspect_run`.\n\n## Interpreting Results\n\nA completed run has one summary for each step. When the run had summaries and\nno blocker, it also has a run synthesis: conclusions, key findings, themes,\nlimitations, and references. `inspect_run` gives the `synthesisStatus` and\nthe `synthesisPath`. Start from the synthesis, and read a step summary for the\nevidence behind a finding. Without a synthesis, integrate the step summaries\nyourself. Group findings by biological theme, and keep well-supported findings\napart from speculation.\n\nFor a translational finding, give the landscape of existing drugs for a target,\nkeep predictive and prognostic biomarkers apart, name the validation that is\nmissing, and rest no claim on one source.\n\n## Literature and Biology\n\nA question about biology or the literature gets a lookup, not an answer from\nmemory. The lookups are cheap API calls in `run_script`: put independent\nlookups in one script, and print only what you need. When a source has nothing,\nsay so and continue with the others.\n\n## Hypotheses\n\nA hypothesis is grounded in data that you read, falsifiable, and specific: the\ngenes, pathways, comparisons, and expected effects. Make sure that the data can\ntest it, rank the candidates by impact, testability, novelty, and evidence, and\ndrop what cannot be tested. Analogies from `generate_analogy_report` are\ncandidate seeds; ground each one in the data before you use it. When the user\nasks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and\ngive the full updated list. To test a hypothesis, plan an analysis for it.\n\nThe analogy report renders as a card. Name the analogies that matter by their\n`analogyTitle`, say why they matter for this data, and end with one question\nabout which one to pursue. Keep analogies out of `generate_plan`,\n`execute_analysis`, and each other workflow input: the planner and the\nsandbox agents do not know analogy reports.\n\n## Reports\n\nWhen the user asks for a report, call `start_report_session` with no\nconfirmation, unless the scope is truly ambiguous: several analyses to choose\nfrom, or an audience that matters and is not known. Then tell the user that the\nreport takes shape in that chat. Do not compose the report here. A request to\nput content into a file, such as a markdown summary or a PDF, is a file that you\nwrite: `write_file` for text, and `export_pdf` in a script for a PDF. The user\nmay not know that report sessions exist: offer one when a structured, cited\nreport would serve them, for example after a run completes.\n\n## Ground Rules\n\n- Cite a value only from a synthesis, a step summary, or a file that you or a\n  script read. A `workspace_search` hit gives a description, not the values.\n  If you cannot find the data behind a claim, say so.\n- A constraint in the working memory binds the rest of the analysis. If a plan\n  or a choice would break one, raise the conflict with the user. Never just\n  proceed.\n- Data profiling runs each time the inputs change, thus a plan needs no step\n  that explores the data structure.\n- Before you call a package or a reference dataset unavailable, find out\n  whether a tool that you hold can provide it.\n- When a tool fails, say so briefly, name a cause that the user can act on, and\n  offer a retry or an alternative. Keep the internal details out.\n- When results conflict, give both sides.\n- Give a hypothesis with its ID, claim, rationale, test design, expected\n  outcomes, and priority.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion of a bioinformatics analysis platform. You\nhelp researchers understand their data, run analyses, interpret results, and\ndevelop testable hypotheses.\n\nYour tool results stay in this conversation across turns. Reuse what you\nalready read or searched, and look again only for something new, for example\na run that completed since.\n\n## Data and Files\n\nYou can read the files of this analysis. `inspect_data_profile` is the record\nof what the dataset is. `workspace_search` finds files by their description,\nand `read_file` gives the values.\n\nWhen the user names data that is not yet an input of this analysis, add it with\nthe input tool if you hold one; its call asks the user. Without one, say that\nthe data must be added as an input. Never tell the user to copy files into a\nfolder to make them visible.\n\n## Analysis Runs\n\nA run starts a sandbox with a specialist agent, and it takes minutes to hours.\nStart one only for computation on the data that needs that environment:\nstatistics, models, R or Python packages, reference data, a table over 16 MiB.\nA lookup, a file read or write, a summary of results that you can read, and\nlight work on a table (a filter, a join, a count, a small test, a reshape, a\nderived file or chart) are not runs. Do them yourself, with `run_script` for\nthe tables.\n\n- **One sandbox computation that the user explicitly asks for** \u2192\n  `execute_analysis` in ad hoc mode, with the request in their words. The\n  request is the consent: do not plan it and do not ask again. Keep one request\n  in one call.\n- **Work of several dependent steps** \u2192 `generate_plan`. It shows the plan\n  card. Explain the plan, and ask for approval. On approval, call\n  `execute_analysis` in plan mode. A thread record that says that the person\n  approved a plan means that its run started already.\n- **A computation that only you suggest** \u2192 ask first.\n\nRuns are asynchronous. Read their results on a later turn with `inspect_run`.\n\n## Interpreting Results\n\nA completed run has one summary for each step. When the run had summaries and\nno blocker, it also has a run synthesis: conclusions, key findings, themes,\nlimitations, and references. `inspect_run` gives the `synthesisStatus` and\nthe `synthesisPath`. Start from the synthesis, and read a step summary for the\nevidence behind a finding. Without a synthesis, integrate the step summaries\nyourself. Group findings by biological theme, and keep well-supported findings\napart from speculation.\n\nFor a translational finding, give the landscape of existing drugs for a target,\nkeep predictive and prognostic biomarkers apart, name the validation that is\nmissing, and rest no claim on one source.\n\n## Literature and Biology\n\nA question about biology or the literature gets a lookup, not an answer from\nmemory. The lookups are cheap API calls in `run_script`: put independent\nlookups in one script, and print only what you need. When a source has nothing,\nsay so and continue with the others.\n\n## Hypotheses\n\nA hypothesis is grounded in data that you read, falsifiable, and specific: the\ngenes, pathways, comparisons, and expected effects. Make sure that the data can\ntest it, rank the candidates by impact, testability, novelty, and evidence, and\ndrop what cannot be tested. Analogies from `generate_analogy_report` are\ncandidate seeds; ground each one in the data before you use it. When the user\nasks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and\ngive the full updated list. To test a hypothesis, plan an analysis for it.\n\nThe analogy block shows the full report to the user, thus do not copy the\nreport into your reply. Name the analogies that matter by their\n`analogyTitle`, say why they matter for this data, and end with one question\nabout which one to pursue. For an `extraction-failed` envelope, give\nthe message of the error and ask the user to narrow the problem. Keep\nanalogies out of `generate_plan`, `execute_analysis`, and each other workflow\ninput: the planner and the sandbox agents do not know analogy reports.\n\n## Reports\n\nWhen the user asks for a report, call `start_report_session` with no\nconfirmation, unless the scope is truly ambiguous: several analyses to choose\nfrom, or an audience that matters and is not known. Then tell the user that the\nreport takes shape in that chat. Do not compose the report here. A request to\nput content into a file, such as a markdown summary or a PDF, is a file that you\nwrite: `write_file` for text, and `export_pdf` in a script for a PDF. The user\nmay not know that report sessions exist: offer one when a structured, cited\nreport would serve them, for example after a run completes.\n\n## Ground Rules\n\n- Cite a value only from a synthesis, a step summary, or a file that you or a\n  script read. A `workspace_search` hit gives a description, not the values.\n  If you cannot find the data behind a claim, say so.\n- A constraint in the working memory binds the rest of the analysis. If a plan\n  or a choice would break one, raise the conflict with the user. Never just\n  proceed.\n- Data profiling runs each time the inputs change, thus a plan needs no step\n  that explores the data structure.\n- Before you call a package or a reference dataset unavailable, find out\n  whether a tool that you hold can provide it.\n- When a tool fails, say so briefly, name a cause that the user can act on, and\n  offer a retry or an alternative. Keep the internal details out.\n- When results conflict, give both sides.\n- Give a hypothesis with its ID, claim, rationale, test design, expected\n  outcomes, and priority.\n";

package/dist/prompts/conversation.js

@@ -72,11 +72,13 @@ candidate seeds; ground each one in the data before you use it. When the user
 asks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and
 give the full updated list. To test a hypothesis, plan an analysis for it.
 
-The analogy report renders as a card. Name the analogies that matter by their
+The analogy block shows the full report to the user, thus do not copy the
+report into your reply. Name the analogies that matter by their
 \`analogyTitle\`, say why they matter for this data, and end with one question
-about which one to pursue. Keep analogies out of \`generate_plan\`,
-\`execute_analysis\`, and each other workflow input: the planner and the
-sandbox agents do not know analogy reports.
+about which one to pursue. For an \`extraction-failed\` envelope, give
+the message of the error and ask the user to narrow the problem. Keep
+analogies out of \`generate_plan\`, \`execute_analysis\`, and each other workflow
+input: the planner and the sandbox agents do not know analogy reports.
 
 ## Reports
 

package/dist/prompts/sandbox/mdv-preparation-agent.d.ts

@@ -0,0 +1 @@
+export declare const mdvPreparationAgentPrompt = "# MDV Preparation Agent\n\nYou prepare biological datasets as assets for MDV (Multi-Dimensional Viewer). You take\nscRNA-seq, snRNA-seq, scATAC-seq, multiome, spatial transcriptomics (CosMx, Xenium, Visium,\nMERFISH) and spatial proteomics (CODEX, IMC, MIBI) data, in raw or processed form. You deliver an\nMDV-ready AnnData that MDV's upload converts into readable tables, the context tables, and a\nREADME, so that a person who did not make them can use them in MDV.\n\n## Skills\n\nYour skills: `mdv-preparation`, `single-cell`, `spatial-omics`, `chromatin-regulation`,\n`shared/omics-general`.\n\nRead `mdv-preparation` first. Its workflow is the order of your work, and its references\nhold the code to copy: the asset helpers and the validator. Use the modality packs for QC,\nnormalisation, embedding, and clustering when the input is raw.\n\n## Workflow (Summary)\n\n1. **Inventory** \u2014 identify the modality, the platform, the input form (raw instrument output,\n   count matrix, processed AnnData, MuData, SpatialData), and the size. Estimate the memory\n   before you load a large matrix.\n2. **Build** \u2014 one analysis-ready AnnData: counts in, QC, log-normalised sparse X, UMAP,\n   clusters, and readable labels with their evidence.\n3. **Curate** \u2014 keep the columns a person needs, label each with words and units (the label is\n   the column name in MDV), keep grouping columns at 256 categories or fewer.\n4. **Write** \u2014 the asset, the context tables, and the README with a column glossary, the\n   processing record, and the first charts to make.\n5. **Validate** \u2014 run the validator of the pack. Zero errors before delivery.\n\n## Domain Standards\n\n- The deliverable is an asset, not an MDV project. You do not need mdvtools.\n- Spatial data: slide coordinates in micrometres as two columns, y flipped upwards. For raw CosMx\n  runs, measure the FOV orientation before you trust the layout.\n- Inferred labels are putative: say so in the column label and keep the evidence.\n- Fix every seed. The same input gives the same asset.\n\n## Figures\n\nThe asset is the deliverable. Write one preview PNG only if the step needs a figure for the\nreport: the tissue or the UMAP coloured by cell type.\n\n## Domain Anti-Patterns\n\n- Raw snake_case keys or bare cluster ids as the labels people see.\n- Dense or scaled matrices, extra layers, or PCA columns in the asset.\n- Grouping columns above 256 categories.\n- Skipping the validator because the file \"loads\".\n\n## Required Output Files\n\n- The asset `output/*.mdv.h5ad`, its context tables `output/*.tsv`, and `output/README.md`.\n- The validator report `output/*.mdv.validation.json`, with zero errors.\n- The analysis AnnData `output/*.h5ad` with standard keys and raw counts.\n";

package/dist/prompts/sandbox/mdv-preparation-agent.js

@@ -0,0 +1,56 @@
+export const mdvPreparationAgentPrompt = `# MDV Preparation Agent
+
+You prepare biological datasets as assets for MDV (Multi-Dimensional Viewer). You take
+scRNA-seq, snRNA-seq, scATAC-seq, multiome, spatial transcriptomics (CosMx, Xenium, Visium,
+MERFISH) and spatial proteomics (CODEX, IMC, MIBI) data, in raw or processed form. You deliver an
+MDV-ready AnnData that MDV's upload converts into readable tables, the context tables, and a
+README, so that a person who did not make them can use them in MDV.
+
+## Skills
+
+Your skills: \`mdv-preparation\`, \`single-cell\`, \`spatial-omics\`, \`chromatin-regulation\`,
+\`shared/omics-general\`.
+
+Read \`mdv-preparation\` first. Its workflow is the order of your work, and its references
+hold the code to copy: the asset helpers and the validator. Use the modality packs for QC,
+normalisation, embedding, and clustering when the input is raw.
+
+## Workflow (Summary)
+
+1. **Inventory** — identify the modality, the platform, the input form (raw instrument output,
+   count matrix, processed AnnData, MuData, SpatialData), and the size. Estimate the memory
+   before you load a large matrix.
+2. **Build** — one analysis-ready AnnData: counts in, QC, log-normalised sparse X, UMAP,
+   clusters, and readable labels with their evidence.
+3. **Curate** — keep the columns a person needs, label each with words and units (the label is
+   the column name in MDV), keep grouping columns at 256 categories or fewer.
+4. **Write** — the asset, the context tables, and the README with a column glossary, the
+   processing record, and the first charts to make.
+5. **Validate** — run the validator of the pack. Zero errors before delivery.
+
+## Domain Standards
+
+- The deliverable is an asset, not an MDV project. You do not need mdvtools.
+- Spatial data: slide coordinates in micrometres as two columns, y flipped upwards. For raw CosMx
+  runs, measure the FOV orientation before you trust the layout.
+- Inferred labels are putative: say so in the column label and keep the evidence.
+- Fix every seed. The same input gives the same asset.
+
+## Figures
+
+The asset is the deliverable. Write one preview PNG only if the step needs a figure for the
+report: the tissue or the UMAP coloured by cell type.
+
+## Domain Anti-Patterns
+
+- Raw snake_case keys or bare cluster ids as the labels people see.
+- Dense or scaled matrices, extra layers, or PCA columns in the asset.
+- Grouping columns above 256 categories.
+- Skipping the validator because the file "loads".
+
+## Required Output Files
+
+- The asset \`output/*.mdv.h5ad\`, its context tables \`output/*.tsv\`, and \`output/README.md\`.
+- The validator report \`output/*.mdv.validation.json\`, with zero errors.
+- The analysis AnnData \`output/*.h5ad\` with standard keys and raw counts.
+`;

package/dist/report-model/fixture-resolver.js

@@ -4,17 +4,9 @@
  * assertion rules without a host.
  */
 import { err, ok } from "neverthrow";
-import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
-import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, snapshotRows, } from "./reference-resolver.js";
-/** Build an `Err` that carries the unresolved reference. The `detail` key is present only when there is a detail to carry. */
-function fail(reference, reason, detail) {
-    const failure = detail !== undefined ? { reference, reason, detail } : { reference, reason };
-    return err(failure);
-}
-/** A short account of a derivation input, for a detail that names which input broke the arithmetic. */
-function describeReference(reference) {
-    return `artifact value at ${reference.path} column ${reference.locator.column}`;
-}
+import { checkValueAssertion } from "./assert-rules.js";
+import { fail, readArtifactTable, resolveCitation, resolveDerivation, selectRow } from "./reference-read.js";
+import { fileTypeHoldsNoCell, snapshotEntry, snapshotRows } from "./reference-resolver.js";
 function resolveArtifactValue(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -35,53 +27,22 @@ function resolveArtifactValue(reference, snapshot) {
     if (readRows.isErr()) {
         return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
     }
-    const rows = readRows.value;
     const locator = reference.locator;
-    let selectedRow;
-    if (locator.row !== undefined) {
-        const row = rows[locator.row];
-        if (row === undefined) {
-            return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
-        }
-        selectedRow = row;
-    }
-    else if (locator.rowFilter !== undefined) {
-        const filter = locator.rowFilter;
-        const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
-        const match = matches[0];
-        if (match === undefined) {
-            return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
-        }
-        if (matches.length > 1) {
-            return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
-        }
-        selectedRow = match;
-    }
-    else {
-        // The locator schema forbids a locator with neither selector. The resolver cannot depend on a
-        // prior parse, thus it treats a row that no selector addresses as out of range.
-        return fail(reference, "locator-out-of-range", "the locator selects no row");
+    const selection = selectRow(readRows.value, locator);
+    if (selection.isErr()) {
+        return fail(reference, selection.error.reason, selection.error.detail);
     }
     // A real table holds an empty cell, and the snapshot parser gives it back as an absent
     // key: `snapshotRows` drops a cell that parsed as `null` or `undefined`, so an absent key
     // is the only absence. It is not a value that a scalar reference can bind. An empty
     // string is a value, thus it stays valid.
-    const cell = selectedRow[locator.column];
+    const cell = selection.value[locator.column];
     if (cell === undefined) {
         return fail(reference, "locator-out-of-range", `column ${locator.column} holds no value in the selected row`);
     }
     const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, cell);
     return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: cell });
 }
-/**
- * Put one own data property on a projected row.
- *
- * A plain assignment at the key `__proto__` reaches the prototype setter, thus the projection loses a
- * column that the row holds. The definition makes an own data property for each key.
- */
-function defineOwn(target, key, value) {
-    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
-}
 function resolveArtifactTable(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -94,46 +55,11 @@ function resolveArtifactTable(reference, snapshot) {
     if (fileTypeHoldsNoCell(tableFileType)) {
         return fail(reference, "unreadable-artifact", `the ${String(tableFileType)} at ${reference.path} holds no cell to read`);
     }
-    // The bound ranks the rows as the artifact holds them, thus a bound over a column that the subset
-    // below leaves out still ranks them. An unknown bound column addresses nothing, exactly as an unknown
-    // subset column does.
-    const bound = reference.rowBound;
     const readRows = snapshotRows(artifact);
     if (readRows.isErr()) {
         return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
     }
-    const allRows = readRows.value;
-    if (bound !== undefined && columnsHeldByNoRow(allRows, [bound.column]).length > 0) {
-        return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the table at ${reference.path} does not hold`);
-    }
-    const rows = bound === undefined ? allRows : applyRowBound(allRows, bound);
-    // The page states the shown count against the count of the artifact. This read is the one place that
-    // holds both, thus a bounded table carries the pre-bound total out with its rows.
-    const total = bound === undefined ? {} : { total: allRows.length };
-    const columns = reference.columns;
-    if (columns === undefined) {
-        return ok({ type: "table", rows, ...total });
-    }
-    // A name that no row holds addresses nothing. Without this check a projection onto an invented column
-    // gives an empty cell for each row and still resolves, which is the fabrication that grounding exists
-    // to reject.
-    const absent = columnsHeldByNoRow(rows, columns);
-    if (absent.length > 0) {
-        return fail(reference, "locator-out-of-range", `the table at ${reference.path} holds no column ${absent.join(", ")}`);
-    }
-    // Project each row onto the requested columns. A table tolerates a ragged row, thus a column that a
-    // given row lacks is left out of that row and is not a failure.
-    const projectedRows = rows.map((row) => {
-        const projected = {};
-        for (const column of columns) {
-            const cell = row[column];
-            if (cell !== undefined) {
-                defineOwn(projected, column, cell);
-            }
-        }
-        return projected;
-    });
-    return ok({ type: "table", rows: projectedRows, columns, ...total });
+    return readArtifactTable(reference, readRows.value);
 }
 function resolveArtifactFile(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
@@ -145,58 +71,6 @@ function resolveArtifactFile(reference, snapshot) {
     }
     return ok({ type: "file", path: reference.path, hash: artifact.hash });
 }
-async function resolveDerivation(reference, snapshot) {
-    const numbers = [];
-    for (const input of reference.inputs) {
-        const inputResult = await resolve(input, snapshot);
-        if (inputResult.isErr()) {
-            // Keep the inner reason so a reviewer sees the real cause, for example a missing artifact under
-            // the derivation. The derivation itself did not fail on its own terms.
-            return fail(reference, inputResult.error.reason, inputResult.error.detail);
-        }
-        const resolved = inputResult.value;
-        const numeric = resolved.type === "scalar" ? asFiniteNumber(resolved.value) : undefined;
-        if (numeric === undefined) {
-            // The arithmetic needs a finite number. A cell that holds text does not address a usable
-            // scalar, thus the closest reason is that the coordinate is out of range.
-            return fail(reference, "locator-out-of-range", `input ${describeReference(input)} did not resolve to a finite number`);
-        }
-        numbers.push(numeric);
-    }
-    const a = numbers[0];
-    const b = numbers[1];
-    if (a === undefined || b === undefined) {
-        return fail(reference, "locator-out-of-range", `operation ${reference.op} needs two inputs, and the derivation holds ${numbers.length}`);
-    }
-    let result;
-    switch (reference.op) {
-        case "ratio":
-            result = a / b;
-            break;
-        case "delta":
-            result = a - b;
-            break;
-        case "pctChange":
-            // A fraction, not a percent. A change of one half gives 0.5, thus an author asserts 0.5 and a
-            // `unit` of `%` only tells a renderer how to show it.
-            result = (a - b) / b;
-            break;
-    }
-    if (!Number.isFinite(result)) {
-        return fail(reference, "locator-out-of-range", `operation ${reference.op} does not yield a finite value, because the divisor is zero`);
-    }
-    const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, result);
-    return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: result });
-}
-function resolveCitation(reference, snapshot) {
-    const key = `${reference.idKind}:${reference.id}`;
-    if (snapshot.citations === undefined || !snapshot.citations.includes(key)) {
-        return fail(reference, "artifact-missing", `the citation ${key} is not in the pinned evidence`);
-    }
-    const value = { type: "citation", id: key };
-    const citationFailure = checkCitationAssertion(reference, reference.assert?.value, key);
-    return citationFailure !== undefined ? err(citationFailure) : ok(value);
-}
 async function resolve(reference, snapshot) {
     switch (reference.kind) {
         case "artifact-value":
@@ -206,7 +80,7 @@ async function resolve(reference, snapshot) {
         case "artifact-file":
             return resolveArtifactFile(reference, snapshot);
         case "derivation":
-            return resolveDerivation(reference, snapshot);
+            return resolveDerivation(reference, snapshot, resolve);
         case "citation":
             return resolveCitation(reference, snapshot);
     }

package/dist/report-model/production-resolver.d.ts

@@ -13,9 +13,9 @@
  * holds the streamed hash and the parsed rows against a stat signature. Two tool calls of one analysis
  * share one cache.
  *
- * The realization calls the shared assert functions in `assert-rules.ts`, and it mirrors the locator walk
- * and the reason choices of `fixture-resolver.ts`. Thus one semantics exists, and the fixture stays the
- * executable specification of the value tier. The two realizations are substitutable behind the seam.
+ * The realization calls the shared assert functions in `assert-rules.ts` and the shared reference reads in
+ * `reference-read.ts`, as the fixture realization does. Thus one semantics exists, and the fixture stays
+ * the executable specification of the value tier. The two realizations are substitutable behind the seam.
  */
 import { type ReferenceResolver } from "./reference-resolver.js";
 /** One artifact row, as plain cells. A text-backed format holds a numeric column as a string. */

package/dist/report-model/production-resolver.js

@@ -13,9 +13,9 @@
  * holds the streamed hash and the parsed rows against a stat signature. Two tool calls of one analysis
  * share one cache.
  *
- * The realization calls the shared assert functions in `assert-rules.ts`, and it mirrors the locator walk
- * and the reason choices of `fixture-resolver.ts`. Thus one semantics exists, and the fixture stays the
- * executable specification of the value tier. The two realizations are substitutable behind the seam.
+ * The realization calls the shared assert functions in `assert-rules.ts` and the shared reference reads in
+ * `reference-read.ts`, as the fixture realization does. Thus one semantics exists, and the fixture stays
+ * the executable specification of the value tier. The two realizations are substitutable behind the seam.
  */
 import { err, ok } from "neverthrow";
 import { readFile, stat } from "node:fs/promises";
@@ -26,8 +26,9 @@ import { allWithConcurrency } from "../lib/async-utils.js";
 import { computeSha256File } from "../lib/fs-helpers.js";
 import { parseJsonAs } from "../lib/parse-json.js";
 import { resolveWorkspacePath } from "../workspace/paths.js";
-import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
-import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
+import { checkValueAssertion } from "./assert-rules.js";
+import { fail, readArtifactTable, resolveCitation, resolveDerivation, selectRow } from "./reference-read.js";
+import { fileTypeHoldsNoCell, snapshotEntry } from "./reference-resolver.js";
 /**
  * The default cap on the file size that the host fast path reads. A larger file takes the fall-through.
  * The cap gates the cell extraction only. The identity compare streams the hash at every size.
@@ -95,15 +96,6 @@ export function createArtifactReadStore() {
 function fallThroughCells(path, hostDetail) {
     return { kind: "unavailable", detail: `the host read of the file at ${path} stopped because ${hostDetail}, and no other reader exists` };
 }
-/** Build an `Err` that carries the unresolved reference. The `detail` key is present only when there is a detail to carry. */
-function fail(reference, reason, detail) {
-    const failure = detail !== undefined ? { reference, reason, detail } : { reference, reason };
-    return err(failure);
-}
-/** A short account of a derivation input, for a detail that names which input broke the arithmetic. */
-function describeReference(reference) {
-    return `artifact value at ${reference.path} column ${reference.locator.column}`;
-}
 /**
  * Map a file extension to the format that the host arm reads. An unknown extension gives back `undefined`.
  *
@@ -538,36 +530,15 @@ export function createProductionResolver(deps) {
     /** Walk the locator over the rows, and match the resolved cell against the authored belief. */
     function selectCell(reference, rows) {
         const locator = reference.locator;
-        let selectedRow;
-        if (locator.row !== undefined) {
-            const row = rows[locator.row];
-            if (row === undefined) {
-                return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
-            }
-            selectedRow = row;
-        }
-        else if (locator.rowFilter !== undefined) {
-            const filter = locator.rowFilter;
-            const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
-            const match = matches[0];
-            if (match === undefined) {
-                return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
-            }
-            if (matches.length > 1) {
-                return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
-            }
-            selectedRow = match;
-        }
-        else {
-            // The locator schema forbids a locator with neither selector. The resolver cannot depend on a
-            // prior parse, thus it treats a row that no selector addresses as out of range.
-            return fail(reference, "locator-out-of-range", "the locator selects no row");
+        const selection = selectRow(rows, locator);
+        if (selection.isErr()) {
+            return fail(reference, selection.error.reason, selection.error.detail);
         }
         // A real table holds an empty cell, and a parse gives it back as an absent key. An absent key is
         // not a value that a scalar reference can bind. An empty string is a value, thus it stays valid.
         // A cell that parsed as `null` never lands in a row: `coerceCell` drops it, so `null` is not
         // an absence the resolver can meet here.
-        const cell = selectedRow[locator.column];
+        const cell = selection.value[locator.column];
         if (cell === undefined) {
             return fail(reference, "locator-out-of-range", `column ${locator.column} holds no value in the selected row`);
         }
@@ -583,41 +554,7 @@ export function createProductionResolver(deps) {
         if (gated.isErr()) {
             return err(gated.error);
         }
-        // The bound ranks the rows as the artifact holds them, thus a bound over a column that the subset
-        // below leaves out still ranks them. An unknown bound column addresses nothing, exactly as an
-        // unknown subset column does.
-        const bound = reference.rowBound;
-        const allRows = gated.value;
-        if (bound !== undefined && columnsHeldByNoRow(allRows, [bound.column]).length > 0) {
-            return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the table at ${reference.path} does not hold`);
-        }
-        const rows = bound === undefined ? allRows : applyRowBound(allRows, bound);
-        // The page states the shown count against the count of the artifact. This read is the one place that
-        // holds both, thus a bounded table carries the pre-bound total out with its rows.
-        const total = bound === undefined ? {} : { total: allRows.length };
-        const columns = reference.columns;
-        if (columns === undefined) {
-            return ok({ type: "table", rows, ...total });
-        }
-        // A name that no row holds addresses nothing. Without this check a projection onto an invented
-        // column gives an empty cell for each row and still resolves, which grounding exists to reject.
-        const absent = columnsHeldByNoRow(rows, columns);
-        if (absent.length > 0) {
-            return fail(reference, "locator-out-of-range", `the table at ${reference.path} holds no column ${absent.join(", ")}`);
-        }
-        // Project each row onto the requested columns. A table tolerates a ragged row, thus a column that
-        // a given row lacks is left out of that row and is not a failure.
-        const projectedRows = rows.map((row) => {
-            const projected = {};
-            for (const column of columns) {
-                const cell = row[column];
-                if (cell !== undefined) {
-                    projected[column] = cell;
-                }
-            }
-            return projected;
-        });
-        return ok({ type: "table", rows: projectedRows, columns, ...total });
+        return readArtifactTable(reference, gated.value);
     }
     async function resolveArtifactFile(reference, snapshot) {
         const identity = await getIdentity(reference.path, snapshot);
@@ -632,58 +569,6 @@ export function createProductionResolver(deps) {
         }
         return ok({ type: "file", path: reference.path, hash: identity.onDiskHash });
     }
-    async function resolveDerivation(reference, snapshot) {
-        const numbers = [];
-        for (const input of reference.inputs) {
-            const inputResult = await resolveArtifactValue(input, snapshot);
-            if (inputResult.isErr()) {
-                // Keep the inner reason so a reviewer sees the real cause, for example a missing artifact
-                // under the derivation. The derivation itself did not fail on its own terms.
-                return fail(reference, inputResult.error.reason, inputResult.error.detail);
-            }
-            const resolved = inputResult.value;
-            const numeric = resolved.type === "scalar" ? asFiniteNumber(resolved.value) : undefined;
-            if (numeric === undefined) {
-                // The arithmetic needs a finite number. A cell that holds text does not address a usable
-                // scalar, thus the closest reason is that the coordinate is out of range.
-                return fail(reference, "locator-out-of-range", `input ${describeReference(input)} did not resolve to a finite number`);
-            }
-            numbers.push(numeric);
-        }
-        const a = numbers[0];
-        const b = numbers[1];
-        if (a === undefined || b === undefined) {
-            return fail(reference, "locator-out-of-range", `operation ${reference.op} needs two inputs, and the derivation holds ${numbers.length}`);
-        }
-        let result;
-        switch (reference.op) {
-            case "ratio":
-                result = a / b;
-                break;
-            case "delta":
-                result = a - b;
-                break;
-            case "pctChange":
-                // A fraction, not a percent. A change of one half gives 0.5, thus an author asserts 0.5 and
-                // a `unit` of `%` only tells a renderer how to show it.
-                result = (a - b) / b;
-                break;
-        }
-        if (!Number.isFinite(result)) {
-            return fail(reference, "locator-out-of-range", `operation ${reference.op} does not yield a finite value, because the divisor is zero`);
-        }
-        const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, result);
-        return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: result });
-    }
-    function resolveCitation(reference, snapshot) {
-        const key = `${reference.idKind}:${reference.id}`;
-        if (snapshot.citations === undefined || !snapshot.citations.includes(key)) {
-            return fail(reference, "artifact-missing", `the citation ${key} is not in the pinned evidence`);
-        }
-        const value = { type: "citation", id: key };
-        const citationFailure = checkCitationAssertion(reference, reference.assert?.value, key);
-        return citationFailure !== undefined ? err(citationFailure) : ok(value);
-    }
     async function resolve(reference, snapshot) {
         switch (reference.kind) {
             case "artifact-value":
@@ -693,7 +578,7 @@ export function createProductionResolver(deps) {
             case "artifact-file":
                 return resolveArtifactFile(reference, snapshot);
             case "derivation":
-                return resolveDerivation(reference, snapshot);
+                return resolveDerivation(reference, snapshot, resolveArtifactValue);
             case "citation":
                 return resolveCitation(reference, snapshot);
         }

package/dist/report-model/reference-read.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The reads of a report reference that the two resolver realizations share.
+ *
+ * The fixture resolver reads the rows of a snapshot, and the production resolver reads the rows of the
+ * pinned artifact on disk. What both do with those rows — the locator walk, the table read, and the
+ * derivation arithmetic — lives here, so one semantics exists for both realizations.
+ */
+import { type Result } from "neverthrow";
+import type { ArtifactTableReference, ArtifactValueReference, CitationReference, DerivationInputReference, DerivationReference, Reference, UnresolvedReason, UnresolvedReference } from "../contracts/report-reference.js";
+import { type ReportSnapshot, type ResolvedValue } from "./reference-resolver.js";
+/** Build an `Err` that carries the unresolved reference. The `detail` key is present only when there is a detail to carry. */
+export declare function fail(reference: Reference, reason: UnresolvedReason, detail?: string): Result<ResolvedValue, UnresolvedReference>;
+/** The failure of a row selection: the reason that an `UnresolvedReference` carries, and its detail. */
+export type RowSelectionFailure = {
+    reason: "locator-out-of-range" | "ambiguous-match";
+    detail: string;
+};
+/**
+ * Walk a locator over the rows, and give back the one row that it selects, or the failure.
+ *
+ * A row index selects the row at that position. A row filter selects the one row that matches; no match
+ * selects nothing, and two or more matches are ambiguous.
+ */
+export declare function selectRow(rows: Array<Record<string, string | number>>, locator: ArtifactValueReference["locator"]): Result<Record<string, string | number>, RowSelectionFailure>;
+/**
+ * Read the table that a table reference addresses out of rows that the caller read from the artifact:
+ * cut the rows on the row bound, refuse a column that no row holds, and project the requested columns.
+ */
+export declare function readArtifactTable(reference: ArtifactTableReference, allRows: Array<Record<string, string | number>>): Result<ResolvedValue, UnresolvedReference>;
+/**
+ * Resolve a derivation: read each input with `resolveInput`, then run the arithmetic of the operation.
+ *
+ * The read of an input stays with the realization: the fixture resolver reads its snapshot, and the
+ * production resolver reads the pinned artifact on disk.
+ */
+export declare function resolveDerivation(reference: DerivationReference, snapshot: ReportSnapshot, resolveInput: (input: DerivationInputReference, snapshot: ReportSnapshot) => Promise<Result<ResolvedValue, UnresolvedReference>>): Promise<Result<ResolvedValue, UnresolvedReference>>;
+/** Resolve a citation: confirm that the id is in the pinned evidence, and echo the key back. */
+export declare function resolveCitation(reference: CitationReference, snapshot: ReportSnapshot): Result<ResolvedValue, UnresolvedReference>;