@inflexa-ai/harness 0.24.0 → 0.26.0

package/dist/input-scan/scan.js

@@ -0,0 +1,182 @@
+/**
+ * The input scan — one deterministic pass over a staged input tree.
+ *
+ * Runs in the harness process over the workspace read seam, which is
+ * sandbox-independent: the walk touches names and metadata, and format detection
+ * compares a bounded byte prefix against a table. Neither is a decode, so neither
+ * needs a container. Only the per-shape header readout (`enrich.ts`) runs a decoder,
+ * and it runs in the sandbox.
+ *
+ * The scan is the SOLE enumeration pass. Before it, the profiler agent discovered
+ * structure by issuing one command per input file, so its cost scaled with file
+ * count and its step budget did not.
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { MAGIC_PREFIX_BYTES, detectFormat, extensionChain } from "./formats.js";
+import { observeShapes } from "./shapes.js";
+/**
+ * Files walked before the scan reports truncation instead of completing.
+ *
+ * Header decode is O(shapes), but the walk and its per-file prefix read are O(files),
+ * and that arm needs a stated ceiling rather than an implicit one. 100k files is ~30s
+ * of stat-and-prefix work against a 20-minute profile deadline, and two orders of
+ * magnitude above the largest tree the platform has seen (3513). Past it the scan
+ * stops and SAYS it stopped: a silently sampled manifest would describe a fraction of
+ * the tree while reading as a description of all of it, which is the failure mode this
+ * capability exists to remove.
+ */
+export const MAX_SCANNED_FILES = 100_000;
+/** Walk the tree breadth-first, reading a bounded prefix of each file for format detection. */
+async function walk(args) {
+    const { session, fs, root, signal } = args;
+    const limit = args.limit ?? MAX_SCANNED_FILES;
+    const files = [];
+    const queue = [root];
+    let truncated = false;
+    while (queue.length > 0) {
+        signal?.throwIfAborted();
+        const dir = queue.shift();
+        const listing = unwrapOrThrow(await fs.list({ session, path: dir }));
+        // A directory that vanished mid-walk, or one the seam refuses, is not a scan
+        // failure — the tree is being described, not validated.
+        if (listing.kind !== "ok")
+            continue;
+        for (const entry of listing.entries) {
+            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+            if (entry.type === "directory") {
+                queue.push(path);
+                continue;
+            }
+            if (files.length >= limit) {
+                truncated = true;
+                return { files, truncated };
+            }
+            const extensions = extensionChain(entry.name);
+            const read = unwrapOrThrow(await fs.readBytes({ session, path, length: MAGIC_PREFIX_BYTES }));
+            const prefix = read.kind === "ok" ? read.bytes : null;
+            const { format, wrapper } = detectFormat({ path, extensions, prefix });
+            files.push({
+                path,
+                size: entry.size ?? 0,
+                extensions,
+                format,
+                ...(wrapper ? { wrapper } : {}),
+            });
+        }
+    }
+    return { files, truncated };
+}
+function formatCensus(files) {
+    const counts = new Map();
+    for (const file of files)
+        counts.set(file.format, (counts.get(file.format) ?? 0) + 1);
+    return [...counts.entries()].map(([format, count]) => ({ format, count })).sort((a, b) => b.count - a.count || a.format.localeCompare(b.format, "en"));
+}
+/** Assemble a manifest from an already-walked file set. Pure — the seam of the unit tests. */
+export function buildManifest(root, files, truncated, limit = MAX_SCANNED_FILES) {
+    const observed = observeShapes(files);
+    const manifest = {
+        root,
+        fileCount: files.length,
+        totalBytes: files.reduce((sum, f) => sum + f.size, 0),
+        truncated,
+        ...(truncated ? { scanLimit: limit } : {}),
+        shapesTruncated: observed.shapesTruncated,
+        formats: formatCensus(files),
+        shapes: observed.shapes,
+        valueOverlaps: observed.valueOverlaps,
+        unstructured: observed.unstructured,
+    };
+    return { files, manifest, positionValues: observed.positionValues };
+}
+/** Walk a staged input tree and observe its shapes. No model, no container. */
+export async function scanInputTree(args) {
+    const limit = args.limit ?? MAX_SCANNED_FILES;
+    const { files, truncated } = await walk(args);
+    return buildManifest(args.root, files, truncated, limit);
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+/**
+ * Render a manifest for a briefing or a tool result.
+ *
+ * Bounded by construction — every list it draws from is already capped — so a tree of
+ * three thousand files costs the same context as a tree of thirty. The wording states
+ * observations only: it never calls a shape a kind, and it says outright that the
+ * grouping decision is the reader's.
+ */
+export function renderInputScanManifest(manifest) {
+    const lines = [];
+    lines.push(`Input scan of ${manifest.root} — ${manifest.fileCount} files, ${formatBytes(manifest.totalBytes)}.`);
+    if (manifest.truncated) {
+        lines.push(`INCOMPLETE: the walk stopped at its ${manifest.scanLimit ?? MAX_SCANNED_FILES}-file ceiling, so this describes part of the tree.`);
+    }
+    lines.push(`Formats: ${manifest.formats.map((f) => `${f.format} (${f.count})`).join(", ") || "none"}`);
+    lines.push("");
+    lines.push("These are OBSERVATIONS of filename structure, not a grouping of the dataset.");
+    lines.push("A shape is a set of files whose names differ only at the marked positions; deciding");
+    lines.push("what is one kind of data, and what the varying positions mean, is your judgement.");
+    if (manifest.shapes.length > 0) {
+        lines.push("");
+        lines.push(`Shapes (${manifest.shapes.length}${manifest.shapesTruncated ? ", capped — the remainder is in the aggregate below" : ""}):`);
+        for (const shape of manifest.shapes) {
+            const location = shape.directory ? `${shape.directory}/` : "";
+            const wrapper = shape.wrapper ? `, ${shape.wrapper}-compressed` : "";
+            lines.push(`- ${shape.id}: ${shape.fileCount} files at ${location}${shape.pattern} (${shape.format}${wrapper}, ${formatBytes(shape.totalBytes)})`);
+            for (const position of shape.variablePositions) {
+                const prefix = position.prefix ? ` after "${position.prefix}"` : "";
+                const shown = position.sampleValues.join(", ");
+                const more = position.distinctValues > position.sampleValues.length ? ", …" : "";
+                lines.push(`  - position <${position.index}>${prefix}: ${position.distinctValues} distinct values — ${shown}${more}`);
+            }
+            for (const pair of shape.cooccurrence) {
+                const crossing = pair.observedPairs === pair.possiblePairs ? "fully crossed" : `partially crossed (${pair.possiblePairs} possible)`;
+                lines.push(`  - positions <${pair.positions[0]}>×<${pair.positions[1]}>: ${pair.observedPairs} observed combinations, ${crossing}`);
+            }
+            if (shape.header) {
+                const fields = Object.entries(shape.header.fields)
+                    .map(([key, value]) => `${key}=${value}`)
+                    .join(", ");
+                lines.push(`  - header (${shape.header.path}): ${fields || shape.header.unavailable || "no fields read"}`);
+            }
+            else {
+                lines.push(`  - example: ${shape.examplePaths[0] ?? "—"}`);
+            }
+        }
+    }
+    if (manifest.valueOverlaps.length > 0) {
+        lines.push("");
+        lines.push("Value overlap between shapes (evidence, NOT an assertion that they share an axis):");
+        for (const overlap of manifest.valueOverlaps) {
+            const gaps = [];
+            if (overlap.onlyInFirst > 0)
+                gaps.push(`${overlap.onlyInFirst} only in ${overlap.shapes[0]} (${overlap.onlyInFirstSample.join(", ")})`);
+            if (overlap.onlyInSecond > 0)
+                gaps.push(`${overlap.onlyInSecond} only in ${overlap.shapes[1]} (${overlap.onlyInSecondSample.join(", ")})`);
+            const gapText = gaps.length > 0 ? `; ${gaps.join("; ")}` : "; no gaps";
+            lines.push(`- ${overlap.shapes[0]}<${overlap.positions[0]}> vs ${overlap.shapes[1]}<${overlap.positions[1]}>: ` +
+                `${overlap.sharedValues} shared values${gapText}`);
+        }
+    }
+    if (manifest.unstructured.count > 0) {
+        lines.push("");
+        lines.push(`Files sharing no name structure with any other (${manifest.unstructured.count}, ${formatBytes(manifest.unstructured.totalBytes)}):`);
+        for (const entry of manifest.unstructured.sample) {
+            lines.push(`- ${entry.path} (${entry.format}, ${formatBytes(entry.size)})`);
+        }
+        if (manifest.unstructured.count > manifest.unstructured.sample.length) {
+            lines.push(`- … ${manifest.unstructured.count - manifest.unstructured.sample.length} more not listed`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/input-scan/shapes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shape observation — pure functions over filenames and sizes, no I/O.
+ *
+ * A shape is a mechanical fact: these filenames differ only here. Establishing it
+ * needs nothing but names, sizes, and the format already detected, which is why
+ * shapes are observed BEFORE any decode and why header enrichment costs O(shapes)
+ * rather than O(files).
+ *
+ * Grouping proceeds in two passes. The first masks digit runs, so `PATIENT_001` and
+ * `PATIENT_002` land together while `tumor_001` and `normal_001` do not. The second
+ * merges groups that differ in exactly one alphabetic position, which is what makes
+ * `tumor`/`normal` one shape with a categorical position rather than two shapes an
+ * agent has to notice are related. A file whose structure matches no other survives
+ * both passes alone and is reported in the aggregate, never as a shape of one.
+ */
+import type { FileShape, ScannedFile, ShapeValueOverlap, UnstructuredFiles } from "./types.js";
+/** Shapes reported before the tail is folded into the aggregate. */
+export declare const MAX_SHAPES = 30;
+/** Values sampled per variable position. The sample is the agent's decision material. */
+export declare const MAX_SAMPLE_VALUES = 20;
+type AtomKind = "alpha" | "digit" | "delim";
+interface Atom {
+    readonly kind: AtomKind;
+    readonly value: string;
+}
+/**
+ * Split a filename stem into runs of letters, runs of digits, and the delimiters
+ * between them. Splitting INSIDE a token is what makes `PT001_D0_rep1` three
+ * positions rather than three opaque tokens — the nested design is only visible
+ * once `PT` and `001` are separate.
+ */
+export declare function tokenizeStem(stem: string): readonly Atom[];
+/** The name stem — the basename with its extension chain removed. */
+export declare function nameStem(fileName: string): string;
+export interface ObservedShapes {
+    readonly shapes: readonly FileShape[];
+    readonly unstructured: UnstructuredFiles;
+    readonly valueOverlaps: readonly ShapeValueOverlap[];
+    /** Complete per-position value sets, keyed by shape id — the manifest carries only a sample. */
+    readonly positionValues: ReadonlyMap<string, readonly (readonly string[])[]>;
+    /** True when the shape list was capped and the remainder folded into the aggregate. */
+    readonly shapesTruncated: boolean;
+}
+/** Observe the shapes of a scanned file set. Pure — no I/O, no container, no model. */
+export declare function observeShapes(files: readonly ScannedFile[]): ObservedShapes;
+export {};

package/dist/input-scan/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Input-scan vocabulary.
+ *
+ * The scan reports what is OBSERVABLE about a staged input tree; it never decides
+ * how the tree is grouped (see the input-scan-manifest spec). That separation is
+ * carried by the vocabulary itself: a shape is "these filenames differ only here",
+ * a kind is "these files are the same sort of thing", and only the profiler agent
+ * can establish the second. Nothing here is named `kinds` or `axes`, and no type
+ * here is assignable to the profiler's output — a manifest an agent could copy
+ * into its submission would make its central judgement invisible.
+ */
+/** One file the walk found. `path` is relative to the analysis root. */
+export interface ScannedFile {
+    readonly path: string;
+    readonly size: number;
+    /** Trailing extension components, outermost last: `sample.vcf.gz` → `["vcf", "gz"]`. */
+    readonly extensions: readonly string[];
+    /** Format identified from magic bytes, falling back to the extension chain, else `"unknown"`. */
+    readonly format: string;
+    /** Compression wrapper reported ALONGSIDE the inner format, never in place of it. */
+    readonly wrapper?: string;
+}
+/**
+ * A filename position whose token differs across a shape's members.
+ *
+ * `sampleValues` is normative, not decoration: a count alone cannot distinguish an
+ * identifier (`0001`…`1171`) from a categorical label (`tumor`/`normal`) from a shard
+ * index (`chr1`…`chr22`), and those readings imply entirely different kinds.
+ */
+export interface VariablePosition {
+    /** Token index within the shape's name pattern — the `<n>` placeholder it fills. */
+    readonly index: number;
+    /** Literal text immediately preceding the token, when any (`PT` in `PT001`). */
+    readonly prefix?: string;
+    readonly distinctValues: number;
+    /** Bounded sample of the values observed at this position. */
+    readonly sampleValues: readonly string[];
+}
+/**
+ * How two variable positions vary together. A fully-crossed pair is a nested design
+ * (every subject × every timepoint); a partially-crossed one is not, and the
+ * difference is design evidence a flat file count destroys.
+ */
+export interface PositionCooccurrence {
+    readonly positions: readonly [number, number];
+    /** Distinct value pairs observed. */
+    readonly observedPairs: number;
+    /** Pairs the two value sets could form. `observedPairs === possiblePairs` is a full crossing. */
+    readonly possiblePairs: number;
+}
+/** Header fields read from a bounded prefix of one member of a shape. */
+export interface HeaderReadout {
+    /** The member the readout came from. */
+    readonly path: string;
+    /** Decoder-reported fields, flat and bounded (`delimiter`, `columns`, `sampleCount`, …). */
+    readonly fields: Readonly<Record<string, string | number | boolean>>;
+    /** Why no readout is present, when the decode did not produce one. */
+    readonly unavailable?: string;
+}
+/**
+ * A set of files that are mechanically indistinguishable by name structure, format,
+ * and location. A shape is an observation, never a grouping of the dataset: the
+ * agent may split one shape into several kinds, cover several shapes with one kind,
+ * or ignore the shape entirely.
+ */
+export interface FileShape {
+    /** Stable within one manifest (`shape-1`, `shape-2`, …) so overlaps can name shapes. */
+    readonly id: string;
+    /** Directory the members share, relative to the analysis root. */
+    readonly directory: string;
+    /** Name pattern with each variable position rendered as `<n>`. */
+    readonly pattern: string;
+    readonly format: string;
+    readonly wrapper?: string;
+    readonly extensions: readonly string[];
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly variablePositions: readonly VariablePosition[];
+    readonly cooccurrence: readonly PositionCooccurrence[];
+    /** Bounded sample of member paths. */
+    readonly examplePaths: readonly string[];
+    /** Present once sandbox enrichment has run for this shape. */
+    readonly header?: HeaderReadout;
+}
+/**
+ * Value-set overlap between two shapes' variable positions, reported WITH its gaps.
+ *
+ * Correspondence across shapes is heuristic — it depends on stripping shape-specific
+ * text before comparing, and near-miss namings defeat it. Reported as evidence it is
+ * useful; asserted as a shared axis it is a guess a consumer cannot tell was guessed.
+ */
+export interface ShapeValueOverlap {
+    readonly shapes: readonly [string, string];
+    readonly positions: readonly [number, number];
+    readonly sharedValues: number;
+    /** Values present in the first shape and absent from the second. */
+    readonly onlyInFirst: number;
+    readonly onlyInSecond: number;
+    /** Bounded samples of the two gaps, so a near-complete correspondence names its misses. */
+    readonly onlyInFirstSample: readonly string[];
+    readonly onlyInSecondSample: readonly string[];
+}
+/** One member of the no-shared-structure aggregate. */
+export interface UnstructuredEntry {
+    readonly path: string;
+    readonly size: number;
+    readonly format: string;
+}
+/**
+ * Files whose name structure matches no other file, in aggregate.
+ *
+ * Never one shape per file: a tree of arbitrarily named files would otherwise produce
+ * a shape count proportional to the file count, which is the unbounded output this
+ * capability exists to prevent. Whether these are notable singletons worth prose or
+ * an unclassified remainder is the agent's determination.
+ */
+export interface UnstructuredFiles {
+    readonly count: number;
+    readonly totalBytes: number;
+    /**
+     * Bounded sample covering distinct formats first, then the largest files. A
+     * size-ordered sample would bury the metadata sheet, the README, and the paper —
+     * one file each — under whatever large files failed to group.
+     */
+    readonly sample: readonly UnstructuredEntry[];
+}
+/** How many files carry each detected format, across the whole scanned tree. */
+export interface FormatCount {
+    readonly format: string;
+    readonly count: number;
+}
+/**
+ * The agent-facing manifest: bounded by construction, so injecting it into a briefing
+ * or returning it from `scan_inputs` costs a fixed amount of context whatever the tree
+ * size. The complete per-file list lives on {@link InputScan}, host-side.
+ */
+export interface InputScanManifest {
+    /** Path scanned, relative to the analysis root. */
+    readonly root: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    /**
+     * True when the walk hit its file ceiling and stopped. The shapes below then
+     * describe a prefix of the tree, not all of it — stated rather than silently
+     * sampled.
+     */
+    readonly truncated: boolean;
+    /** The ceiling that bound, when `truncated`. */
+    readonly scanLimit?: number;
+    /** True when the shape list itself was capped; the remainder is folded into `unstructured`. */
+    readonly shapesTruncated: boolean;
+    readonly formats: readonly FormatCount[];
+    readonly shapes: readonly FileShape[];
+    readonly valueOverlaps: readonly ShapeValueOverlap[];
+    readonly unstructured: UnstructuredFiles;
+}
+/**
+ * The scan's full result. `files` is the complete enumeration — it stays host-side and
+ * backs coverage and the index projection; `manifest` is the bounded projection the
+ * agent reads.
+ */
+export interface InputScan {
+    readonly files: readonly ScannedFile[];
+    readonly manifest: InputScanManifest;
+    /**
+     * Per shape, the COMPLETE value set of each variable position, keyed by shape id.
+     * Bounded output belongs to the manifest; the entity tier of the index needs every
+     * value, and re-deriving them from filenames downstream would duplicate the
+     * tokenisation.
+     */
+    readonly positionValues: ReadonlyMap<string, readonly (readonly string[])[]>;
+}

package/dist/input-scan/types.js

@@ -0,0 +1,12 @@
+/**
+ * Input-scan vocabulary.
+ *
+ * The scan reports what is OBSERVABLE about a staged input tree; it never decides
+ * how the tree is grouped (see the input-scan-manifest spec). That separation is
+ * carried by the vocabulary itself: a shape is "these filenames differ only here",
+ * a kind is "these files are the same sort of thing", and only the profiler agent
+ * can establish the second. Nothing here is named `kinds` or `axes`, and no type
+ * here is assignable to the profiler's output — a manifest an agent could copy
+ * into its submission would make its central judgement invisible.
+ */
+export {};

package/dist/lib/page-capture.d.ts

@@ -2,8 +2,15 @@
  * The one page capture over the Chrome sidecar.
  *
  * A capture navigates to a page URL, collects the console errors and the failed requests, waits for the
- * readiness signal of the page, and gives back a base64 screenshot. Two tools capture a report page: the
- * preview snapshot of the old report path and the eyes tool of a report session. Both read this module.
+ * readiness signal of the page, and gives back base64 screenshots. The eyes tool of a report session reads
+ * this module.
+ *
+ * A short page captures as one full-page shot. A tall page captures as consecutive vertical slices, because
+ * one tall picture dies twice on the provider path: a picture past the hard dimension cap rejects the whole
+ * request, and a legal tall picture downscales to about 1568 pixels on the long side, which compresses the
+ * text past legibility. A slice of about two window heights survives both. The slice budget bounds what one
+ * look costs, and a page past the budget truncates with the captured and the total pixels on the coverage,
+ * thus the truncation is never silent.
  *
  * The readiness contract is the reason for one shared body. The renderer emits the event name and the
  * sentinel name, and `report-render/page.ts` owns both constants together with the two budgets. This module
@@ -23,20 +30,41 @@ export interface FailedRequest {
     url: string;
     reason: string;
 }
-/** The picture and the faults of one page capture. */
+/** One picture of a capture: the base64 bytes, and the document rows that a slice holds. */
+export interface CapturedShot {
+    readonly base64: string;
+    /** The vertical document range of a slice, in CSS pixels. Absent on a whole-document or window picture. */
+    readonly range?: {
+        readonly fromY: number;
+        readonly toY: number;
+    };
+}
+/**
+ * What the pictures hold together. `full` is one shot of the whole document. `tiled` is consecutive vertical
+ * slices in document order; `capturedPx` is the height the slices cover and `totalPx` is the document height,
+ * thus `capturedPx < totalPx` says that the slice budget ran out and the tail of the page is absent. `viewport`
+ * appears when a screenshot threw and the retry at the window passed, thus the one picture shows the top
+ * window alone and a section below the fold is absent from it.
+ */
+export type CaptureCoverage = {
+    readonly kind: "full";
+} | {
+    readonly kind: "tiled";
+    readonly capturedPx: number;
+    readonly totalPx: number;
+} | {
+    readonly kind: "viewport";
+};
+/** The pictures and the faults of one page capture. */
 export interface PageCapture {
-    screenshotBase64: string;
-    /**
-     * What the picture holds. `full` is the whole document, and it is the shape of a capture that passed at
-     * the first attempt. `viewport` appears when the full-page screenshot threw and the retry at the window
-     * passed, thus the picture shows the top window alone and a section below the fold is absent from it.
-     */
-    coverage: "full" | "viewport";
+    /** The pictures in document order: one shot under `full` and `viewport`, the slices under `tiled`. */
+    screenshots: CapturedShot[];
+    coverage: CaptureCoverage;
     consoleErrors: string[];
     failedRequests: FailedRequest[];
 }
 /**
- * The capture seam. It navigates to a page URL, and it gives back the screenshot and the faults. The seam
+ * The capture seam. It navigates to a page URL, and it gives back the screenshots and the faults. The seam
  * speaks the throw protocol, because the chrome connection does. A test injects a seam that reads no
  * browser, thus a tool orchestration runs with no chrome sidecar.
  */
@@ -49,11 +77,12 @@ export interface CaptureOptions {
     readonly waitMs?: number;
 }
 /**
- * Capture one page: the screenshot, the console errors, and the failed requests.
+ * Capture one page: the screenshots, the console errors, and the failed requests.
  *
- * The picture holds the whole document, and not the window alone. Thus a caller can judge a section that a
- * reader reaches by a scroll. A refused full-page bitmap degrades to the window, and the coverage of the
- * result names which of the two pictures arrived.
+ * The pictures hold the document, and not the window alone. Thus a caller can judge a section that a reader
+ * reaches by a scroll. A short page arrives as one full-page shot, and a tall page arrives as consecutive
+ * slices in document order. A refused bitmap degrades to the window, and the coverage of the result names
+ * what the pictures hold.
  *
  * The readiness wait is best-effort. A page that never signals still captures at the readiness budget, thus
  * a broken page gives a picture that shows what broke.

package/dist/lib/page-capture.js

@@ -2,8 +2,15 @@
  * The one page capture over the Chrome sidecar.
  *
  * A capture navigates to a page URL, collects the console errors and the failed requests, waits for the
- * readiness signal of the page, and gives back a base64 screenshot. Two tools capture a report page: the
- * preview snapshot of the old report path and the eyes tool of a report session. Both read this module.
+ * readiness signal of the page, and gives back base64 screenshots. The eyes tool of a report session reads
+ * this module.
+ *
+ * A short page captures as one full-page shot. A tall page captures as consecutive vertical slices, because
+ * one tall picture dies twice on the provider path: a picture past the hard dimension cap rejects the whole
+ * request, and a legal tall picture downscales to about 1568 pixels on the long side, which compresses the
+ * text past legibility. A slice of about two window heights survives both. The slice budget bounds what one
+ * look costs, and a page past the budget truncates with the captured and the total pixels on the coverage,
+ * thus the truncation is never silent.
  *
  * The readiness contract is the reason for one shared body. The renderer emits the event name and the
  * sentinel name, and `report-render/page.ts` owns both constants together with the two budgets. This module
@@ -29,6 +36,23 @@ const SELECTOR_TIMEOUT_MS = 5_000;
  */
 const VIEWPORT_WIDTH = 1440;
 const VIEWPORT_HEIGHT = 900;
+/**
+ * The height of one capture slice, in CSS pixels, and the bound of a single-shot page.
+ *
+ * The provider downscales every picture to about 1568 pixels on the long side before the model reads it. Two
+ * window heights survive that downscale with readable text, and a taller picture reaches the model compressed
+ * past that. Thus a page at this height or under captures as one full-page shot, and a taller page captures
+ * as slices of this height.
+ */
+const TILE_HEIGHT_PX = VIEWPORT_HEIGHT * 2;
+/**
+ * The most slices of one capture.
+ *
+ * Each slice is one picture on the tool result, and the budget bounds what one look costs the context. A page
+ * taller than the budget covers truncates, and the coverage carries the captured and the total pixels, thus
+ * the truncation is never silent.
+ */
+const MAX_TILES = 6;
 /**
  * The body of the readiness wait, in the browser context. The sentinel arm resolves a page that dispatched
  * the event before this wait registered, thus a plain listener never blocks forever. The timer arm bounds a
@@ -57,37 +81,72 @@ function waitForThemeReady(sentinel, event, timeout) {
 function toBase64(shot) {
     return typeof shot === "string" ? shot : Buffer.from(shot).toString("base64");
 }
+/** The body of the height measure, in the browser context. */
+function measureScrollHeight() {
+    return document.documentElement.scrollHeight;
+}
 /**
- * Take the picture of one settled page, at the whole document or at the window alone.
+ * Measure the document height, in CSS pixels. A page that refuses the measure reads as a short one, thus the
+ * capture takes the one full-page shot and the refusal costs no look.
+ */
+async function measureTotalHeight(page) {
+    const measured = await page.evaluate(measureScrollHeight).catch(() => undefined);
+    return typeof measured === "number" && Number.isFinite(measured) ? measured : 0;
+}
+/**
+ * Capture the slices of one tall page, in document order. Each slice clips {@link TILE_HEIGHT_PX} rows at the
+ * reader width, and the last slice ends at the document height or at the budget, whichever comes first.
+ */
+async function captureTiles(page, totalPx) {
+    const tileCount = Math.min(Math.ceil(totalPx / TILE_HEIGHT_PX), MAX_TILES);
+    const screenshots = [];
+    for (let index = 0; index < tileCount; index++) {
+        const fromY = index * TILE_HEIGHT_PX;
+        const toY = Math.min(fromY + TILE_HEIGHT_PX, totalPx);
+        const clip = { x: 0, y: fromY, width: VIEWPORT_WIDTH, height: toY - fromY };
+        screenshots.push({ base64: toBase64(await page.screenshot({ encoding: "base64", clip })), range: { fromY, toY } });
+    }
+    const capturedPx = Math.min(tileCount * TILE_HEIGHT_PX, totalPx);
+    return { screenshots, coverage: { kind: "tiled", capturedPx, totalPx } };
+}
+/**
+ * Take the pictures of one settled page.
+ *
+ * A page at the single-shot bound or under gives one full-page shot. A taller page gives consecutive slices,
+ * because the provider path compresses or rejects one tall picture; the module comment carries the account.
  *
- * The compositor can refuse a full-page bitmap of a tall page while the bitmap of the window is fine. A
- * degraded picture beats a dead look, thus a refused full page retries one time at the window. A second throw
- * names a broken browser and not a tall page, thus it propagates to the caller.
+ * The compositor can refuse a bitmap of either shape while the bitmap of the window is fine. A degraded
+ * picture beats a dead look, thus a refusal retries one time at the window. A second throw names a broken
+ * browser and not a tall page, thus it propagates to the caller.
  */
-async function captureShot(page) {
+async function captureShots(page) {
+    const totalPx = await measureTotalHeight(page);
     try {
-        return { screenshotBase64: toBase64(await page.screenshot({ encoding: "base64", fullPage: true })), coverage: "full" };
+        if (totalPx > TILE_HEIGHT_PX)
+            return await captureTiles(page, totalPx);
+        return { screenshots: [{ base64: toBase64(await page.screenshot({ encoding: "base64", fullPage: true })) }], coverage: { kind: "full" } };
     }
-    catch (refusedFullPage) {
+    catch (refused) {
         try {
-            return { screenshotBase64: toBase64(await page.screenshot({ encoding: "base64" })), coverage: "viewport" };
+            return { screenshots: [{ base64: toBase64(await page.screenshot({ encoding: "base64" })) }], coverage: { kind: "viewport" } };
         }
         catch (refusedViewport) {
             // The two refusals together are the account of a dead look, and the caller reports the second one
             // alone. Thus the first one rides as the cause, and no reader of that report loses half of it.
             if (refusedViewport instanceof Error && refusedViewport.cause === undefined) {
-                refusedViewport.cause = refusedFullPage;
+                refusedViewport.cause = refused;
             }
             throw refusedViewport;
         }
     }
 }
 /**
- * Capture one page: the screenshot, the console errors, and the failed requests.
+ * Capture one page: the screenshots, the console errors, and the failed requests.
  *
- * The picture holds the whole document, and not the window alone. Thus a caller can judge a section that a
- * reader reaches by a scroll. A refused full-page bitmap degrades to the window, and the coverage of the
- * result names which of the two pictures arrived.
+ * The pictures hold the document, and not the window alone. Thus a caller can judge a section that a reader
+ * reaches by a scroll. A short page arrives as one full-page shot, and a tall page arrives as consecutive
+ * slices in document order. A refused bitmap degrades to the window, and the coverage of the result names
+ * what the pictures hold.
  *
  * The readiness wait is best-effort. A page that never signals still captures at the readiness budget, thus
  * a broken page gives a picture that shows what broke.
@@ -124,12 +183,12 @@ export function capturePage(chrome, url, options = {}) {
             const settle = options.waitMs;
             await new Promise((resolve) => setTimeout(resolve, settle));
         }
-        // The picture must show the whole document at the layout that a reader gets. Thus a defect below the
+        // The pictures must show the whole document at the layout that a reader gets. Thus a defect below the
         // fold is visible, and a question about content that never appeared has an answer.
-        const shot = await captureShot(page);
+        const shots = await captureShots(page);
         return {
-            screenshotBase64: shot.screenshotBase64,
-            coverage: shot.coverage,
+            screenshots: shots.screenshots,
+            coverage: shots.coverage,
             consoleErrors,
             failedRequests,
         };