@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/contracts/report-blocks.js

@@ -14,12 +14,40 @@
  * rule only when an extra field fails the parse.
  */
 import { z } from "zod";
-import { ArtifactFileReferenceSchema, ArtifactTableReferenceSchema, CitationReferenceSchema, ReferenceSchema, ScalarReferenceSchema, } from "./report-reference.js";
+import { ArtifactFileReferenceSchema, ArtifactTableReferenceSchema, ArtifactValueReferenceSchema, CitationReferenceSchema, ReferenceSchema, ScalarReferenceSchema, } from "./report-reference.js";
 /**
- * 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.
+ * The chart vocabulary. The first eleven values name one plot form each. Each value after them is a preset:
+ * the canonical figure of one plot of a field, which the renderer derives from its own figure module.
  */
-const ChartTypeSchema = z.enum(["bar", "line", "scatter", "histogram", "box", "heatmap", "pie", "volcano", "manhattan", "ma", "km"]);
+const ChartTypeSchema = z.enum([
+    "bar",
+    "line",
+    "scatter",
+    "histogram",
+    "box",
+    "heatmap",
+    "pie",
+    "violin",
+    "stacked-bar",
+    "normalized-bar",
+    "radar",
+    "volcano",
+    "manhattan",
+    "ma",
+    "km",
+    "pca",
+    "embedding",
+    "dotplot",
+    "forest",
+    "roc",
+    "qq",
+    "gsea",
+    "oncoprint",
+    "lollipop",
+    "upset",
+    "sankey",
+    "locuszoom",
+]);
 /** The per-row transforms of a channel. Each derived value comes from one cell. */
 const ChartTransformSchema = z.enum(["log10", "neg_log10", "abs", "rank"]);
 /**
@@ -28,52 +56,170 @@ const ChartTransformSchema = z.enum(["log10", "neg_log10", "abs", "rank"]);
  */
 const ChartOrientationSchema = z.enum(["vertical", "horizontal"]);
 /**
- * The threshold pair of a preset that classifies its rows.
+ * The thresholds 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.
+ * drawn lines, and no second declaration can disagree with the first one. A volcano reads the pair. An MA
+ * reads the significance cut against its `p` column alone, thus the chart block holds the effect cut to the
+ * volcano.
  */
 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."),
+        .describe("The significance cut of the p column, for example `0.05`. On a `volcano` the guide line sits at the transformed value of it, and a point past the line reads as significant. On an `ma` a point whose `p` is under the cut draws in the signal color."),
     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."),
+        .optional()
+        .describe("The effect cut of a `volcano`, 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. A `volcano` needs it beside the significance cut, and an `ma` refuses it."),
 });
 /** 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.
+ * One visual channel: a column name, or a column with a per-row transform and a category order.
  *
- * 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.
+ * The object form carries column names and closed enum members, and it carries no value. Thus a channel can
+ * never bring a data literal into the chart option. The refine holds the order direction to a declared sort
+ * column, because a direction with nothing to sort by names a rule that nothing reads.
  */
 export const ChartChannelSchema = z.union([
     z.string().describe("The column that feeds the channel."),
-    z.strictObject({
+    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."),
+        transform: ChartTransformSchema.optional().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 axis title puts the label of the column inside the transform, for example `log10(Normalized count)`, thus the label names the untransformed column."),
+        orderBy: z
+            .string()
+            .optional()
+            .describe("The column that sorts the categories of this channel, for example the leaf order of a clustered heatmap or the score of a ranked bar. Each category must hold one value in this column. A tie keeps the order of the rows. It is legal on a channel that draws a category axis alone."),
+        order: z
+            .enum(["asc", "desc"])
+            .optional()
+            .describe("The direction of the `orderBy` sort. `asc` is the default, and `desc` puts the largest value first. It is legal beside `orderBy` alone."),
+    })
+        .refine((channel) => channel.order === undefined || channel.orderBy !== undefined, {
+        message: "`order` is legal beside `orderBy` alone. Name the column that sorts the categories.",
+        path: ["order"],
     }),
 ]);
+/** The teaching text of the continuous color channel. The quick path and a series both carry it. */
+const COLOR_DESCRIPTION = "A numeric column that colors each point or bar on a continuous scale, for example the expression of a gene over an embedding or the adjusted p of an enriched set. A column that holds values on both sides of zero takes a diverging scale centered on zero, and every other column takes a sequential scale. It is legal on a `scatter`, a `bar`, an `embedding`, a `dotplot`, and a `locuszoom`, and never beside a `group` channel. On an `embedding` a zero draws in a light gray ground, the scale clips at the 99th percentile, and the high values draw on top. On a `dotplot` the scale is sequential. On a `locuszoom` it names the r² of each variant with the lead variant, and the points take the five LD bins of LocusZoom. A row whose cell is not numeric draws no point, except on a `locuszoom`, where it draws gray.";
+/** The teaching text of the size channel. The quick path and a series both carry it. */
+const SIZE_DESCRIPTION = "A numeric column that sizes each point, for example the gene count of an enrichment dot plot. It is legal on a `scatter`, a `forest`, and a `dotplot`. On a `forest` it sets the area of each square, for example the weight of a study. On a `dotplot` a size legend of three reference circles names it. A row whose cell is not numeric draws no point.";
+/** The teaching text of the lower interval bound. The quick path and a series both carry it. */
+const LOW_DESCRIPTION = "The column of the lower bound of an interval around each plotted value, for example the lower confidence limit of a forest plot or of an error bar. Give `high` with it. The bound sits on the value axis, and a lower bound above its value is a fault. It is legal on a `bar`, a `scatter`, a `km`, a `forest`, and a `qq`. On a `km` the two bounds draw the confidence band of each curve as a step band. On a `qq` the two bounds draw the band of the null expectation under the points.";
+/** The teaching text of the upper interval bound. The quick path and a series both carry it. */
+const HIGH_DESCRIPTION = "The column of the upper bound of an interval around each plotted value. Give `low` with it. An upper bound under its value is a fault. It is legal on a `bar`, a `scatter`, a `km`, a `forest`, and a `qq`. On a `km` the two bounds draw the confidence band of each curve as a step band. On a `qq` the two bounds draw the band of the null expectation under the points.";
+/** The teaching text of the facet channel. The quick path and a composition both carry it. */
+const FACET_DESCRIPTION = "A category column that splits one table into small multiples: one panel for each value, in the order of the rows, with one shared axis range. At most 12 panels. It is legal on a `scatter`, a `line`, a `bar`, a `stacked-bar`, a `normalized-bar`, and an `embedding`. Each panel of an `embedding` keeps one unit on x and y. Each panel of a stacked form stacks the parts of its own rows, for example the cell-type shares of each donor under each condition.";
+/** The teaching text of the shape channel. */
+const SHAPE_DESCRIPTION = "A category column that sets the symbol of each point beside the color of `group`, for example the batch of each sample on a PCA plot. At most 6 categories. It is legal on a `pca` and a `scatter`. A `scatter` with a shape reads `x`, `y`, `group`, and `label` beside it, and no other channel.";
+/** The teaching text of the p channel. */
+const P_DESCRIPTION = "The p-value column that a figure reads beside its two axes. On an `ma` a point under the significance cut draws in the signal color, and every other point draws gray. On a `forest` the column prints as a text column beside the estimate column. It is legal on an `ma` and a `forest`.";
+/** The teaching text of the censor channel. */
+const CENSOR_DESCRIPTION = "The count of subjects censored at the time of the row. A row with a count above zero carries a small tick on its curve. It is legal on a `km`.";
+/** The teaching text of the risk channel. */
+const RISK_DESCRIPTION = "The number of subjects at risk at the time of the row. The number-at-risk table under the plot reads it at each tick of the time axis. It is legal on a `km`.";
+/** The teaching text of the hit channel. */
+const HIT_DESCRIPTION = "1 where the gene at the rank of the row is a member of the set, else 0. The middle panel draws one tick at each hit. It is legal on a `gsea`.";
+/** The teaching text of the metric channel. */
+const METRIC_DESCRIPTION = "The second numeric column of a figure. On a `gsea` it is the ranking metric at the rank of the row, for example the signed statistic of a differential test, and the bottom panel draws it as an area. On a `locuszoom` it is the recombination rate in cM/Mb at the position of the row, and it draws as a line on a right axis. It is legal on a `gsea` and a `locuszoom`.";
+/** The teaching text of the tracks channel. */
+const TRACKS_DESCRIPTION = "One to four category columns that draw as annotation strips along the x axis, for example the condition and the batch of each sample. Each column must hold one value for each x category. It is legal on a `heatmap` and an `oncoprint`.";
+/** The one refine rule of an interval: the two bounds arrive together. */
+function holdsBothBounds(encoding) {
+    return (encoding.low === undefined) === (encoding.high === undefined);
+}
+/** The refusal of a lone interval bound. */
+const LONE_BOUND = { message: "An interval has two bounds. Give `low` and `high` together.", path: ["low"] };
 /** The mapping from a data column to a visual channel. Each channel is optional. */
-const ChartEncodingSchema = z.strictObject({
-    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."),
+const ChartEncodingSchema = z
+    .strictObject({
+    x: ChartChannelSchema.optional().describe("The channel on the x axis. On an `upset` it names the element of each membership row, for example a sample. On a `sankey` it names the source node of each flow. On a `locuszoom` it names the position in base pairs on one chromosome, and the axis reads in megabases."),
+    y: ChartChannelSchema.optional().describe("The channel on the y axis. On a `sankey` it names the target node of each flow."),
+    group: ChartChannelSchema.optional().describe("The column that splits and colors the series. On a `pie` it names the slices. On a `lollipop` it names the mutation class of each row, and a common class of the MAF standard takes its fixed color. On an `upset` it names the set of each membership row, for example a mutated gene. At most 12 sets. On a `sankey` it is optional, and it names the category of each flow: each flow takes the palette color of its category, and the nodes draw gray. On a `locuszoom` it is optional, and it names the chromosome of each row. The rows must hold one chromosome, and the x title names it."),
+    value: ChartChannelSchema.optional().describe("The value column of a `pie`, a `heatmap`, and a `sankey`. On a `pie` it sizes each slice, and `group` names the slices. On a `heatmap` it colors each cell. On a `sankey` it gives the size of each flow. On an `oncoprint` it names the alteration class of each gene and sample, for example `Missense_Mutation`. A row with an empty class names a sample with no alteration."),
+    label: z
+        .string()
+        .optional()
+        .describe("The column that names each point. The name rides the tooltip of a bar, a line, and a scatter. On a `lollipop` the three largest counts carry it as text, for example the protein change. On a `volcano` the ten most significant signal points show it, on a `manhattan` the lead variant of each chromosome shows it, and on a `locuszoom` the lead variant shows it."),
+    color: ChartChannelSchema.optional().describe(COLOR_DESCRIPTION),
+    size: ChartChannelSchema.optional().describe(SIZE_DESCRIPTION),
+    low: ChartChannelSchema.optional().describe(LOW_DESCRIPTION),
+    high: ChartChannelSchema.optional().describe(HIGH_DESCRIPTION),
+    facet: ChartChannelSchema.optional().describe(FACET_DESCRIPTION),
+    shape: ChartChannelSchema.optional().describe(SHAPE_DESCRIPTION),
+    p: ChartChannelSchema.optional().describe(P_DESCRIPTION),
+    censor: ChartChannelSchema.optional().describe(CENSOR_DESCRIPTION),
+    risk: ChartChannelSchema.optional().describe(RISK_DESCRIPTION),
+    hit: ChartChannelSchema.optional().describe(HIT_DESCRIPTION),
+    metric: ChartChannelSchema.optional().describe(METRIC_DESCRIPTION),
+    tracks: z.array(z.string().min(1)).min(1).max(4).optional().describe(TRACKS_DESCRIPTION),
+})
+    .refine(holdsBothBounds, LONE_BOUND);
+/**
+ * One statistic of a figure: a short name, and the one cell that gives its value.
+ *
+ * The value is an artifact reference and never a literal, thus a printed statistic is grounded exactly as a
+ * metric is.
+ */
+export const ChartStatisticSchema = z.strictObject({
+    label: z.string().min(1).describe("The short name of the statistic, for example `Log-rank p`, `AUC`, or `λ`."),
+    value: ArtifactValueReferenceSchema.describe("The one cell that gives the value of the statistic."),
 });
+/**
+ * The second table of a figure, and the four columns of it that the figure reads.
+ *
+ * The track binds a whole table exactly as the chart binding does, thus it resolves and it grounds the same
+ * way.
+ */
+export const ChartTrackSchema = z.strictObject({
+    binding: ArtifactTableReferenceSchema.describe("The whole-table artifact of the track, for example the protein domains of a gene."),
+    start: z.string().min(1).describe("The column of the track table that holds the start position of each feature."),
+    end: z.string().min(1).describe("The column of the track table that holds the end position of each feature."),
+    label: z.string().min(1).describe("The column of the track table that names each feature, for example the domain name."),
+    length: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The column of the track table that holds the full length, for example the length of the protein. The x axis then ends at that length."),
+});
+/**
+ * The tree of one category axis of a heatmap: an edge list, and the three columns of it that the figure reads.
+ *
+ * The tree binds a whole table exactly as the chart binding does, thus it resolves and it grounds the same way.
+ */
+export const ChartTreeSchema = z.strictObject({
+    binding: ArtifactTableReferenceSchema.describe("The whole-table artifact of the tree: one row for each edge of the linkage, for example the gene tree of a hierarchical clustering."),
+    parent: z.string().min(1).describe("The column of the tree table that names the parent node of each edge."),
+    child: z
+        .string()
+        .min(1)
+        .describe("The column of the tree table that names the child node of each edge. A leaf is a child that is never a parent, and it equals one category of its axis."),
+    height: z.string().min(1).describe("The column of the tree table that holds the height of the parent node of each edge, for example the merge distance."),
+});
+/** The trees of the two category axes of a heatmap. A member names one axis, and at least one member is present. */
+const ChartTreesSchema = z
+    .strictObject({
+    x: ChartTreeSchema.optional().describe("The tree of the `x` categories. It draws above the matrix and above the tracks."),
+    y: ChartTreeSchema.optional().describe("The tree of the `y` categories. It draws at the left of the row names."),
+})
+    .refine((trees) => trees.x !== undefined || trees.y !== undefined, { message: "The trees name at least one axis. Give `x`, `y`, or both." });
 /** The channels of one series. A series plots two channels, thus `x` and `y` are both present. */
-const ChartSeriesEncodingSchema = z.strictObject({
+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."),
-});
+    color: ChartChannelSchema.optional().describe(COLOR_DESCRIPTION),
+    size: ChartChannelSchema.optional().describe(SIZE_DESCRIPTION),
+    low: ChartChannelSchema.optional().describe(LOW_DESCRIPTION),
+    high: ChartChannelSchema.optional().describe(HIGH_DESCRIPTION),
+})
+    .refine(holdsBothBounds, LONE_BOUND);
 /**
  * One series of a composition: a plot form, its own channels, and an optional legend name.
  *
@@ -135,11 +281,15 @@ 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. */
+/**
+ * The full chart grammar: the series, the annotations, the axes, and the facet. 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."),
+    facet: ChartChannelSchema.optional().describe(`${FACET_DESCRIPTION} On a composition, the first series has one of those forms.`),
 });
 /**
  * One typed list of a text block: the flag that selects the form, and the items.
@@ -202,11 +352,37 @@ export const ChartBlockSchema = z
     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.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."),
+    chartType: ChartTypeSchema.optional().describe("The quick path. Give `encoding` with it, and omit `composition`. Each base type reads these channels. " +
+        "A `bar` draws the `y` value of each category of `x`. A `line` and a `scatter` draw `y` against `x`. A `histogram` counts the values of `x` alone in bins. " +
+        "A `box` draws the spread of `y` in each category of `x`, and a `violin` draws the density of `y` in each category of `x`. A `box` and a `violin` with no `group` draw each value as a point over the shape where a category holds 200 values or fewer. " +
+        "A `stacked-bar` stacks the `y` values of the `group` parts in each category of `x`, a `normalized-bar` stacks their shares, and a `radar` draws one polygon of `y` values for each `group` over the categories of `x`. These three need a `group` channel. " +
+        "A `heatmap` draws `value` over each pair of `x` and `y`, and its `tracks` draw annotation strips over the matrix. " +
+        "A `pie` reads no `x` and no `y`. Its `group` column names the slices, and its `value` column sizes them. " +
+        "A preset draws the canonical figure of one plot of a field from one table, and it reads its own channels: " +
+        "`volcano` (x effect, y p), `manhattan` (x cumulative position, y p, group chromosome), `ma` (x mean, y effect, p), `km` (x time, y survival, group arm, low, high, censor, risk), " +
+        "`pca` (x and y components, group, shape, label), `embedding` (x and y of a UMAP or a t-SNE, group or color, facet), `dotplot` (y category, x category or value, size, color), " +
+        "`forest` (y term, x estimate, low, high, p, size), `roc` (x false positive rate, y true positive rate, group), `qq` (x expected, y observed, low, high), " +
+        "`gsea` (x rank, y running score, group set, hit, metric), `oncoprint` (x sample, y gene, value alteration class, tracks), `lollipop` (x amino-acid position, y count, group class, label, and the track of the protein domains), " +
+        "`upset` (x element, group set, one row for each member of each set, and the figure counts the intersections), `sankey` (x source node, y target node, value flow, group, one row for each flow with no cycle), " +
+        "and `locuszoom` (x position on one chromosome, y p, color r² with the lead variant, label variant, metric recombination rate, group chromosome, and the track of the genes). " +
+        "A preset 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."),
+    orientation: ChartOrientationSchema.optional().describe(`${ORIENTATION_DESCRIPTION} The field belongs to the \`bar\`, the \`stacked-bar\`, and the \`normalized-bar\` chart types, and every other type refuses it.`),
+    thresholds: ChartThresholdsSchema.optional().describe("The thresholds of a `volcano` and of an `ma`. On a `volcano` give the pair: it replaces the preset defaults of `0.05` and `1`, and it moves the guide lines and the color split together. On an `ma` give the significance cut alone: it replaces the default of `0.1`, and it moves the color split of the `p` 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."),
+    focus: z
+        .array(z.string())
+        .min(1)
+        .optional()
+        .describe("The category values of the finding. Each named category takes the one focus color, and every other category is muted. On a bar with no `group` channel a category is a value of `x`, and on every other chart it is a value of `group`. It is legal on a bar and the two stacked forms, and on a grouped scatter, line, box, violin, and radar. It is never legal beside a `color` channel."),
+    statistics: z
+        .array(ChartStatisticSchema)
+        .min(1)
+        .max(4)
+        .optional()
+        .describe("One to four statistics that the figure prints inside the plot, at the place that its field uses, for example a log-rank p, an AUC, or the genomic inflation λ. Each value binds one cell of a pinned artifact, and the page prints it in the number format of its column. It is legal on a `km`, a `roc`, a `qq`, and a `gsea`."),
+    track: ChartTrackSchema.optional().describe("A second table that the figure draws beside the bound table, for example the protein domains under the axis of a lollipop or the genes under a regional association plot. It is legal on a `lollipop` and a `locuszoom`."),
+    trees: ChartTreesSchema.optional().describe("The dendrogram of each category axis of a `heatmap`: one edge table for each axis, for example the gene tree and the sample tree of a hierarchical clustering. The axis takes the depth-first leaf order of its tree, thus an `orderBy` on the same axis refuses. It is legal on a `heatmap`."),
     caption: z.string().optional(),
 })
     .refine((block) => {
@@ -217,11 +393,20 @@ export const ChartBlockSchema = z
     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.",
+    .refine((block) => block.thresholds === undefined || block.chartType === "volcano" || block.chartType === "ma", {
+    // 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` and the `ma` chart types alone. Every other type reads no threshold.",
     path: ["thresholds"],
+})
+    .refine((block) => block.chartType !== "volcano" || block.thresholds === undefined || block.thresholds.effect !== undefined, {
+    // The member moves the guide lines and the split of both axes, thus a volcano states both cuts.
+    message: "The thresholds of a `volcano` are a pair. Give the `effect` cut beside the `significance` cut.",
+    path: ["thresholds", "effect"],
+})
+    .refine((block) => block.chartType !== "ma" || block.thresholds?.effect === undefined, {
+    // An MA splits its rows by the p column alone, thus an effect cut would move nothing.
+    message: "An `ma` reads the `significance` cut alone. Omit the `effect` cut.",
+    path: ["thresholds", "effect"],
 });
 /** A static image artifact. An image has no per-cell address, thus it is pinned whole-file. */
 export const FigureBlockSchema = z.strictObject({
@@ -290,3 +475,10 @@ export function channelColumn(channel) {
 export function channelTransform(channel) {
     return typeof channel === "string" ? undefined : channel.transform;
 }
+/** The category order of one channel, or `undefined` when the channel declares none. */
+export function channelOrder(channel) {
+    if (typeof channel === "string" || channel.orderBy === undefined) {
+        return undefined;
+    }
+    return { by: channel.orderBy, order: channel.order ?? "asc" };
+}

package/dist/contracts/report-reference.js

@@ -131,7 +131,7 @@ export const ArtifactTableReferenceSchema = z.strictObject({
         // 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."),
+        .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. Name the raw column, never a transform of it: the header shows the raw values, and a chart channel with a transform states the transform on its axis itself, for example `log10(Normalized count)`. A key that names no column of the artifact has no effect."),
     ...displayShape,
 });
 /**

package/dist/contracts/schemas/chat-events.d.ts

@@ -14,6 +14,13 @@ export declare const TextDeltaEventSchema: z.ZodObject<{
         callPath: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const IterationEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"iteration">;
+    source: z.ZodObject<{
+        agentId: z.ZodString;
+        callPath: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 /** Mirrors the `ToolOutcome` union — three states, never a boolean. */
 export declare const ToolOutcomeSchema: z.ZodEnum<{
     error: "error";
@@ -90,6 +97,12 @@ export declare const ChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"iteration">;
+    source: z.ZodObject<{
+        agentId: z.ZodString;
+        callPath: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool-started">;
     toolUseId: z.ZodString;

package/dist/contracts/schemas/chat-events.js

@@ -12,6 +12,10 @@ export const TextDeltaEventSchema = z.object({
     text: z.string(),
     source: EventSourceSchema,
 });
+export const IterationEventSchema = z.object({
+    type: z.literal("iteration"),
+    source: EventSourceSchema,
+});
 /** Mirrors the `ToolOutcome` union — three states, never a boolean. */
 export const ToolOutcomeSchema = z.enum(["ok", "error", "denied"]);
 /** Mirrors `ToolCallOutcome` — the live three plus the record-only `incomplete`. */
@@ -47,6 +51,7 @@ export const ChatErrorEventSchema = z.object({
 });
 export const ChatEventSchema = z.discriminatedUnion("type", [
     TextDeltaEventSchema,
+    IterationEventSchema,
     ToolStartedEventSchema,
     ToolFinishedEventSchema,
     FinishEventSchema,

package/dist/contracts/schemas/chat-parts.d.ts

@@ -494,8 +494,8 @@ export declare const CompactionPartSchema: z.ZodObject<{
     id: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
-        done: "done";
         running: "running";
+        done: "done";
     }>;
     tokensBefore: z.ZodNumber;
     tokensAfter: z.ZodOptional<z.ZodNumber>;
@@ -810,8 +810,8 @@ export declare const ChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
-        done: "done";
         running: "running";
+        done: "done";
     }>;
     tokensBefore: z.ZodNumber;
     tokensAfter: z.ZodOptional<z.ZodNumber>;

package/dist/contracts/schemas/index.d.ts

@@ -1,3 +1,3 @@
 export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, ChatPartSchema, } from "./chat-parts.js";
-export { EventSourceSchema, TextDeltaEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
+export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
 export { TokenUsageRollupSchema } from "./usage.js";

package/dist/contracts/schemas/index.js

@@ -1,3 +1,3 @@
 export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, ChatPartSchema, } from "./chat-parts.js";
-export { EventSourceSchema, TextDeltaEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
+export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
 export { TokenUsageRollupSchema } from "./usage.js";

package/dist/execution/input-signature.d.ts

@@ -1,22 +1,16 @@
 /**
- * The input signature — the fixed-width comparand a completed profile persists in
- * place of a per-file identity list.
+ * The input signature — the fixed-width record of the kept input set that a completed
+ * profile persists in place of a per-file identity list.
  *
- * A per-file identity list would have exactly one consumer, the staleness comparison —
- * several thousand identifiers persisted, detoasted on every read of the row, and
- * compared element-wise to answer a question 40 bytes answer. The signature covers
- * `size` and `mtimeMs` as well, so it also notices that the bytes behind a path
- * changed — a `fileId` is a path identity and survives an in-place edit unchanged.
+ * It covers `size` and `mtimeMs` as well as the `fileId`, so it also records the bytes
+ * behind a path — a `fileId` is a path identity and survives an in-place edit unchanged.
+ * Nothing compares it: the staleness of a profile reads only the profile ledger.
  *
  * Order independence is a property of the digest, not of the caller: entries are
  * sorted canonically before hashing, so two enumerations of the same set agree.
  *
- * It digests KEPT files only — quarantine runs before the digest, on both sides of the
- * comparison. A partial-download twin or an OS droppings file was never part of what was
- * profiled, so its appearance, edit, or removal is not drift, and a profile that
- * re-triggered on it would re-run on churn nobody caused. A change to the quarantine rules
- * themselves recomputes every signature once on the next scan, which is the correct
- * consequence: the definition of "kept" changed.
+ * It digests KEPT files only — quarantine runs before the digest. A partial-download twin
+ * or an OS droppings file was never part of what was profiled.
  */
 import type { DataProfileInputSignature } from "../state/data-profile.js";
 import type { StagedInput } from "./staged-input.js";

package/dist/execution/run-canceler.d.ts

@@ -14,8 +14,9 @@
  * engine (see `dbos-workflow-purger.ts` for why the static `DBOS` facade is
  * the wrong tool here). `cancelWorkflows` is an optional test seam over it.
  *
- * No stream writes: `DBOS.writeStream` is body-only, so hosts synthesize the
- * terminal frame read-side.
+ * No stream writes: `DBOS.writeStream` writes only from inside the workflow
+ * that owns the stream, so the run-event reader (`run-event-stream.ts`)
+ * synthesizes the terminal part from the run row.
  */
 import type { Pool } from "pg";
 import type { AgentSession } from "../auth/types.js";

package/dist/execution/run-canceler.js

@@ -14,8 +14,9 @@
  * engine (see `dbos-workflow-purger.ts` for why the static `DBOS` facade is
  * the wrong tool here). `cancelWorkflows` is an optional test seam over it.
  *
- * No stream writes: `DBOS.writeStream` is body-only, so hosts synthesize the
- * terminal frame read-side.
+ * No stream writes: `DBOS.writeStream` writes only from inside the workflow
+ * that owns the stream, so the run-event reader (`run-event-stream.ts`)
+ * synthesizes the terminal part from the run row.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";

package/dist/execution/run-event-stream.d.ts

@@ -30,9 +30,12 @@
  * that tore itself down on one bad part would be strictly less robust than the
  * writer it observes.
  */
+import type { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import type { ChatPart } from "../contracts/chat-parts.js";
+import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
+import type { RunStatus } from "../state/schema.js";
 /**
  * Construction-time dependencies. The pool is the application pool the run
  * ledger lives in; the logger is where every contained failure is reported, and
@@ -42,6 +45,10 @@ import type { Logger } from "../lib/logger.js";
 export interface RunEventStreamDeps {
     readonly pool: Pool;
     readonly logger?: Logger;
+    /** Reads the status of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
+    readonly readRunStatus?: (runId: string) => ResultAsync<RunStatus | null, DbError>;
+    /** The wait between two reads of the run row. Defaults to a timer. */
+    readonly sleep?: (ms: number) => Promise<void>;
 }
 /**
  * Receives one part. May be async — the subscription awaits it, so a handler is
@@ -66,8 +73,15 @@ export interface RunEventSubscribeOptions {
 export interface RunEventStream {
     /**
      * Deliver every part the run produces — parent and children alike — to
-     * `onPart`, resolving when the run is terminal and every stream opened has
-     * drained, or promptly when the signal aborts.
+     * `onPart`, resolving when the run is terminal, every stream opened has
+     * drained, and `onPart` has taken the last part, or promptly when the signal
+     * aborts.
+     *
+     * A canceled workflow runs no more steps, thus it never writes its own
+     * terminal part, and the canceler cannot write a stream. When the parent
+     * stream ends with no `data-run-completed` or `data-run-failed` part and
+     * the run row reads `canceled`, the last part delivered is a
+     * `data-run-failed` part with `reason: "canceled"`.
      *
      * Parts from one workflow arrive in the order that workflow wrote them. No
      * order is promised ACROSS the parent and its children: those workflows