@inflexa-ai/harness 0.20.0 → 0.21.0

package/dist/contracts/report-blocks.js

@@ -15,20 +15,154 @@
  */
 import { z } from "zod";
 import { ArtifactFileReferenceSchema, ArtifactTableReferenceSchema, CitationReferenceSchema, ReferenceSchema, ScalarReferenceSchema, } from "./report-reference.js";
-/** The chart vocabulary. Each value names one plot form. */
-const ChartTypeSchema = z.enum(["bar", "line", "scatter", "histogram", "box", "heatmap", "pie"]);
+/**
+ * The chart vocabulary. The first seven values name one plot form each. The last four are presets of a
+ * scientific plot, and the renderer expands a preset into a composition.
+ */
+const ChartTypeSchema = z.enum(["bar", "line", "scatter", "histogram", "box", "heatmap", "pie", "volcano", "manhattan", "ma", "km"]);
+/** The per-row transforms of a channel. Each derived value comes from one cell. */
+const ChartTransformSchema = z.enum(["log10", "neg_log10", "abs", "rank"]);
+/**
+ * The arrangement of a bar. The channels keep their data meaning under both values, thus one encoding
+ * serves both and the author flips this one field.
+ */
+const ChartOrientationSchema = z.enum(["vertical", "horizontal"]);
+/**
+ * The threshold pair of a preset that classifies its rows.
+ *
+ * One declaration moves the guide lines and the color split together. Thus the split always lands on the
+ * drawn lines, and no second declaration can disagree with the first one.
+ */
+const ChartThresholdsSchema = z.strictObject({
+    significance: z
+        .number()
+        .positive()
+        .describe("The significance cut of the p column, for example `0.05`. The guide line sits at the transformed value of it, and a point past the line reads as significant."),
+    effect: z
+        .number()
+        .positive()
+        .describe("The effect cut, for example `1`. One guide line sits at each side of zero, and a point past a line reads as a signal on that side."),
+});
+/** The teaching text of the orientation. The quick path and the bar series form both carry it. */
+const ORIENTATION_DESCRIPTION = "The arrangement of the bars. `vertical` is the default, and it draws the categories along the bottom. `horizontal` draws them up the left side, and it is the form to reach for when a category name is long, for example a gene-set name: a long name reads on the y axis, and it is unreadable slanted under a vertical bar. The channels do not move with the orientation. `x` names the category column and `y` names the value column in both.";
+/**
+ * One visual channel: a column name, or a column with a per-row transform.
+ *
+ * The object form carries a column and a transform, and it carries no value. Thus a channel can never
+ * bring a data literal into the chart option.
+ */
+export const ChartChannelSchema = z.union([
+    z.string().describe("The column that feeds the channel."),
+    z.strictObject({
+        column: z.string().describe("The column that feeds the channel."),
+        transform: ChartTransformSchema.describe("The per-row transform. `log10` and `neg_log10` drop a cell that is not positive. `rank` gives the place of the cell in the ascending order of the column, and a tie shares its place."),
+    }),
+]);
 /** The mapping from a data column to a visual channel. Each channel is optional. */
 const ChartEncodingSchema = z.strictObject({
-    x: z.string().optional().describe("The column on the x axis."),
-    y: z.string().optional().describe("The column on the y axis."),
-    group: z.string().optional().describe("The column that splits and colors the series."),
-    value: z.string().optional().describe("The value column for a pie or heatmap."),
+    x: ChartChannelSchema.optional().describe("The channel on the x axis."),
+    y: ChartChannelSchema.optional().describe("The channel on the y axis."),
+    group: ChartChannelSchema.optional().describe("The column that splits and colors the series."),
+    value: ChartChannelSchema.optional().describe("The value column for a pie or heatmap."),
+    label: z.string().optional().describe("The column that names each point. The name rides the tooltip of a bar, a line, and a scatter."),
+});
+/** The channels of one series. A series plots two channels, thus `x` and `y` are both present. */
+const ChartSeriesEncodingSchema = z.strictObject({
+    x: ChartChannelSchema.describe("The channel on the x axis."),
+    y: ChartChannelSchema.describe("The channel on the y axis."),
+    y0: ChartChannelSchema.optional().describe("The lower bound of a band. It is legal on an `area` series only."),
+    group: ChartChannelSchema.optional().describe("The column that splits the series, one series for each value."),
+    label: z.string().optional().describe("The column that names each point of the series."),
+});
+/**
+ * One series of a composition: a plot form, its own channels, and an optional legend name.
+ *
+ * A `step` series is a line with the step flag. An `area` series can name a `y0` lower bound, thus a band
+ * between two columns of one row is expressible. The refine holds `y0` to the one form that draws a band,
+ * and the second refine holds the orientation to the one form that carries an arrangement.
+ */
+export const ChartSeriesSchema = z
+    .strictObject({
+    form: z.enum(["line", "scatter", "bar", "area", "step"]).describe("The plot form of the series."),
+    encoding: ChartSeriesEncodingSchema.describe("The columns that feed the series."),
+    name: z.string().optional().describe("The legend name of the series."),
+    orientation: ChartOrientationSchema.optional().describe(ORIENTATION_DESCRIPTION),
+})
+    .refine((series) => series.form === "area" || series.encoding.y0 === undefined, {
+    message: "`y0` is legal on an `area` series only.",
+    path: ["encoding", "y0"],
+})
+    .refine((series) => series.form === "bar" || series.orientation === undefined, {
+    message: "`orientation` is legal on a `bar` series only.",
+    path: ["orientation"],
+});
+/** A guide line at one constant on one axis. */
+const ReferenceLineAnnotationSchema = z.strictObject({
+    kind: z.literal("reference-line"),
+    axis: z.enum(["x", "y"]).describe("The axis that the constant sits on."),
+    value: z.number().describe("The constant of the guide line."),
+    label: z.string().optional().describe("The text beside the line."),
+});
+/** A guide band between two constants on one axis. */
+const ReferenceBandAnnotationSchema = z.strictObject({
+    kind: z.literal("reference-band"),
+    axis: z.enum(["x", "y"]).describe("The axis that the two constants sit on."),
+    from: z.number().describe("The lower bound of the band."),
+    to: z.number().describe("The upper bound of the band."),
+    label: z.string().optional().describe("The text on the band."),
+});
+/** A name beside each point of a declared top-N subset. The subset comes from a rank over one column. */
+const PointLabelsAnnotationSchema = z.strictObject({
+    kind: z.literal("point-labels"),
+    column: z.string().describe("The column that ranks the rows."),
+    order: z.enum(["asc", "desc"]).describe("The direction of the rank."),
+    n: z.number().int().min(1).max(20).describe("How many points carry a name. The maximum is 20."),
+});
+/**
+ * One annotation of a composition.
+ *
+ * A reference line and a reference band both carry a declared constant. Such a constant is a guide, and it
+ * is never a plotted value.
+ */
+export const ChartAnnotationSchema = z.discriminatedUnion("kind", [ReferenceLineAnnotationSchema, ReferenceBandAnnotationSchema, PointLabelsAnnotationSchema]);
+/** The title and the scale of one axis. */
+const ChartAxisSchema = z.strictObject({
+    title: z.string().optional().describe("The axis title. It replaces the column name."),
+    scale: z.enum(["linear", "log"]).optional().describe("The axis scale."),
+});
+/** The two axes of a composition. */
+export const ChartAxesSchema = z.strictObject({
+    x: ChartAxisSchema.optional().describe("The x axis."),
+    y: ChartAxisSchema.optional().describe("The y axis."),
+});
+/** The full chart grammar: the series, the annotations, and the axes. Each series reads the one bound table. */
+export const ChartCompositionSchema = z.strictObject({
+    series: z.array(ChartSeriesSchema).min(1).describe("One series at least. Each one reads the bound table."),
+    annotations: z.array(ChartAnnotationSchema).optional().describe("The guide lines, the guide bands, and the point names."),
+    axes: ChartAxesSchema.optional().describe("The axis titles and the axis scales."),
+});
+/**
+ * One typed list of a text block: the flag that selects the form, and the items.
+ *
+ * An item is one inline line, and the renderer escapes it as it escapes a paragraph. No item carries
+ * markup, and no item carries a list of its own. A deeper structure composes as a section with blocks.
+ */
+export const TextListSchema = z.strictObject({
+    ordered: z.boolean().describe("True for a numbered list, for example a ranked set or a sequence of steps. False for a bulleted list of parallel points."),
+    items: z
+        .array(z.string().min(1).describe("One item as one inline line. It carries no markup and no list of its own."))
+        .min(1)
+        .describe("One item at least. Each item is one point."),
 });
 /** Prose with no binding. The absence of a binding field is the rule for this kind. */
 export const TextBlockSchema = z.strictObject({
     kind: z.literal("text"),
     id: z.string().min(1).describe("The stable identity of the block."),
-    content: z.strictObject({ prose: z.string() }),
+    content: z.strictObject({
+        prose: z.string(),
+        list: TextListSchema.optional().describe("The enumeration of the block, as a list. Three or more parallel points compose here, and never inline in the prose as " +
+            '"(1) ... (6)". The prose above the list carries the lead sentences that introduce it, and it can be empty.'),
+    }),
 });
 /** Prose with at least one reference that justifies it. */
 export const ClaimBlockSchema = z.strictObject({
@@ -52,15 +186,42 @@ export const TableBlockSchema = z.strictObject({
     binding: ArtifactTableReferenceSchema.describe("The whole-table artifact to render."),
     caption: z.string().optional(),
 });
-/** A whole-table artifact rendered as a chart, with the plot form and the channel mapping. */
-export const ChartBlockSchema = z.strictObject({
+/**
+ * A whole-table artifact rendered as a chart.
+ *
+ * The block carries the quick path or the composition, and never both. The quick path is one chart type
+ * with one encoding. The composition holds the series, the annotations, and the axes. The refine makes the
+ * exactly-one rule a parse failure.
+ *
+ * No member of either path carries a data literal, and no member carries script text. Thus every plotted
+ * value comes from the resolved rows of the bound table.
+ */
+export const ChartBlockSchema = z
+    .strictObject({
     kind: z.literal("chart"),
     id: z.string().min(1).describe("The stable identity of the block."),
     title: z.string().optional(),
     binding: ArtifactTableReferenceSchema.describe("The whole-table artifact to plot."),
-    chartType: ChartTypeSchema,
-    encoding: ChartEncodingSchema,
+    chartType: ChartTypeSchema.optional().describe("The quick path. Give `encoding` with it, and omit `composition`. A preset (`volcano`, `manhattan`, `ma`, `km`) reads the same channels, and it applies its own transform and its own guide lines."),
+    encoding: ChartEncodingSchema.optional().describe("The channels of the quick path."),
+    orientation: ChartOrientationSchema.optional().describe(`${ORIENTATION_DESCRIPTION} The field belongs to the \`bar\` chart type, and every other type refuses it.`),
+    thresholds: ChartThresholdsSchema.optional().describe("The threshold pair of a `volcano`. It replaces the preset defaults of `0.05` and `1`, and it moves the guide lines and the color split together. State it to draw the volcano of a corrected significance column. Every other chart type reads no threshold, thus every other type refuses the field."),
+    composition: ChartCompositionSchema.optional().describe("The full grammar. Omit `chartType` and `encoding` with it."),
     caption: z.string().optional(),
+})
+    .refine((block) => {
+    const quickPath = block.chartType !== undefined && block.encoding !== undefined;
+    // The orientation and the thresholds are quick-path fields. A composition states the arrangement
+    // on its own bar series, and it draws its own guide lines. Thus either field beside a composition
+    // names a rule that nothing reads.
+    const partialQuickPath = block.chartType !== undefined || block.encoding !== undefined || block.orientation !== undefined || block.thresholds !== undefined;
+    return block.composition !== undefined ? !partialQuickPath : quickPath;
+}, { message: "A chart carries either `chartType` with `encoding`, or `composition`. The `orientation` and the `thresholds` belong to the quick path." })
+    .refine((block) => block.thresholds === undefined || block.chartType === "volcano", {
+    // The member is a pair, and the volcano is the one type that reads both values. A silent ignore
+    // would teach the author a field that does nothing, thus the parse states the fault.
+    message: "`thresholds` is legal beside the `volcano` chart type alone. Every other type reads no threshold pair.",
+    path: ["thresholds"],
 });
 /** A static image artifact. An image has no per-cell address, thus it is pinned whole-file. */
 export const FigureBlockSchema = z.strictObject({
@@ -115,3 +276,17 @@ export const ReportDocumentSchema = z.strictObject({
     title: z.string().min(1),
     sections: z.array(SectionBlockSchema).min(1).describe("The top-level sections, each with at least one block."),
 });
+/**
+ * The column that one channel names.
+ *
+ * A transform rides beside the column and never in place of it, thus the two channel forms name their
+ * column the same way. The walk, the preset expansion, and the derivation all read the name through this
+ * one function.
+ */
+export function channelColumn(channel) {
+    return typeof channel === "string" ? channel : channel.column;
+}
+/** The transform of one channel, or `undefined` when the channel names a plain column. */
+export function channelTransform(channel) {
+    return typeof channel === "string" ? undefined : channel.transform;
+}

package/dist/contracts/report-reference.d.ts

@@ -36,16 +36,62 @@ export declare const ArtifactValueReferenceSchema: z.ZodObject<{
     snapshot: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"artifact-value">;
 }, z.core.$strict>;
+/**
+ * What one column of a table holds, as a closed set of five.
+ *
+ * A meaning states the content of the column. It is not a format: the design source keeps the one rule for
+ * how each meaning reads on the page, thus no block carries a format field.
+ */
+export declare const ColumnMeaningSchema: z.ZodEnum<{
+    count: "count";
+    identifier: "identifier";
+    category: "category";
+    "p-value": "p-value";
+    effect: "effect";
+}>;
+/**
+ * The row bound of a whole-table binding: the top rows by one column.
+ *
+ * The bound is content and not presentation. The resolution applies it, thus the resolved table, the
+ * rendered card, the staged data, and the gate all read one bounded set.
+ */
+export declare const RowBoundSchema: z.ZodObject<{
+    column: z.ZodString;
+    count: z.ZodNumber;
+    order: z.ZodOptional<z.ZodEnum<{
+        desc: "desc";
+        asc: "asc";
+    }>>;
+}, z.core.$strict>;
 /**
  * A reference to a whole table artifact. It carries no locator, because it binds every row.
  *
  * It carries no assert. A table is not one value, thus the only belief that an author can hold about it
  * is its bytes, and the pinned `hash` already carries that belief.
+ *
+ * The two declaration maps state what the columns are and what to call them. They ride the whole-table
+ * binding, thus one declaration serves the table block and the chart block alike.
  */
 export declare const ArtifactTableReferenceSchema: z.ZodObject<{
     unit: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodString>;
+    rowBound: z.ZodOptional<z.ZodObject<{
+        column: z.ZodString;
+        count: z.ZodNumber;
+        order: z.ZodOptional<z.ZodEnum<{
+            desc: "desc";
+            asc: "asc";
+        }>>;
+    }, z.core.$strict>>;
     columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        count: "count";
+        identifier: "identifier";
+        category: "category";
+        "p-value": "p-value";
+        effect: "effect";
+    }>>>;
+    columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     run: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
     hash: z.ZodString;
@@ -181,7 +227,23 @@ export declare const ReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>, z.ZodObject<{
     unit: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodString>;
+    rowBound: z.ZodOptional<z.ZodObject<{
+        column: z.ZodString;
+        count: z.ZodNumber;
+        order: z.ZodOptional<z.ZodEnum<{
+            desc: "desc";
+            asc: "asc";
+        }>>;
+    }, z.core.$strict>>;
     columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        count: "count";
+        identifier: "identifier";
+        category: "category";
+        "p-value": "p-value";
+        effect: "effect";
+    }>>>;
+    columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     run: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
     hash: z.ZodString;
@@ -351,7 +413,23 @@ export declare const UnresolvedReferenceSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         unit: z.ZodOptional<z.ZodString>;
         format: z.ZodOptional<z.ZodString>;
+        rowBound: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            count: z.ZodNumber;
+            order: z.ZodOptional<z.ZodEnum<{
+                desc: "desc";
+                asc: "asc";
+            }>>;
+        }, z.core.$strict>>;
         columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            count: "count";
+            identifier: "identifier";
+            category: "category";
+            "p-value": "p-value";
+            effect: "effect";
+        }>>>;
+        columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         run: z.ZodOptional<z.ZodString>;
         path: z.ZodString;
         hash: z.ZodString;
@@ -428,6 +506,8 @@ export declare const UnresolvedReferenceSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ArtifactValueReference = z.infer<typeof ArtifactValueReferenceSchema>;
 export type ArtifactTableReference = z.infer<typeof ArtifactTableReferenceSchema>;
+export type RowBound = z.infer<typeof RowBoundSchema>;
+export type ColumnMeaning = z.infer<typeof ColumnMeaningSchema>;
 export type ArtifactFileReference = z.infer<typeof ArtifactFileReferenceSchema>;
 export type CitationReference = z.infer<typeof CitationReferenceSchema>;
 export type DerivationInputReference = z.infer<typeof DerivationInputReferenceSchema>;
@@ -436,6 +516,14 @@ export type Reference = z.infer<typeof ReferenceSchema>;
 export type ScalarReference = z.infer<typeof ScalarReferenceSchema>;
 export type UnresolvedReason = z.infer<typeof UnresolvedReasonSchema>;
 export type UnresolvedReference = z.infer<typeof UnresolvedReferenceSchema>;
+/**
+ * The declaration that a binding holds for one column, or `undefined` when it holds none.
+ *
+ * A key that names no column of the artifact never reaches this reader, thus a stale declaration after a
+ * re-derivation has no effect. The reader takes an own key alone. Thus a column that carries the name of a
+ * member of the object prototype gives no value, and the declared type stays true at runtime.
+ */
+export declare function declaredForColumn<T>(declarations: Record<string, T> | undefined, column: string): T | undefined;
 /**
  * Serialize a reference to a canonical URI.
  *

package/dist/contracts/report-reference.js

@@ -87,16 +87,51 @@ export const ArtifactValueReferenceSchema = z.strictObject({
     assert: AssertValueSchema.optional().describe("The authored belief that resolution matches against."),
     ...displayShape,
 });
+/**
+ * What one column of a table holds, as a closed set of five.
+ *
+ * A meaning states the content of the column. It is not a format: the design source keeps the one rule for
+ * how each meaning reads on the page, thus no block carries a format field.
+ */
+export const ColumnMeaningSchema = z.enum(["p-value", "effect", "count", "identifier", "category"]);
+/**
+ * The row bound of a whole-table binding: the top rows by one column.
+ *
+ * The bound is content and not presentation. The resolution applies it, thus the resolved table, the
+ * rendered card, the staged data, and the gate all read one bounded set.
+ */
+export const RowBoundSchema = z.strictObject({
+    column: z.string().min(1).describe("The column that ranks the rows. The artifact must hold it, and the bound refuses a name that it does not."),
+    count: z.number().int().positive().describe("How many rows to keep. The bound takes the first rows of the ranked order."),
+    order: z
+        .enum(["desc", "asc"])
+        .optional()
+        .describe("The rank direction. Omit it for `desc`, which keeps the largest values. Use `asc` for a column where the smallest value ranks first, such as a p-value."),
+});
 /**
  * A reference to a whole table artifact. It carries no locator, because it binds every row.
  *
  * It carries no assert. A table is not one value, thus the only belief that an author can hold about it
  * is its bytes, and the pinned `hash` already carries that belief.
+ *
+ * The two declaration maps state what the columns are and what to call them. They ride the whole-table
+ * binding, thus one declaration serves the table block and the chart block alike.
  */
 export const ArtifactTableReferenceSchema = z.strictObject({
     kind: z.literal("artifact-table"),
     ...artifactPinShape,
+    rowBound: RowBoundSchema.optional().describe("The primary size control of a table: the top rows by one column. Bind the whole artifact and bound it here, and never bind a pre-cut copy of the file. A binding with no bound resolves every row of the artifact."),
     columns: z.array(z.string()).optional().describe("An optional column subset to render. Omit to bind every column."),
+    columnMeanings: z
+        .record(z.string(), ColumnMeaningSchema)
+        .optional()
+        .describe("What each column holds, keyed by the raw column name. A meaning is the content of the column, and it is not a format: `p-value` is a probability, `effect` is a signed magnitude such as a fold change, `count` is a whole tally, `identifier` is a name that is written with digits, and `category` is a label. You read the artifact, thus you know which column is which. Declare the columns that you know, and omit the rest. A key that names no column of the artifact has no effect."),
+    columnLabels: z
+        // A label replaces the column name on the page. Empty text names nothing, thus it would blank the
+        // header and the axis title. Omit the key instead, which is the way to declare no label.
+        .record(z.string(), z.string().min(1))
+        .optional()
+        .describe("The display name of each column, keyed by the raw column name. A label names what the column measures, for example `Adjusted p-value` for `padj`. The page shows the label in the table header and in the axis title, and the raw name stays on hover. A key that names no column of the artifact has no effect."),
     ...displayShape,
 });
 /**
@@ -193,6 +228,19 @@ export const UnresolvedReferenceSchema = z.strictObject({
     reason: UnresolvedReasonSchema,
     detail: z.string().optional(),
 });
+/**
+ * The declaration that a binding holds for one column, or `undefined` when it holds none.
+ *
+ * A key that names no column of the artifact never reaches this reader, thus a stale declaration after a
+ * re-derivation has no effect. The reader takes an own key alone. Thus a column that carries the name of a
+ * member of the object prototype gives no value, and the declared type stays true at runtime.
+ */
+export function declaredForColumn(declarations, column) {
+    if (declarations === undefined || !Object.prototype.hasOwnProperty.call(declarations, column)) {
+        return undefined;
+    }
+    return declarations[column];
+}
 /** The URI scheme and version for a serialized reference. The payload after it is opaque. */
 const REFERENCE_URI_PREFIX = "inflexa-ref:v1:";
 /**

package/dist/index.d.ts

@@ -8,7 +8,15 @@ export { assembleCoreRuntime } from "./runtime/assemble.js";
 export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable, MakeReportReferenceResolver, ReportResolverScope, } from "./runtime/assemble.js";
 export type { ReferenceResolver, ReportSnapshot, ResolvedValue } from "./report-model/reference-resolver.js";
 export type { ResolvePageAsset } from "./tools/report-session/index.js";
+export { PAGE_ASSETS } from "./report-render/assets.js";
+export type { PageAsset } from "./report-render/assets.js";
+export { createStaticEyes } from "./lib/eyes.js";
+export type { AcquireEyes, EyesScope, EyesLease } from "./lib/eyes.js";
+export { resolveCompositionEyes } from "./runtime/assemble.js";
 export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
+export { createReportSessionSpawn } from "./app/spawn-report-session.js";
+export type { ReportSessionSpawn, ReportSessionSpawnDeps, ReportSessionPaging, SpawnRefusal, ReportBrief, ReportSessionDelta, NewestReportChild, } from "./app/spawn-report-session.js";
+export type { EnsureSessionStateResult } from "./app/report-session-runtime.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
@@ -151,6 +159,7 @@ export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parse
 export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 export { runStepDir } from "./workspace/paths.js";
+export { reportSessionDir } from "./workspace/paths.js";
 export type { LogFields, LogLevel, Logger } from "./lib/logger.js";
 export { defaultErrorFields } from "./lib/logger.js";
 export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";

package/dist/index.js

@@ -6,6 +6,22 @@
  */
 // Runtime assembly + composition root.
 export { assembleCoreRuntime } from "./runtime/assemble.js";
+export { PAGE_ASSETS } from "./report-render/assets.js";
+// Seam: the eyes of a report session — where a browser comes from for one look at the
+// rendered page. A host with a standing sidecar names the endpoint in its chrome config, and
+// the assembly wraps it. A host with no sidecar starts a browser for one look, thus it binds
+// its own realization. The names of the acquire, the scope, and the lease then belong on the
+// front door. `createStaticEyes` is the shipped realization over a standing sidecar, and an
+// embedder that wires the spawn itself binds the same eyes there. That embedder reads the same
+// precedence through `resolveCompositionEyes`: the bound seam first, then a chrome config that
+// names a browser. Thus the gate of the spawn and the gate of the look cannot disagree. A
+// runtime that can look never carries a spawn that refuses with `no_browser`.
+export { createStaticEyes } from "./lib/eyes.js";
+export { resolveCompositionEyes } from "./runtime/assemble.js";
+// The report-session spawn makes a `report` child thread, and its listing gives
+// the report sessions of one analysis. An embedder reaches the listing for its
+// navigation surface, thus these names belong on the front door.
+export { createReportSessionSpawn } from "./app/spawn-report-session.js";
 // The harness-owned boot sequence: ordered boot steps around `assembleCoreRuntime`
 // (skill validation → state init → connection budget → assemble → launch) + a
 // `shutdown` handle the embedder wires to its process signals.
@@ -241,6 +257,10 @@ export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 // Workspace-tree path convention — the root-relative step directory each
 // sandbox step confines its artifact writes to (join onto the resolved root).
 export { runStepDir } from "./workspace/paths.js";
+// An embedder removes the page files of a purged report session. Thus it needs
+// the root-relative directory of that session, and it restates no layout of the
+// harness.
+export { reportSessionDir } from "./workspace/paths.js";
 // `Logger.errorFields` is on the interface so a realization can defer to its
 // sink's native error handling (pino's `err` serializer, OTel's `exception.*`);
 // `defaultErrorFields` is the shipped mapping for one with no opinion.

package/dist/lib/chrome.d.ts

@@ -1,10 +1,12 @@
 /**
- * Headless Chrome connection — process-lifetime singleton connected to the
- * Chrome sidecar reachable at `CHROME_BROWSER_URL`. Used by the iterate-report
- * preview-snapshot tool for visual validation.
+ * The connection to a headless Chrome endpoint.
  *
- * Connection is lazy and reconnect-on-disconnect; pages are gated through a
- * semaphore so the sidecar isn't overwhelmed by concurrent reports.
+ * Two callers name an endpoint. A composition names a standing sidecar at assembly, and a lease of the eyes
+ * seam names a browser for one look. Thus the module holds one connection for each endpoint, and it holds no
+ * connection for the process.
+ *
+ * A connection is lazy, and an endpoint connects again after a disconnect. Each endpoint also carries its own
+ * page gate. The gate bounds the pages that run at the same time against that one sidecar.
  */
 import type { Browser, BrowserContext, Page } from "puppeteer-core";
 import type { Logger } from "./logger.js";
@@ -26,7 +28,25 @@ export interface ChromeConfig {
 /**
  * Whether the config names a browser to connect to. A composition with no endpoint has no eyes, and a
  * caller reads that up front instead of failing once for each attempted connection.
+ *
+ * The predicate narrows the config. Thus a caller that reads the endpoint after the gate needs no type
+ * assertion for a field that the gate proved.
+ */
+export declare function hasBrowserUrl(cfg: ChromeConfig): cfg is ChromeConfig & {
+    readonly browserUrl: string;
+};
+/** The connect operation of one endpoint. */
+export type BrowserConnector = (browserUrl: string) => Promise<Browser>;
+/**
+ * Replace the connect operation, and give back the restore of the previous one.
+ *
+ * The cache keeps no state that a caller can read, because a connection is the only product of the module.
+ * Thus a real browser is the only other way to drive the cache, and a unit test of the keys needs this seam.
+ *
+ * Two facts make the seam safe. The module reads the binding at each connect, and no module under `src/`
+ * calls the setter. Thus a deployment always runs the connect of puppeteer. The caller restores the previous
+ * binding, thus a replacement never reaches a later file of the same test run.
  */
-export declare function hasBrowserUrl(cfg: ChromeConfig): boolean;
+export declare function setBrowserConnector(next: BrowserConnector): () => void;
 export declare function getBrowser(browserUrl?: string, injected?: Logger): Promise<Browser>;
 export declare function withPage<T>(cfg: ChromeConfig, fn: (page: Page, context: BrowserContext) => Promise<T>): Promise<T>;