@inflexa-ai/harness 0.24.0 → 0.25.0

package/dist/input-scan/enrich.js

@@ -0,0 +1,227 @@
+/**
+ * Per-shape header readout — the one part of the scan that needs the sandbox.
+ *
+ * A bounded prefix read compared against a magic table runs on the host; a DECODER
+ * over user-supplied bytes does not. zlib, HDF5, and PDF parsers in the long-lived
+ * multi-tenant harness process are exactly the exposure the ephemeral sandbox exists
+ * to contain, so every decode below runs there.
+ *
+ * Cost is O(shapes), not O(files): shapes are observed from names and sizes alone, so
+ * enrichment decodes a bounded number of members per shape — roughly four files for
+ * the 3513-file tree that motivated this capability. One exec covers every shape, so
+ * even the round trip does not scale with the tree.
+ *
+ * Nothing ships in `sandbox-base` for this: the decoder is a Python program passed on
+ * the command line through the existing `runSandboxExec` path, so the capability
+ * releases on the harness's own path rather than on the image's manual one.
+ */
+import { runSandboxExec } from "../tools/workspace/run-exec.js";
+/** Members decoded per shape. One is enough to characterise a set whose names already match. */
+export const MEMBERS_DECODED_PER_SHAPE = 1;
+/** Wall-clock bound on the whole readout exec — it reads prefixes, nothing more. */
+const ENRICH_TIMEOUT_SECONDS = 120;
+/**
+ * The decoder, as a self-contained program. Reads a bounded prefix of each path and
+ * prints one JSON object per line: `{"path": …, "fields": {…}}` or `{"path": …,
+ * "unavailable": …}`. It never reads a file in full except a size-capped document,
+ * whose page count lives in a trailer no prefix can reach.
+ */
+const DECODER = String.raw `
+import sys, json, zlib, io, os, csv
+
+PREFIX = 262144
+MEMBER = 1048576
+DOC_MAX = 33554432
+
+def prefix_bytes(path, n=PREFIX):
+    with open(path, "rb") as fh:
+        return fh.read(n)
+
+def gunzip_prefix(raw):
+    d = zlib.decompressobj(16 + zlib.MAX_WBITS)
+    try:
+        return d.decompress(raw, MEMBER)
+    except zlib.error:
+        return b""
+
+def sniff_delimiter(line):
+    counts = {d: line.count(d) for d in [",", "\t", ";", "|"]}
+    best = max(counts, key=lambda d: counts[d])
+    return best if counts[best] > 0 else None
+
+def text_fields(text):
+    lines = [l for l in text.splitlines() if l.strip() != ""]
+    if not lines:
+        return {}
+    head = lines[0]
+    if head.startswith("##fileformat=VCF") or head.startswith("##"):
+        fields = {}
+        for line in lines[:200]:
+            if line.startswith("##fileformat="):
+                fields["fileformat"] = line.split("=", 1)[1][:40]
+            elif line.startswith("##reference="):
+                fields["reference"] = line.split("=", 1)[1][:80]
+            elif line.startswith("#CHROM"):
+                cols = line.split("\t")
+                samples = cols[9:]
+                fields["sampleCount"] = len(samples)
+                fields["samples"] = ", ".join(samples[:5])[:120]
+                break
+        fields["metaLines"] = sum(1 for l in lines if l.startswith("##"))
+        return fields
+    if head.startswith(">"):
+        return {"firstRecord": head[1:80], "recordsInPrefix": sum(1 for l in lines if l.startswith(">"))}
+    if head.startswith("@") and len(lines) > 1 and not head.startswith("@HD"):
+        return {"firstRecord": head[1:80], "readLength": len(lines[1])}
+    if head.startswith("@HD") or head.startswith("@SQ"):
+        return {"referenceSequences": sum(1 for l in lines if l.startswith("@SQ")), "readGroups": sum(1 for l in lines if l.startswith("@RG"))}
+    delim = sniff_delimiter(head)
+    if delim:
+        columns = next(csv.reader([head], delimiter=delim))
+        return {
+            "delimiter": {",": "comma", "\t": "tab", ";": "semicolon", "|": "pipe"}[delim],
+            "columnCount": len(columns),
+            "columns": ", ".join(c.strip()[:24] for c in columns[:12])[:200],
+            "linesInPrefix": len(lines),
+        }
+    return {"firstLine": head[:120]}
+
+def hdf5_fields(path):
+    try:
+        import h5py
+    except Exception:
+        return {"unavailable": "h5py not installed in this sandbox"}
+    try:
+        with h5py.File(path, "r") as f:
+            keys = list(f.keys())[:20]
+            out = {"rootKeys": ", ".join(keys)[:200], "rootKeyCount": len(f.keys())}
+            for probe in ("X", "obs", "var", "matrix"):
+                if probe in f:
+                    node = f[probe]
+                    shape = getattr(node, "shape", None)
+                    if shape:
+                        out[probe + "Shape"] = "x".join(str(d) for d in shape)
+            return out
+    except Exception as exc:
+        return {"unavailable": "hdf5 open failed: " + str(exc)[:80]}
+
+def pdf_fields(path):
+    if os.path.getsize(path) > DOC_MAX:
+        return {"unavailable": "document too large to page-count within the scan's bound"}
+    try:
+        from pypdf import PdfReader
+        reader = PdfReader(path)
+        text = (reader.pages[0].extract_text() or "")[:200] if reader.pages else ""
+        return {"pageCount": len(reader.pages), "firstPageText": " ".join(text.split())[:200]}
+    except Exception as exc:
+        return {"unavailable": "pdf read failed: " + str(exc)[:80]}
+
+def docx_fields(path):
+    if os.path.getsize(path) > DOC_MAX:
+        return {"unavailable": "document too large to inspect within the scan's bound"}
+    try:
+        import zipfile, re
+        with zipfile.ZipFile(path) as z:
+            names = z.namelist()
+            out = {"parts": len(names)}
+            if "docProps/app.xml" in names:
+                app = z.read("docProps/app.xml").decode("utf8", "replace")
+                for tag in ("Pages", "Words"):
+                    m = re.search("<" + tag + ">(\\d+)</" + tag + ">", app)
+                    if m:
+                        out[tag.lower()] = int(m.group(1))
+            return out
+    except Exception as exc:
+        return {"unavailable": "docx read failed: " + str(exc)[:80]}
+
+def describe(path):
+    ext = path.lower()
+    if ext.endswith(".pdf"):
+        return pdf_fields(path)
+    if ext.endswith(".docx"):
+        return docx_fields(path)
+    if ext.endswith((".h5", ".hdf5", ".h5ad", ".loom")):
+        return hdf5_fields(path)
+    raw = prefix_bytes(path)
+    if raw[:2] == b"\x1f\x8b":
+        wrapper = "bgzip" if len(raw) > 13 and raw[3] & 4 and raw[12:14] == b"BC" else "gzip"
+        inner = gunzip_prefix(raw)
+        if inner[:4] == b"BAM\x01":
+            l_text = int.from_bytes(inner[4:8], "little")
+            header = inner[8:8 + min(l_text, 65536)].decode("utf8", "replace")
+            fields = text_fields(header)
+            fields["wrapper"] = wrapper
+            fields["container"] = "bam"
+            return fields
+        if inner[:4] == b"BCF\x02" or inner[:3] == b"BCF":
+            return {"wrapper": wrapper, "container": "bcf"}
+        fields = text_fields(inner.decode("utf8", "replace"))
+        fields["wrapper"] = wrapper
+        return fields
+    if raw[:8] == b"\x89HDF\r\n\x1a\n":
+        return hdf5_fields(path)
+    return text_fields(raw.decode("utf8", "replace"))
+
+for path in sys.argv[1:]:
+    try:
+        fields = describe(path)
+    except Exception as exc:
+        fields = {"unavailable": type(exc).__name__ + ": " + str(exc)[:80]}
+    note = fields.pop("unavailable", None)
+    record = {"path": path, "fields": fields}
+    if note:
+        record["unavailable"] = note
+    sys.stdout.write(json.dumps(record) + "\n")
+`;
+/**
+ * Decode one member per shape and attach the readout.
+ *
+ * A shape whose decode failed keeps its `unavailable` note rather than losing the
+ * shape: the readout is enrichment, and a manifest without it still carries every
+ * structural observation the agent's grouping rests on.
+ */
+export async function enrichShapes(args) {
+    const { shapes, mountRoot } = args;
+    const targets = shapes.map((shape) => ({ shape, paths: shape.examplePaths.slice(0, MEMBERS_DECODED_PER_SHAPE) })).filter((t) => t.paths.length > 0);
+    if (targets.length === 0)
+        return [...shapes];
+    const absolute = new Map();
+    for (const { shape, paths } of targets) {
+        for (const path of paths)
+            absolute.set(`${mountRoot}/${path}`, shape.id);
+    }
+    const result = await runSandboxExec({
+        sandboxClient: args.sandboxClient,
+        sandbox: args.sandbox,
+        execId: args.execId,
+        command: ["python3", "-c", DECODER, ...absolute.keys()],
+        timeoutSeconds: ENRICH_TIMEOUT_SECONDS,
+        deadlineMs: args.deadlineMs,
+        emit: args.emit,
+    });
+    const readouts = new Map();
+    for (const line of result.stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const shapeId = parsed.path ? absolute.get(parsed.path) : undefined;
+        if (!shapeId || !parsed.path)
+            continue;
+        readouts.set(shapeId, {
+            path: parsed.path.startsWith(`${mountRoot}/`) ? parsed.path.slice(mountRoot.length + 1) : parsed.path,
+            fields: parsed.fields ?? {},
+            ...(parsed.unavailable ? { unavailable: parsed.unavailable } : {}),
+        });
+    }
+    return shapes.map((shape) => {
+        const header = readouts.get(shape.id);
+        return header ? { ...shape, header } : shape;
+    });
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Format detection over a bounded byte prefix.
+ *
+ * A prefix read compared against a magic-byte table is NOT a decode: no parser
+ * runs over the bytes, so this belongs in the harness process. Every actual
+ * decoder — zlib, HDF5, PDF — stays in the sandbox (see `enrich.ts`), which is
+ * the exposure the sandbox exists to contain.
+ *
+ * Compression wrappers are reported ALONGSIDE the inner format, never in place of
+ * it: `.vcf.gz` is a VCF, and a shape observed on the wrapper would present
+ * unrelated data as mechanically alike. The wrapper comes from the bytes; the inner
+ * format of a wrapped file comes from its extension chain, which the sandbox
+ * header readout then confirms against the decompressed stream.
+ *
+ * The recognised list is a floor, not a closed set. An unrecognised format reports
+ * `unknown` with its extension chain preserved, and still joins a shape — shape
+ * observation depends on names and sizes, which are always available.
+ */
+/** Bytes read per file for detection. Enough for every magic below plus a text sniff line. */
+export declare const MAGIC_PREFIX_BYTES = 512;
+/** The extension chain of a basename, outermost last. `sample.vcf.gz` → `["vcf", "gz"]`. */
+export declare function extensionChain(fileName: string): string[];
+/** The extension chain with any compression wrappers stripped from the tail. */
+export declare function innerExtensions(extensions: readonly string[]): string[];
+export interface DetectedFormat {
+    readonly format: string;
+    readonly wrapper?: string;
+}
+/**
+ * Identify a file's format from a bounded prefix of its bytes, falling back to the
+ * extension chain — which is all a wrapped file can offer the host, since reading
+ * the inner format's magic would mean decompressing.
+ *
+ * A path segment ending `.zarr` names a chunked store whose members are individually
+ * meaningless, so every file beneath one reports `zarr`.
+ */
+export declare function detectFormat(args: {
+    readonly path: string;
+    readonly extensions: readonly string[];
+    readonly prefix: Buffer | null;
+}): DetectedFormat;

package/dist/input-scan/formats.js

@@ -0,0 +1,279 @@
+/**
+ * Format detection over a bounded byte prefix.
+ *
+ * A prefix read compared against a magic-byte table is NOT a decode: no parser
+ * runs over the bytes, so this belongs in the harness process. Every actual
+ * decoder — zlib, HDF5, PDF — stays in the sandbox (see `enrich.ts`), which is
+ * the exposure the sandbox exists to contain.
+ *
+ * Compression wrappers are reported ALONGSIDE the inner format, never in place of
+ * it: `.vcf.gz` is a VCF, and a shape observed on the wrapper would present
+ * unrelated data as mechanically alike. The wrapper comes from the bytes; the inner
+ * format of a wrapped file comes from its extension chain, which the sandbox
+ * header readout then confirms against the decompressed stream.
+ *
+ * The recognised list is a floor, not a closed set. An unrecognised format reports
+ * `unknown` with its extension chain preserved, and still joins a shape — shape
+ * observation depends on names and sizes, which are always available.
+ */
+/** Bytes read per file for detection. Enough for every magic below plus a text sniff line. */
+export const MAGIC_PREFIX_BYTES = 512;
+/** Compression wrappers, keyed by the extension that names them. */
+const WRAPPER_EXTENSIONS = new Set(["gz", "bgz", "bgzf", "zst", "zstd", "bz2", "xz"]);
+/**
+ * Extension → format. This table IS the platform's format floor (see the
+ * input-scan-manifest spec); an extension absent from it detects as `unknown`
+ * unless its bytes are recognised.
+ */
+const EXTENSION_FORMATS = {
+    // Variants
+    vcf: "vcf",
+    bcf: "bcf",
+    tbi: "tabix-index",
+    csi: "csi-index",
+    // Alignments
+    sam: "sam",
+    bam: "bam",
+    cram: "cram",
+    bai: "bam-index",
+    crai: "cram-index",
+    // Sequence
+    fa: "fasta",
+    fasta: "fasta",
+    fna: "fasta",
+    faa: "fasta",
+    fq: "fastq",
+    fastq: "fastq",
+    // Intervals and annotation
+    bed: "bed",
+    gff: "gff",
+    gff3: "gff3",
+    gtf: "gtf",
+    wig: "wig",
+    bw: "bigwig",
+    bigwig: "bigwig",
+    bb: "bigbed",
+    bigbed: "bigbed",
+    chain: "chain",
+    // Matrices and containers
+    h5: "hdf5",
+    hdf5: "hdf5",
+    h5ad: "h5ad",
+    loom: "loom",
+    mtx: "matrix-market",
+    zarr: "zarr",
+    rds: "rds",
+    rdata: "rdata",
+    // Tabular
+    csv: "csv",
+    tsv: "tsv",
+    txt: "text",
+    tab: "tsv",
+    parquet: "parquet",
+    xlsx: "excel",
+    xls: "excel",
+    // Genotype
+    bim: "plink-bim",
+    fam: "plink-fam",
+    pgen: "plink-pgen",
+    pvar: "plink-pvar",
+    psam: "plink-psam",
+    // Chemistry and structure
+    sdf: "sdf",
+    mol: "mol",
+    mol2: "mol2",
+    smi: "smiles",
+    smiles: "smiles",
+    pdb: "pdb",
+    cif: "mmcif",
+    mmcif: "mmcif",
+    // Mass spectrometry
+    mzml: "mzml",
+    mzxml: "mzxml",
+    mzid: "mzidentml",
+    mgf: "mgf",
+    // Arrays
+    idat: "idat",
+    cel: "cel",
+    // Imaging
+    dcm: "dicom",
+    nii: "nifti",
+    tif: "tiff",
+    tiff: "tiff",
+    // Documents and config
+    pdf: "pdf",
+    docx: "docx",
+    md: "markdown",
+    markdown: "markdown",
+    json: "json",
+    yaml: "yaml",
+    yml: "yaml",
+    log: "text",
+};
+/**
+ * `.bed` is PLINK's binary genotype table AND the interval format, and only the
+ * bytes tell them apart (PLINK writes a three-byte magic).
+ */
+const PLINK_BED_MAGIC = Buffer.from([0x6c, 0x1b, 0x01]);
+function startsWith(buf, magic) {
+    const bytes = Buffer.isBuffer(magic) ? magic : Buffer.from(magic);
+    return buf.length >= bytes.length && buf.subarray(0, bytes.length).equals(bytes);
+}
+function startsWithText(buf, text) {
+    return startsWith(buf, Buffer.from(text, "latin1"));
+}
+/**
+ * A gzip member whose FEXTRA carries the `BC` subfield is BGZF — the block-gzip
+ * form every indexed bioinformatics file uses. Reported distinctly because it is
+ * what makes a random-access decode of one member possible.
+ */
+function gzipWrapper(buf) {
+    if (buf.length < 12)
+        return "gzip";
+    const flags = buf[3];
+    const hasExtra = (flags & 0x04) !== 0;
+    if (!hasExtra)
+        return "gzip";
+    return buf[12] === 0x42 && buf[13] === 0x43 ? "bgzip" : "gzip";
+}
+/** The wrapper a prefix's magic bytes name, or `undefined` for uncompressed content. */
+function detectWrapper(buf) {
+    if (startsWith(buf, [0x1f, 0x8b]))
+        return gzipWrapper(buf);
+    if (startsWith(buf, [0x28, 0xb5, 0x2f, 0xfd]))
+        return "zstd";
+    if (startsWithText(buf, "BZh"))
+        return "bzip2";
+    if (startsWith(buf, [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00]))
+        return "xz";
+    return undefined;
+}
+/** Format identified from binary magic alone, independent of any extension. */
+function binaryFormat(buf) {
+    if (startsWith(buf, [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return "hdf5";
+    if (startsWithText(buf, "PAR1"))
+        return "parquet";
+    if (startsWithText(buf, "CRAM"))
+        return "cram";
+    if (startsWithText(buf, "%PDF-"))
+        return "pdf";
+    if (startsWith(buf, [0x26, 0xfc, 0x8f, 0x88]))
+        return "bigwig";
+    if (startsWith(buf, [0xeb, 0xf2, 0x89, 0x87]))
+        return "bigbed";
+    if (startsWithText(buf, "RDX2") || startsWithText(buf, "RDX3"))
+        return "rds";
+    if (startsWithText(buf, "II*\0") || startsWithText(buf, "MM\0*"))
+        return "tiff";
+    if (startsWith(buf, PLINK_BED_MAGIC))
+        return "plink-bed";
+    if (buf.length >= 132 && buf.subarray(128, 132).toString("latin1") === "DICM")
+        return "dicom";
+    if (startsWithText(buf, "IDAT"))
+        return "idat";
+    return undefined;
+}
+/** Format identified from a text prefix — the header line most text formats declare. */
+function textFormat(buf) {
+    const head = buf.toString("utf8", 0, Math.min(buf.length, 256));
+    if (head.startsWith("##fileformat=VCF"))
+        return "vcf";
+    if (head.startsWith("##gff-version 3"))
+        return "gff3";
+    if (head.startsWith("##gff-version"))
+        return "gff";
+    if (head.startsWith("@HD\t") || head.startsWith("@SQ\t"))
+        return "sam";
+    if (head.startsWith("%%MatrixMarket"))
+        return "matrix-market";
+    if (head.startsWith("BEGIN IONS"))
+        return "mgf";
+    if (head.startsWith("@<TRIPOS>"))
+        return "mol2";
+    if (head.startsWith("chain "))
+        return "chain";
+    if (head.startsWith("HEADER    ") || head.startsWith("ATOM  "))
+        return "pdb";
+    if (head.startsWith("data_"))
+        return "mmcif";
+    if (head.startsWith("[CEL]"))
+        return "cel";
+    if (head.startsWith("track ") || head.startsWith("fixedStep") || head.startsWith("variableStep"))
+        return "wig";
+    if (/^<\?xml/.test(head)) {
+        if (head.includes("<indexedmzML") || head.includes("<mzML"))
+            return "mzml";
+        if (head.includes("<mzXML"))
+            return "mzxml";
+        if (head.includes("MzIdentML"))
+            return "mzidentml";
+        return "xml";
+    }
+    if (head.startsWith(">"))
+        return "fasta";
+    if (head.startsWith("@"))
+        return "fastq";
+    return undefined;
+}
+/** The extension chain of a basename, outermost last. `sample.vcf.gz` → `["vcf", "gz"]`. */
+export function extensionChain(fileName) {
+    const dot = fileName.indexOf(".");
+    // A leading dot names a hidden file, not an extension.
+    if (dot <= 0)
+        return [];
+    return fileName
+        .slice(dot + 1)
+        .split(".")
+        .filter((part) => part.length > 0 && part.length <= 12)
+        .map((part) => part.toLowerCase());
+}
+/** The extension chain with any compression wrappers stripped from the tail. */
+export function innerExtensions(extensions) {
+    const inner = [...extensions];
+    while (inner.length > 0 && WRAPPER_EXTENSIONS.has(inner[inner.length - 1]))
+        inner.pop();
+    return inner;
+}
+/**
+ * Identify a file's format from a bounded prefix of its bytes, falling back to the
+ * extension chain — which is all a wrapped file can offer the host, since reading
+ * the inner format's magic would mean decompressing.
+ *
+ * A path segment ending `.zarr` names a chunked store whose members are individually
+ * meaningless, so every file beneath one reports `zarr`.
+ */
+export function detectFormat(args) {
+    const { path, extensions, prefix } = args;
+    if (path.split("/").some((segment) => segment.toLowerCase().endsWith(".zarr")))
+        return { format: "zarr" };
+    const wrapper = prefix ? detectWrapper(prefix) : undefined;
+    const inner = innerExtensions(extensions);
+    const innerExt = inner[inner.length - 1];
+    const byExtension = innerExt ? EXTENSION_FORMATS[innerExt] : undefined;
+    if (wrapper) {
+        // The inner bytes are behind a decoder; the extension chain is the only inner
+        // evidence available here, and the sandbox header readout confirms it.
+        return byExtension ? { format: byExtension, wrapper } : { format: "unknown", wrapper };
+    }
+    if (prefix && prefix.length > 0) {
+        const binary = binaryFormat(prefix);
+        // A container's specialisation is an extension fact (`.h5ad` and `.loom` are
+        // both HDF5), so a more specific extension reading wins over the container magic.
+        if (binary === "hdf5" && byExtension && byExtension !== "hdf5")
+            return { format: byExtension };
+        if (binary)
+            return { format: binary };
+        const text = textFormat(prefix);
+        // `@` opens both FASTQ and SAM headers, and `>` opens FASTA; where the extension
+        // is explicit it is the better evidence for WHICH text format this is.
+        if (text && byExtension && text !== byExtension) {
+            const ambiguous = text === "fastq" || text === "fasta" || text === "xml";
+            if (ambiguous)
+                return { format: byExtension };
+        }
+        if (text)
+            return { format: text };
+    }
+    return { format: byExtension ?? "unknown" };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Input scan — the deterministic pass that replaced per-file agent profiling.
+ *
+ * The scan observes; the profiler agent groups. Nothing exported here names a kind
+ * or an axis (see the input-scan-manifest spec).
+ */
+export { MAGIC_PREFIX_BYTES, detectFormat, extensionChain, innerExtensions, type DetectedFormat } from "./formats.js";
+export { MAX_SAMPLE_VALUES, MAX_SHAPES, nameStem, observeShapes, tokenizeStem, type ObservedShapes } from "./shapes.js";
+export { MAX_SCANNED_FILES, buildManifest, renderInputScanManifest, scanInputTree, type ScanInputTreeArgs } from "./scan.js";
+export { MEMBERS_DECODED_PER_SHAPE, enrichShapes, type EnrichShapesArgs } from "./enrich.js";
+export { computeCoverage, type ProfileCoverage } from "./coverage.js";
+export type { FileShape, FormatCount, HeaderReadout, InputScan, InputScanManifest, PositionCooccurrence, ScannedFile, ShapeValueOverlap, UnstructuredEntry, UnstructuredFiles, VariablePosition, } from "./types.js";

package/dist/input-scan/index.js

@@ -0,0 +1,11 @@
+/**
+ * Input scan — the deterministic pass that replaced per-file agent profiling.
+ *
+ * The scan observes; the profiler agent groups. Nothing exported here names a kind
+ * or an axis (see the input-scan-manifest spec).
+ */
+export { MAGIC_PREFIX_BYTES, detectFormat, extensionChain, innerExtensions } from "./formats.js";
+export { MAX_SAMPLE_VALUES, MAX_SHAPES, nameStem, observeShapes, tokenizeStem } from "./shapes.js";
+export { MAX_SCANNED_FILES, buildManifest, renderInputScanManifest, scanInputTree } from "./scan.js";
+export { MEMBERS_DECODED_PER_SHAPE, enrichShapes } from "./enrich.js";
+export { computeCoverage } from "./coverage.js";

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

@@ -0,0 +1,50 @@
+/**
+ * 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 type { AgentSession } from "../auth/types.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { InputScan, InputScanManifest, ScannedFile } from "./types.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 declare const MAX_SCANNED_FILES = 100000;
+export interface ScanInputTreeArgs {
+    readonly session: AgentSession;
+    readonly fs: WorkspaceFilesystem;
+    /** Directory to scan, relative to the analysis root (e.g. `data/inputs`). */
+    readonly root: string;
+    /** Walk ceiling; defaults to {@link MAX_SCANNED_FILES}. */
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+/** Assemble a manifest from an already-walked file set. Pure — the seam of the unit tests. */
+export declare function buildManifest(root: string, files: readonly ScannedFile[], truncated: boolean, limit?: number): InputScan;
+/** Walk a staged input tree and observe its shapes. No model, no container. */
+export declare function scanInputTree(args: ScanInputTreeArgs): Promise<InputScan>;
+/**
+ * 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 declare function renderInputScanManifest(manifest: InputScanManifest): string;