@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/report-model/reference-stamp.js

@@ -0,0 +1,173 @@
+/**
+ * The hash stamp of the land path, and the hash elision of the read.
+ *
+ * An artifact reference pins a path and a content hash. The pinned snapshot already maps each path onto
+ * its hash, thus the author of a block gives the path alone. The stamp fills the hash from the snapshot,
+ * and a reference that names the path lands.
+ *
+ * The stamp also drops a hash that a payload carries. The snapshot owns the value. Thus an echoed binding
+ * and a mistyped one both land with the hash of the snapshot entry, and the structural tier reads no stale
+ * pin on the land path.
+ *
+ * The walk is structural, because it runs before the grammar parse. It reads the artifact-reference shape
+ * alone: a pinned kind and a string path. Every other value passes through untouched, thus a nested block,
+ * a derivation input, and a plain field are all safe.
+ *
+ * A reference whose path the snapshot does not hold refuses here. Without this arm the parse refuses the
+ * absent hash, and that message sends the author to the wrong repair.
+ *
+ * The elision walks the same shape in the other direction: a read of a landed block gives each binding
+ * with no hash. Thus one module holds both directions, and the two agree on which object carries a pin.
+ */
+import { err, ok } from "neverthrow";
+import { snapshotEntry } from "./reference-resolver.js";
+/**
+ * The three reference kinds that name one artifact directly, thus the three kinds that take a hash.
+ *
+ * The `satisfies` clause ties each literal to a member of the reference union. A renamed kind becomes a
+ * compile error here. A new kind passes with no error, because the stamp fills a known kind and it never
+ * refuses one.
+ */
+const PINNED_KINDS = new Set(["artifact-value", "artifact-table", "artifact-file"]);
+/** Give `true` when an object carries an artifact pin. Such an object takes a stamp, and a read removes its hash. */
+function holdsPin(record) {
+    const { kind } = record;
+    return typeof kind === "string" && PINNED_KINDS.has(kind);
+}
+/**
+ * Put one own data property on a copy.
+ *
+ * A plain assignment at the key `__proto__` reaches the prototype setter, thus the copy loses an own key
+ * that the payload carries. 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 });
+}
+/**
+ * Give the artifact path of an object that takes a stamp, or `undefined` when the object takes none.
+ *
+ * The test reads the shape alone, because the payload reaches the stamp before the grammar parse. A hash
+ * that the object carries decides nothing here, because the stamp writes the hash of the snapshot over it.
+ */
+function stampablePath(record) {
+    const { path } = record;
+    if (!holdsPin(record) || typeof path !== "string") {
+        return undefined;
+    }
+    return path;
+}
+/**
+ * Walk one value, and give the value with the hash of each artifact reference filled from the snapshot.
+ *
+ * The walk builds a copy on the changed path only. A branch that no stamp touched comes back as the same
+ * reference, thus the input stays intact and the copy costs the size of the change.
+ */
+function stampValue(value, snapshot, missing) {
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = [];
+        for (const item of value) {
+            const stamped = stampValue(item, snapshot, missing);
+            if (stamped !== item) {
+                changed = true;
+            }
+            next.push(stamped);
+        }
+        return changed ? next : value;
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    let changed = false;
+    const next = {};
+    for (const key of Object.keys(record)) {
+        const stamped = stampValue(record[key], snapshot, missing);
+        if (stamped !== record[key]) {
+            changed = true;
+        }
+        defineOwn(next, key, stamped);
+    }
+    const path = stampablePath(record);
+    if (path === undefined) {
+        return changed ? next : value;
+    }
+    const entry = snapshotEntry(snapshot, path);
+    if (entry === undefined) {
+        missing.push({ path, record });
+        return changed ? next : value;
+    }
+    return { ...next, hash: entry.hash };
+}
+/**
+ * Stamp the hash of each artifact reference in a block payload, from the snapshot entry at its path.
+ *
+ * The membership read is `snapshotEntry`, because the path is author text. An own key alone counts, thus
+ * an inherited member of a plain object reads as absent and the stamp agrees with the structural tier.
+ *
+ * The whole call refuses when one reference names a path that the snapshot does not hold. A partial stamp
+ * beside a refusal would land nothing, thus the refusal carries every unknown path at one time and the
+ * author repairs them together.
+ */
+export function stampReferenceHashes(payload, snapshot) {
+    const missing = [];
+    const stamped = stampValue(payload, snapshot, missing);
+    if (missing.length === 0) {
+        return ok(stamped);
+    }
+    const unresolved = missing.map((pin) => ({
+        // The payload reaches the stamp before the parse, thus the object holds the fields of a reference
+        // as the author wrote them. The refusal names that object, and this assertion is the one place
+        // where the pre-parse shape enters the parsed reference type.
+        reference: pin.record,
+        reason: "artifact-missing",
+        detail: `no artifact at ${pin.path}`,
+    }));
+    return err({
+        reason: "unresolved-reference",
+        detail: `the pinned evidence holds no artifact at ${missing.map((pin) => pin.path).join(", ")}`,
+        unresolved,
+    });
+}
+/**
+ * Give one value with the stamped hash of each artifact reference removed.
+ *
+ * The snapshot owns the hash, thus a read that echoed one would give an agent a value to mistype. A binding
+ * still gives its path and its locator, which are what an agent authored and what it changes.
+ *
+ * The walk builds a copy on the changed path only. A branch that carries no pin comes back as the same
+ * reference. Thus the read costs the size of the pins, and never the size of the block.
+ */
+export function stripReferenceHashes(value) {
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = [];
+        for (const item of value) {
+            const stripped = stripReferenceHashes(item);
+            if (stripped !== item) {
+                changed = true;
+            }
+            next.push(stripped);
+        }
+        return changed ? next : value;
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    const pinned = holdsPin(record);
+    let changed = false;
+    const next = {};
+    for (const key of Object.keys(record)) {
+        if (pinned && key === "hash") {
+            changed = true;
+            continue;
+        }
+        const stripped = stripReferenceHashes(record[key]);
+        if (stripped !== record[key]) {
+            changed = true;
+        }
+        defineOwn(next, key, stripped);
+    }
+    return changed ? next : value;
+}

package/dist/report-model/structural-validation.d.ts

@@ -17,6 +17,9 @@ import { type ReportSnapshot } from "./reference-resolver.js";
  * value comes from a read of the artifact. An `assert` is the authored belief about that value, thus this
  * tier matches no assertion and a reference that carries one passes on its pin alone.
  *
+ * `columns` carries each column that the grammar of a chart block names. The walk collects them, thus a
+ * chart that plots an invented column refuses before it lands, wherever the snapshot can answer.
+ *
  * The answer is synchronous, because the snapshot is already in memory.
  */
-export declare function validateReferenceStructure(reference: Reference, snapshot: ReportSnapshot): Result<void, UnresolvedReference>;
+export declare function validateReferenceStructure(reference: Reference, snapshot: ReportSnapshot, columns?: readonly string[]): Result<void, UnresolvedReference>;

package/dist/report-model/structural-validation.js

@@ -8,7 +8,7 @@
  * value. As a result the costly read happens one time for each report version, and never for each edit.
  */
 import { err, ok } from "neverthrow";
-import { fileTypeHoldsNoCell, snapshotEntry } from "./reference-resolver.js";
+import { columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry } 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 };
@@ -33,6 +33,30 @@ function validatePin(reference, snapshot) {
     }
     return ok();
 }
+/**
+ * Match each column that a chart grammar names against the table that the block binds.
+ *
+ * The tier reads the snapshot alone, thus it answers from the two things that the snapshot holds. A table
+ * reference that declares a column subset answers on its own terms, because a name outside the subset
+ * addresses nothing. A snapshot entry that carries rows answers from those rows.
+ *
+ * A snapshot that pins identity alone holds no rows. Such a snapshot contradicts no name, thus the tier
+ * passes and the value tier settles the match over the artifact that it reads.
+ */
+function validateColumns(reference, snapshot, columns) {
+    const subset = reference.columns;
+    if (subset !== undefined) {
+        const outside = columns.filter((column) => !subset.includes(column));
+        if (outside.length > 0) {
+            return fail(reference, "locator-out-of-range", `the chart names column ${outside.join(", ")}, which the bound column subset leaves out`);
+        }
+    }
+    const absent = columnsHeldByNoRow(snapshotEntry(snapshot, reference.path)?.rows ?? [], columns);
+    if (absent.length > 0) {
+        return fail(reference, "locator-out-of-range", `the chart names column ${absent.join(", ")}, which the bound table does not hold`);
+    }
+    return ok();
+}
 /**
  * Validate one reference against the snapshot.
  *
@@ -40,12 +64,33 @@ function validatePin(reference, snapshot) {
  * value comes from a read of the artifact. An `assert` is the authored belief about that value, thus this
  * tier matches no assertion and a reference that carries one passes on its pin alone.
  *
+ * `columns` carries each column that the grammar of a chart block names. The walk collects them, thus a
+ * chart that plots an invented column refuses before it lands, wherever the snapshot can answer.
+ *
  * The answer is synchronous, because the snapshot is already in memory.
  */
-export function validateReferenceStructure(reference, snapshot) {
+export function validateReferenceStructure(reference, snapshot, columns) {
     switch (reference.kind) {
+        case "artifact-table": {
+            const pin = validatePin(reference, snapshot);
+            if (pin.isErr()) {
+                return pin;
+            }
+            // The bound is content: it decides which rows the table holds. Thus a bound column that the
+            // artifact does not hold refuses here, exactly as a grammar column of a chart does.
+            const bound = reference.rowBound;
+            if (bound !== undefined) {
+                const absent = columnsHeldByNoRow(snapshotEntry(snapshot, reference.path)?.rows ?? [], [bound.column]);
+                if (absent.length > 0) {
+                    return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the bound table does not hold`);
+                }
+            }
+            if (columns === undefined || columns.length === 0) {
+                return ok();
+            }
+            return validateColumns(reference, snapshot, columns);
+        }
         case "artifact-value":
-        case "artifact-table":
         case "artifact-file":
             return validatePin(reference, snapshot);
         case "derivation": {

package/dist/report-model/validate.d.ts

@@ -5,7 +5,7 @@
  * by construction, and a metric value slot admits one scalar reference only. Thus a schema parse failure
  * is the grammar rejection, and the validator does not re-implement it. The validator adds the three
  * checks that a schema cannot make: it makes sure that each block id occurs one time only, it resolves
- * each reference against the pinned evidence, and it warns about a free numeral in prose.
+ * each reference against the pinned evidence, and it warns about the prose of each block.
  */
 import type { UnresolvedReference } from "../contracts/report-reference.js";
 import { type AnyBlock, type CollectedReference, type ReportWarning } from "./block-walk.js";

package/dist/report-model/validate.js

@@ -5,7 +5,7 @@
  * by construction, and a metric value slot admits one scalar reference only. Thus a schema parse failure
  * is the grammar rejection, and the validator does not re-implement it. The validator adds the three
  * checks that a schema cannot make: it makes sure that each block id occurs one time only, it resolves
- * each reference against the pinned evidence, and it warns about a free numeral in prose.
+ * each reference against the pinned evidence, and it warns about the prose of each block.
  */
 import { ReportDocumentSchema } from "../contracts/report-blocks.js";
 import { allWithConcurrency } from "../lib/async-utils.js";

package/dist/report-render/asset-lookup.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The lookup of the source file of one staged page asset.
+ *
+ * A manifest entry (`assets.ts`) names a module specifier, and a caller that stages the assets beside a page
+ * needs the file on disk. The resolution reads the installation of the harness, thus the staged bytes are
+ * the bytes of the pinned version.
+ *
+ * The module sits beside the manifest, thus the preview tool and the fixture script read one lookup and
+ * neither one carries the module graph of the other.
+ */
+/**
+ * The absolute path of the source file of one manifest specifier.
+ *
+ * A package that publishes an `exports` map refuses a subpath that the map does not name, and a browser
+ * bundle beside the module entry is such a subpath. The fallback then reads the specifier as a path under
+ * each candidate `node_modules` directory of the resolution. Thus a bundle that the map hides still stages,
+ * and a specifier that names no file still fails with the resolution error of the package.
+ */
+export declare function resolvePageAssetFromInstallation(specifier: string): string;

package/dist/report-render/asset-lookup.js

@@ -0,0 +1,37 @@
+/**
+ * The lookup of the source file of one staged page asset.
+ *
+ * A manifest entry (`assets.ts`) names a module specifier, and a caller that stages the assets beside a page
+ * needs the file on disk. The resolution reads the installation of the harness, thus the staged bytes are
+ * the bytes of the pinned version.
+ *
+ * The module sits beside the manifest, thus the preview tool and the fixture script read one lookup and
+ * neither one carries the module graph of the other.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+/** The resolver of a package source. It reads the installation that holds this module. */
+const moduleResolver = createRequire(import.meta.url);
+/**
+ * The absolute path of the source file of one manifest specifier.
+ *
+ * A package that publishes an `exports` map refuses a subpath that the map does not name, and a browser
+ * bundle beside the module entry is such a subpath. The fallback then reads the specifier as a path under
+ * each candidate `node_modules` directory of the resolution. Thus a bundle that the map hides still stages,
+ * and a specifier that names no file still fails with the resolution error of the package.
+ */
+export function resolvePageAssetFromInstallation(specifier) {
+    try {
+        return moduleResolver.resolve(specifier);
+    }
+    catch (cause) {
+        for (const directory of moduleResolver.resolve.paths(specifier) ?? []) {
+            const candidate = join(directory, specifier);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        throw cause;
+    }
+}

package/dist/report-render/assets.d.ts

@@ -5,13 +5,25 @@
  * names the staged file and the module specifier of its source. The caller resolves each specifier against
  * its own installation, and it copies the bytes beside the page.
  *
+ * Each entry of the manifest names a file under `deps/`. Thus the shipped libraries and the shipped fonts
+ * sit in one directory of their own, and the files that the report produced keep the root of the assets
+ * directory. A reader of the directory then tells the two apart on sight, and the sweep of the stage governs
+ * the report-side files alone.
+ *
  * The module holds data alone. The renderer reads no file, thus the page stays a pure function of its
  * inputs.
  */
 /** The directory of the staged assets, relative to the page. */
 export declare const ASSETS_DIR = "assets";
 /**
- * One staged asset. `file` is the basename under the assets directory, and `specifier` is the module
+ * The directory of the shipped libraries and fonts, under the assets directory.
+ *
+ * The manifest, the skeleton, and the stage each spell the segment through this constant. Thus the tag of
+ * the page, the file that the stage writes, and the set that the sweep keeps cannot disagree.
+ */
+export declare const DEPS_DIR = "deps";
+/**
+ * One staged asset. `file` is the path under the assets directory, and `specifier` is the module
  * specifier of the source file inside the installed package.
  */
 export interface PageAsset {
@@ -20,8 +32,40 @@ export interface PageAsset {
 }
 /** The relative source of a staged asset. The page directory is self-contained, thus the source is `assets/<file>`. */
 export declare function assetSource(asset: PageAsset): string;
+/** The relative source of a staged file by its name. A page reference never spells the directory itself. */
+export declare function stagedSource(file: string): string;
+/**
+ * The staged name of the raw bytes of one table artifact: a hash head, then the basename of the path.
+ *
+ * The reader downloads the pinned file itself and never a re-serialization of it, thus the name must carry
+ * the identity of those bytes. The hash head makes two artifacts of one basename two staged files, and the
+ * basename keeps the downloaded file recognizable on the disk of the reader.
+ *
+ * The hash arrives as `algorithm:hex`, and neither the colon nor a path separator is safe in a file name.
+ * The head takes the hex alone, and the basename takes each unsafe run as one dash.
+ */
+export declare function tableSidecarName(hash: string, path: string): string;
+/**
+ * The staged name of the script of one derivation: a hash head, in the content-address style of a data
+ * asset.
+ *
+ * The chain line of the appendix links this name, and the stage writes the script text under it. Both read
+ * this one function, thus the link and the file cannot disagree. The head is the head that the chain line
+ * shows, thus a reader compares the shown hash against the file name by sight.
+ *
+ * The extension is `.py`, because a session derivation runs its script through the Python interpreter of the
+ * container.
+ */
+export declare function derivationScriptName(scriptHash: string): string;
 /** The chart runtime. The page-side bootstrap reads the `echarts` global that this file declares. */
 export declare const ECHARTS_ASSET: PageAsset;
+/**
+ * The grid runtime. The page-side bootstrap reads the `agGrid` global that this file declares.
+ *
+ * The entry names the browser bundle of the package. The package `exports` map publishes the module
+ * entries alone, thus this specifier resolves as a path under the installed package directory.
+ */
+export declare const AG_GRID_ASSET: PageAsset;
 /** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
 export declare const SANS_FONT_ASSET: PageAsset;
 /**

package/dist/report-render/assets.js

@@ -5,23 +5,81 @@
  * names the staged file and the module specifier of its source. The caller resolves each specifier against
  * its own installation, and it copies the bytes beside the page.
  *
+ * Each entry of the manifest names a file under `deps/`. Thus the shipped libraries and the shipped fonts
+ * sit in one directory of their own, and the files that the report produced keep the root of the assets
+ * directory. A reader of the directory then tells the two apart on sight, and the sweep of the stage governs
+ * the report-side files alone.
+ *
  * The module holds data alone. The renderer reads no file, thus the page stays a pure function of its
  * inputs.
  */
 /** The directory of the staged assets, relative to the page. */
 export const ASSETS_DIR = "assets";
+/**
+ * The directory of the shipped libraries and fonts, under the assets directory.
+ *
+ * The manifest, the skeleton, and the stage each spell the segment through this constant. Thus the tag of
+ * the page, the file that the stage writes, and the set that the sweep keeps cannot disagree.
+ */
+export const DEPS_DIR = "deps";
 /** The relative source of a staged asset. The page directory is self-contained, thus the source is `assets/<file>`. */
 export function assetSource(asset) {
     return `${ASSETS_DIR}/${asset.file}`;
 }
+/** The relative source of a staged file by its name. A page reference never spells the directory itself. */
+export function stagedSource(file) {
+    return `${ASSETS_DIR}/${file}`;
+}
+/** The count of hash characters in a staged name. A staged file carries enough of the hash to be unique. */
+const HASH_CHARS = 12;
+/**
+ * The staged name of the raw bytes of one table artifact: a hash head, then the basename of the path.
+ *
+ * The reader downloads the pinned file itself and never a re-serialization of it, thus the name must carry
+ * the identity of those bytes. The hash head makes two artifacts of one basename two staged files, and the
+ * basename keeps the downloaded file recognizable on the disk of the reader.
+ *
+ * The hash arrives as `algorithm:hex`, and neither the colon nor a path separator is safe in a file name.
+ * The head takes the hex alone, and the basename takes each unsafe run as one dash.
+ */
+export function tableSidecarName(hash, path) {
+    const hex = hash.slice(hash.lastIndexOf(":") + 1).replace(/[^a-z0-9]+/gi, "");
+    const base = path.slice(path.lastIndexOf("/") + 1).replace(/[^a-z0-9._-]+/gi, "-");
+    return `${hex.slice(0, HASH_CHARS)}-${base}`;
+}
+/**
+ * The staged name of the script of one derivation: a hash head, in the content-address style of a data
+ * asset.
+ *
+ * The chain line of the appendix links this name, and the stage writes the script text under it. Both read
+ * this one function, thus the link and the file cannot disagree. The head is the head that the chain line
+ * shows, thus a reader compares the shown hash against the file name by sight.
+ *
+ * The extension is `.py`, because a session derivation runs its script through the Python interpreter of the
+ * container.
+ */
+export function derivationScriptName(scriptHash) {
+    const hex = scriptHash.slice(scriptHash.lastIndexOf(":") + 1).replace(/[^a-z0-9]+/gi, "");
+    return `d-${hex.slice(0, HASH_CHARS)}.py`;
+}
 /** The chart runtime. The page-side bootstrap reads the `echarts` global that this file declares. */
 export const ECHARTS_ASSET = {
-    file: "echarts.min.js",
+    file: `${DEPS_DIR}/echarts.min.js`,
     specifier: "echarts/dist/echarts.min.js",
 };
+/**
+ * The grid runtime. The page-side bootstrap reads the `agGrid` global that this file declares.
+ *
+ * The entry names the browser bundle of the package. The package `exports` map publishes the module
+ * entries alone, thus this specifier resolves as a path under the installed package directory.
+ */
+export const AG_GRID_ASSET = {
+    file: `${DEPS_DIR}/ag-grid-community.min.js`,
+    specifier: "ag-grid-community/dist/ag-grid-community.min.js",
+};
 /** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
 export const SANS_FONT_ASSET = {
-    file: "space-grotesk-latin-wght-normal.woff2",
+    file: `${DEPS_DIR}/space-grotesk-latin-wght-normal.woff2`,
     specifier: "@fontsource-variable/space-grotesk/files/space-grotesk-latin-wght-normal.woff2",
 };
 /**
@@ -32,27 +90,28 @@ export const SANS_FONT_ASSET = {
  * and 700 for a metric value.
  */
 export const MONO_FONT_400_ASSET = {
-    file: "ibm-plex-mono-latin-400-normal.woff2",
+    file: `${DEPS_DIR}/ibm-plex-mono-latin-400-normal.woff2`,
     specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-400-normal.woff2",
 };
 /** The mono font at weight 500, for a tag and a stat-card label. */
 export const MONO_FONT_500_ASSET = {
-    file: "ibm-plex-mono-latin-500-normal.woff2",
+    file: `${DEPS_DIR}/ibm-plex-mono-latin-500-normal.woff2`,
     specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-500-normal.woff2",
 };
 /** The mono font at weight 600, for a table header, a section label, and the panel badge. */
 export const MONO_FONT_600_ASSET = {
-    file: "ibm-plex-mono-latin-600-normal.woff2",
+    file: `${DEPS_DIR}/ibm-plex-mono-latin-600-normal.woff2`,
     specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-600-normal.woff2",
 };
 /** The mono font at weight 700, for a metric value. */
 export const MONO_FONT_700_ASSET = {
-    file: "ibm-plex-mono-latin-700-normal.woff2",
+    file: `${DEPS_DIR}/ibm-plex-mono-latin-700-normal.woff2`,
     specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-700-normal.woff2",
 };
 /** Each asset that the caller stages beside the page. */
 export const PAGE_ASSETS = [
     ECHARTS_ASSET,
+    AG_GRID_ASSET,
     SANS_FONT_ASSET,
     MONO_FONT_400_ASSET,
     MONO_FONT_500_ASSET,

package/dist/report-render/chart-presets.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The preset expansion of the chart grammar.
+ *
+ * A preset is sugar over the composition. `expandPreset` gives the composition of one preset, thus the
+ * derivation reads one shape and the two paths cannot drift.
+ *
+ * Each default of a preset is a declared constant of this module, and a declared threshold pair replaces
+ * one. A guide line carries such a value, and a guide is never a plotted value. The expansion estimates
+ * nothing: the `km` preset plots the precomputed survival columns as they are, and it fits no curve.
+ *
+ * A preset can also carry a classification. The classification reads the plotted pair of one row against
+ * the same values that the guides carry, thus the color split lands on the drawn lines. It reads one row
+ * at a time, and it computes no aggregate.
+ *
+ * A preset declares its own transform on the channel that it transforms. Thus it reads the column of that
+ * channel and it drops an authored transform there, and no value takes the transform two times.
+ */
+import { type ChartChannel, type ChartComposition, type ChartEncoding, type ChartThresholds, type ChartType } from "../contracts/report-blocks.js";
+/** The four chart types that expand into a composition. */
+export declare const PRESET_CHART_TYPES: readonly ["volcano", "manhattan", "ma", "km"];
+/** One chart type that expands into a composition. */
+export type PresetChartType = (typeof PRESET_CHART_TYPES)[number];
+/** The default p-value threshold of a volcano. The guide line sits at the transformed value of it. */
+export declare const VOLCANO_P_THRESHOLD = 0.05;
+/** The default effect threshold of a volcano. One guide line sits at each side of zero. */
+export declare const VOLCANO_EFFECT_THRESHOLD = 1;
+/** The genome-wide significance threshold of a Manhattan plot. */
+export declare const MANHATTAN_P_THRESHOLD = 5e-8;
+/** The baseline of an MA plot. A point above it rose, and a point below it fell. */
+export declare const MA_BASELINE = 0;
+/** The semantic axis titles of one preset. A preset whose axis carries no fixed quantity states none. */
+export interface PresetAxisTitles {
+    readonly x?: string;
+    readonly y?: string;
+}
+/** One category of a preset classification: the name that a legend reads, and whether it states no finding. */
+export interface PresetCategory {
+    readonly name: string;
+    readonly muted: boolean;
+}
+/**
+ * The classification rule as plain data: the kind of the split, and the two cuts that it reads.
+ *
+ * `categoryOf` is a function, thus it reaches no page. A chart that reads the shared payload builds its
+ * series in the browser, and this shape is what such a build takes. The two forms answer alike, and the
+ * shared test vector holds them together.
+ *
+ * `cut` sits on the plotted y value, which is the transformed p-value, and `effect` sits on the plotted x
+ * value. The volcano rule gives the place of the category in `categories`: 0 for the down side, 1 for the
+ * up side, and 2 for the null category.
+ */
+export interface PresetRule {
+    readonly kind: "volcano";
+    readonly cut: number;
+    readonly effect: number;
+}
+/**
+ * The per-row classification of one preset.
+ *
+ * `categoryOf` reads the plotted pair of one row and nothing else. Thus it computes no aggregate, and it
+ * compares each point against the same numbers that the guide lines carry. The color split then lands on
+ * the drawn lines. A row that gives no pair belongs to no category, and its point drops.
+ */
+export interface PresetClassification {
+    readonly categories: readonly PresetCategory[];
+    readonly categoryOf: (x: number | null, y: number | null) => string | undefined;
+    readonly rule: PresetRule;
+}
+/** The expansion of one preset: the composition, and the classification where the preset draws one. */
+export interface PresetExpansion {
+    readonly composition: ChartComposition;
+    readonly classification?: PresetClassification;
+}
+/** True when the chart type expands into a composition. */
+export declare function isPresetChartType(chartType: ChartType): chartType is PresetChartType;
+/**
+ * Expand one preset into a composition.
+ *
+ * `x` and `y` are the two channels that every preset demands. The caller resolves them from the encoding
+ * and refuses an absent one, thus this function is total and it needs no failure channel. `encoding`
+ * supplies the optional `group` and `label` channels.
+ *
+ * `thresholds` carries the pair that the author declared. The volcano is the one preset that reads it, and
+ * an absent pair gives the two constants of this module.
+ */
+export declare function expandPreset(preset: PresetChartType, x: ChartChannel, y: ChartChannel, encoding: ChartEncoding, thresholds?: ChartThresholds): PresetExpansion;
+/**
+ * The semantic axis titles that one preset states.
+ *
+ * A preset knows its own quantities, thus it names them in words. A volcano plots a log2 effect against the
+ * transformed p, and a manhattan plots a genome position against the same transformed p. The `ma` and the
+ * `km` presets name nothing, because neither axis of them carries a fixed quantity.
+ *
+ * A channel that carries an authored transform plots a derived quantity, thus the semantic title would
+ * state the wrong one. Such a channel takes no title, and the derived name of the renderer states the true
+ * quantity. The y channel of a volcano and of a manhattan takes the transform of the preset itself, thus
+ * its title is exact.
+ *
+ * The titles rank under a declared column label. Thus they ride beside the composition and never inside its
+ * `axes` field, where an agent title sits and where they would outrank the label.
+ */
+export declare function presetAxisTitles(preset: PresetChartType, x: ChartChannel): PresetAxisTitles;