@inflexa-ai/harness 0.28.0 → 0.29.0

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

@@ -0,0 +1,127 @@
+/**
+ * The menu — the bounded projection of a detected-set scan that the profiler agent
+ * authors against.
+ *
+ * It is the briefing's replacement for an enumeration of input paths: a tree of three
+ * thousand files costs the same context as a tree of thirty, because every list it draws
+ * from is capped and the set list itself is capped again here. A menu past its bound
+ * SAYS so — an elided tail is a fact the agent can act on, and a silent truncation is
+ * the failure this projection exists to prevent.
+ *
+ * Nothing here names a group or a dimension. Slot correspondence across sets is reported
+ * as measured overlap with its gaps, never as a shared dimension: whether two sets' id
+ * slots are the same thing is the agent's determination, recorded as a slot observation.
+ */
+import type { DetectedSet, DetectedSets, LeftoverFiles, QuarantineSummary } from "./set-types.js";
+import type { HeaderReadout } from "./types.js";
+/**
+ * Sets the menu lists before the tail folds into a counted line.
+ *
+ * Forty is far past any tree that groups: a scan producing more has told the agent
+ * everything a longer list would, and the aggregate says how much was left out.
+ */
+export declare const MAX_MENU_SETS = 40;
+/** Slot pairs reported, ordered by how much they overlap. */
+export declare const MAX_CORRESPONDENCES = 20;
+/** Values named per side of an overlap, so a near-complete correspondence names its misses. */
+export declare const MAX_CORRESPONDENCE_SAMPLE = 5;
+/**
+ * Members listed in full rather than by one example.
+ *
+ * A set this small is a handful of distinct artifacts, and `memberAnnotations` are keyed
+ * by path — an agent shown one example of five cannot write per-member prose for the
+ * other four. Past the bound the example plus the template is the whole of what a listing
+ * would add, at a cost that grows with the tree.
+ */
+export declare const MAX_FULLY_LISTED_SET_MEMBERS = 10;
+/** Slots crossed in one co-occurrence report. Past this the cross product says nothing a reader can hold. */
+export declare const MAX_CROSSED_SLOTS = 3;
+/**
+ * How a set's slots vary TOGETHER.
+ *
+ * Per-slot cardinalities describe the margins; a set of 8 subjects × 3 timepoints could be
+ * a full 24-member crossing or 8 members each at one timepoint, and the two are different
+ * experimental designs. The margins alone cannot tell them apart.
+ */
+export interface SetCrossing {
+    readonly setId: string;
+    readonly slotIds: readonly string[];
+    readonly observedCombinations: number;
+    /** The full cross product, or `null` when it is past counting. */
+    readonly possibleCombinations: number | null;
+}
+/**
+ * Measured overlap between two sets' slots, with its gaps.
+ *
+ * Evidence, not a claim. Two id slots drawing on the same values is what makes a shared
+ * dimension plausible; the values present in one and absent from the other are what make
+ * it checkable.
+ */
+export interface SlotCorrespondence {
+    readonly sets: readonly [string, string];
+    readonly slots: readonly [string, string];
+    readonly shared: number;
+    readonly onlyInFirst: number;
+    readonly onlyInSecond: number;
+    readonly sharedSample: readonly string[];
+    readonly onlyInFirstSample: readonly string[];
+    readonly onlyInSecondSample: readonly string[];
+}
+/** The tail the menu did not list, in aggregate. */
+export interface UnlistedSets {
+    readonly sets: number;
+    readonly members: number;
+    readonly files: number;
+    readonly totalBytes: number;
+}
+export interface SetMenu {
+    readonly fileCount: number;
+    readonly keptFileCount: number;
+    /** The addressable entries. An operation may name one of these ids and no other. */
+    readonly sets: readonly DetectedSet[];
+    readonly unlisted: UnlistedSets;
+    readonly correspondences: readonly SlotCorrespondence[];
+    /** How each multi-slot set's slots vary together. Empty for single-slot sets. */
+    readonly crossings: readonly SetCrossing[];
+    readonly quarantine: QuarantineSummary;
+    readonly leftovers: LeftoverFiles;
+    /** Header readouts keyed by path — one member per set, plus every leftover. */
+    readonly headers: ReadonlyMap<string, HeaderReadout>;
+    /**
+     * True when the walk stopped at its file ceiling. Every count below then describes a
+     * prefix of the tree — carried on the menu because the agent's grouping, the persisted
+     * census, and the orientation all read as complete otherwise.
+     */
+    readonly truncated: boolean;
+    /** Leftovers whose header readout was elided by the readout budget. */
+    readonly readoutsElided: number;
+}
+/**
+ * Slot overlap across the listed sets, strongest first.
+ *
+ * Computed from the complete value sets the scan keeps host-side — a bounded sample
+ * could not tell a full correspondence from a partial one, which is the whole content of
+ * this observation.
+ */
+export declare function buildCorrespondences(detected: DetectedSets, sets: readonly DetectedSet[]): SlotCorrespondence[];
+/**
+ * How the slots of one set vary together, from the per-member values the scan keeps
+ * host-side. A bounded sample could not distinguish a full crossing from a partial one,
+ * which is the whole content of the observation.
+ */
+export declare function buildCrossings(detected: DetectedSets, sets: readonly DetectedSet[]): SetCrossing[];
+export interface BuildSetMenuOptions {
+    readonly headers?: ReadonlyMap<string, HeaderReadout>;
+    /** The walk stopped at its ceiling; see {@link SetMenu.truncated}. */
+    readonly truncated?: boolean;
+    readonly readoutsElided?: number;
+}
+/** Project a scan into the bounded menu the agent authors against. */
+export declare function buildSetMenu(detected: DetectedSets, options?: BuildSetMenuOptions): SetMenu;
+/**
+ * Render the menu for a briefing or a tool result.
+ *
+ * The wording states observations only: it never calls a set a group, and it says
+ * outright that the grouping decision belongs to the reader.
+ */
+export declare function renderSetMenu(menu: SetMenu, root: string): string;

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

@@ -0,0 +1,17 @@
+/**
+ * Stage 0 — junk and partial artifacts leave before structure is observed.
+ *
+ * A partial-download twin sitting beside its completed file has the completed file's
+ * stem, so template mining absorbs it into the set and the set's member count then
+ * counts a file that holds nothing. The exclusion has to happen first, and it has to
+ * be reported: a wrongly quarantined file that no one can see is worse than the junk.
+ */
+import type { QuarantineReason, QuarantineSummary } from "./set-types.js";
+import type { ScannedFile } from "./types.js";
+/** The rule a path trips, or `undefined` when it trips none. */
+export declare function quarantineReason(path: string): QuarantineReason | undefined;
+export interface QuarantineResult {
+    readonly kept: readonly ScannedFile[];
+    readonly summary: QuarantineSummary;
+}
+export declare function quarantine(files: readonly ScannedFile[]): QuarantineResult;

package/dist/input-scan/quarantine.js

@@ -0,0 +1,69 @@
+/**
+ * Stage 0 — junk and partial artifacts leave before structure is observed.
+ *
+ * A partial-download twin sitting beside its completed file has the completed file's
+ * stem, so template mining absorbs it into the set and the set's member count then
+ * counts a file that holds nothing. The exclusion has to happen first, and it has to
+ * be reported: a wrongly quarantined file that no one can see is worse than the junk.
+ */
+import { MAX_QUARANTINE_SAMPLE } from "./tuning.js";
+const EXACT_JUNK_NAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+const NAME_RULES = [
+    { pattern: /^\._/, reason: "os-junk" },
+    { pattern: /^~\$/, reason: "editor-temp" },
+    { pattern: /~$/, reason: "editor-temp" },
+    { pattern: /^\.~lock\..*#$/, reason: "editor-temp" },
+    { pattern: /\.swp$/, reason: "editor-temp" },
+    { pattern: /\.part$/, reason: "partial-download" },
+    { pattern: /\.filepart$/, reason: "partial-download" },
+    { pattern: /\.crdownload$/, reason: "partial-download" },
+    { pattern: /\.download$/, reason: "partial-download" },
+    { pattern: /\.tmp$/, reason: "atomic-write-temp" },
+    { pattern: /^\.nfs/, reason: "atomic-write-temp" },
+    { pattern: /\.tmp-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/, reason: "atomic-write-temp" },
+    { pattern: /\.tmp-[0-9a-fA-F]{8,}$/, reason: "atomic-write-temp" },
+];
+const SEGMENT_RULES = [
+    { pattern: /^__MACOSX$/, reason: "os-junk" },
+    { pattern: /^\.Trash-/, reason: "os-junk" },
+];
+/** The rule a path trips, or `undefined` when it trips none. */
+export function quarantineReason(path) {
+    const segments = path.split("/");
+    const name = segments[segments.length - 1];
+    if (EXACT_JUNK_NAMES.has(name))
+        return "os-junk";
+    for (const rule of NAME_RULES)
+        if (rule.pattern.test(name))
+            return rule.reason;
+    for (const segment of segments)
+        for (const rule of SEGMENT_RULES)
+            if (rule.pattern.test(segment))
+                return rule.reason;
+    return undefined;
+}
+export function quarantine(files) {
+    const kept = [];
+    const excluded = [];
+    for (const file of files) {
+        const reason = quarantineReason(file.path);
+        if (reason)
+            excluded.push({ file, reason });
+        else
+            kept.push(file);
+    }
+    const counts = new Map();
+    for (const entry of excluded)
+        counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
+    return {
+        kept,
+        summary: {
+            count: excluded.length,
+            totalBytes: excluded.reduce((total, entry) => total + entry.file.size, 0),
+            reasons: [...counts.entries()]
+                .map(([reason, count]) => ({ reason, count }))
+                .sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason, "en")),
+            sample: excluded.slice(0, MAX_QUARANTINE_SAMPLE).map((entry) => entry.file.path),
+        },
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Which files a header readout should open.
+ *
+ * Members of a set are alike by construction — that is what made them a set — so one
+ * readout per set establishes what a readout per member would, at a cost that does not
+ * grow with the tree. What a set does not speak for still needs reading individually:
+ * a leftover is a file nothing else is like, and there is nothing to generalise from.
+ *
+ * The selection is data, not an action. Deciding to run it, and where, belongs to the
+ * caller.
+ */
+import type { DetectedSet, DetectedSets, MemberFile, ReadoutSelection } from "./set-types.js";
+/**
+ * Leftovers opened individually before the rest are elided.
+ *
+ * One readout per set costs O(sets), which is bounded by the menu. Leftovers are not: a
+ * tree of one-off human-named files is leftovers all the way down, and reading every one
+ * of them is a per-file cost in a pipeline whose whole claim is that it has none.
+ */
+export declare const MAX_LEFTOVER_READOUTS = 64;
+/** A file the selection named, with what the scan already knows about its bytes. */
+export interface ReadoutTarget {
+    readonly path: string;
+    readonly format: string;
+    readonly wrapper?: string;
+}
+export declare function selectReadouts(sets: readonly DetectedSet[], leftovers: readonly MemberFile[]): ReadoutSelection;
+/**
+ * The selection as readout targets. The format the scan detected rides along, so the
+ * reader picks a decoder without re-sniffing bytes it already sniffed.
+ */
+export declare function readoutTargets(detected: DetectedSets): ReadoutTarget[];

package/dist/input-scan/readout-budget.js

@@ -0,0 +1,61 @@
+/**
+ * Which files a header readout should open.
+ *
+ * Members of a set are alike by construction — that is what made them a set — so one
+ * readout per set establishes what a readout per member would, at a cost that does not
+ * grow with the tree. What a set does not speak for still needs reading individually:
+ * a leftover is a file nothing else is like, and there is nothing to generalise from.
+ *
+ * The selection is data, not an action. Deciding to run it, and where, belongs to the
+ * caller.
+ */
+/**
+ * Leftovers opened individually before the rest are elided.
+ *
+ * One readout per set costs O(sets), which is bounded by the menu. Leftovers are not: a
+ * tree of one-off human-named files is leftovers all the way down, and reading every one
+ * of them is a per-file cost in a pipeline whose whole claim is that it has none.
+ */
+export const MAX_LEFTOVER_READOUTS = 64;
+/** The member a set is best read through: the first non-empty one, by path order. */
+function representativeOf(set) {
+    const ordered = [...set.members].sort((a, b) => a.path.localeCompare(b.path, "en"));
+    return (ordered.find((member) => member.size > 0) ?? ordered[0])?.path;
+}
+export function selectReadouts(sets, leftovers) {
+    const representatives = [];
+    for (const set of sets) {
+        const path = representativeOf(set);
+        if (path !== undefined)
+            representatives.push({ setId: set.id, path });
+    }
+    const paths = [...leftovers].map((file) => file.path).sort((a, b) => a.localeCompare(b, "en"));
+    return {
+        representatives,
+        individual: paths.slice(0, MAX_LEFTOVER_READOUTS),
+        individualElided: Math.max(0, paths.length - MAX_LEFTOVER_READOUTS),
+    };
+}
+/**
+ * The selection as readout targets. The format the scan detected rides along, so the
+ * reader picks a decoder without re-sniffing bytes it already sniffed.
+ */
+export function readoutTargets(detected) {
+    const members = new Map();
+    for (const set of detected.sets)
+        for (const member of set.members)
+            members.set(member.path, member);
+    for (const member of detected.leftoverMembers)
+        members.set(member.path, member);
+    const paths = [...detected.readout.representatives.map((entry) => entry.path), ...detected.readout.individual];
+    const targets = [];
+    const seen = new Set();
+    for (const path of paths) {
+        const member = members.get(path);
+        if (!member || seen.has(path))
+            continue;
+        seen.add(path);
+        targets.push({ path, format: member.format, ...(member.wrapper ? { wrapper: member.wrapper } : {}) });
+    }
+    return targets;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Prefix-sufficient header readouts.
+ *
+ * Most of what a header says sits at the front of the file: the magic bytes, a
+ * declared `##` preamble, a delimited header row, the first records. Reading that
+ * costs one bounded prefix and no parser over the whole file, so it runs here in
+ * the harness process rather than in a container.
+ *
+ * Every function below is pure over a `Buffer` — the I/O is the caller's (see
+ * `enrich.ts`), which is what makes the whole surface testable from synthetic bytes.
+ */
+/** Bytes read from each file. The readout's whole per-file I/O budget. */
+export declare const READOUT_PREFIX_BYTES = 262144;
+/** Cap on the text window a readout inspects, whether decompressed or raw. */
+export declare const READOUT_TEXT_BYTES = 262144;
+export type ReadoutFields = Record<string, string | number | boolean>;
+export interface PrefixReadout {
+    readonly fields: ReadoutFields;
+    /** Why the fields are thin or empty. Present alongside whatever WAS read. */
+    readonly unavailable?: string;
+}
+/**
+ * Read what a bounded prefix can say about a file.
+ *
+ * `wrapper` is the compression the scan already identified from these same bytes
+ * (see `formats.ts`); it is reported alongside the inner readout, never in place
+ * of it.
+ */
+export declare function readPrefix(args: {
+    readonly prefix: Buffer;
+    readonly format: string;
+    readonly wrapper?: string;
+}): Promise<PrefixReadout>;

package/dist/input-scan/readout.js

@@ -0,0 +1,336 @@
+/**
+ * Prefix-sufficient header readouts.
+ *
+ * Most of what a header says sits at the front of the file: the magic bytes, a
+ * declared `##` preamble, a delimited header row, the first records. Reading that
+ * costs one bounded prefix and no parser over the whole file, so it runs here in
+ * the harness process rather than in a container.
+ *
+ * Every function below is pure over a `Buffer` — the I/O is the caller's (see
+ * `enrich.ts`), which is what makes the whole surface testable from synthetic bytes.
+ */
+import { constants as zlibConstants, createGunzip, createZstdDecompress } from "node:zlib";
+/** Bytes read from each file. The readout's whole per-file I/O budget. */
+export const READOUT_PREFIX_BYTES = 262_144;
+/** Cap on the text window a readout inspects, whether decompressed or raw. */
+export const READOUT_TEXT_BYTES = 262_144;
+/** Header lines scanned for a format's declared metadata. */
+const MAX_META_LINES = 200;
+const MAX_COLUMNS_REPORTED = 12;
+const MAX_COLUMN_NAME_CHARS = 24;
+const MAX_FIELD_CHARS = 200;
+const MAX_LINE_CHARS = 120;
+const MAX_RECORD_CHARS = 80;
+/** Window scanned for a NUL byte before the prefix is called binary. */
+const BINARY_SNIFF_BYTES = 4096;
+/**
+ * Read what a bounded prefix can say about a file.
+ *
+ * `wrapper` is the compression the scan already identified from these same bytes
+ * (see `formats.ts`); it is reported alongside the inner readout, never in place
+ * of it.
+ */
+export async function readPrefix(args) {
+    const { prefix, format, wrapper } = args;
+    if (prefix.length === 0)
+        return { fields: {}, unavailable: "file is empty" };
+    if (wrapper === undefined)
+        return decodeText(prefix, format);
+    const inner = await decompressBounded(prefix, wrapper);
+    if (inner === undefined)
+        return { fields: { wrapper }, unavailable: `${wrapper} has no in-process prefix decoder` };
+    if (inner.length === 0)
+        return { fields: { wrapper }, unavailable: `${wrapper} prefix did not decompress` };
+    return withWrapper(containerFields(inner) ?? decodeText(inner, format), wrapper);
+}
+function withWrapper(readout, wrapper) {
+    return { ...readout, fields: { ...readout.fields, wrapper } };
+}
+/**
+ * Decompress a prefix, tolerating the truncated tail that a prefix always has.
+ *
+ * `Z_SYNC_FLUSH` as the finish flush is what makes the cut-off member yield its
+ * decoded bytes instead of an error, and the output cap is what keeps a highly
+ * compressible prefix from expanding without bound.
+ */
+async function decompressBounded(raw, wrapper) {
+    const stream = decompressorFor(wrapper);
+    if (stream === undefined)
+        return undefined;
+    return await new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            stream.removeAllListeners();
+            stream.destroy();
+            resolve(Buffer.concat(chunks).subarray(0, READOUT_TEXT_BYTES));
+        };
+        stream.on("data", (chunk) => {
+            chunks.push(chunk);
+            total += chunk.length;
+            if (total >= READOUT_TEXT_BYTES)
+                finish();
+        });
+        stream.on("end", finish);
+        stream.on("close", finish);
+        stream.on("error", finish);
+        stream.end(raw);
+    });
+}
+function decompressorFor(wrapper) {
+    if (wrapper === "gzip" || wrapper === "bgzip")
+        return createGunzip({ finishFlush: zlibConstants.Z_SYNC_FLUSH });
+    if (wrapper === "zstd")
+        return createZstdDecompress();
+    return undefined;
+}
+/**
+ * The two bioinformatics containers whose payload is binary but whose header is a
+ * plain text block at a known offset — so a prefix reaches them and no container
+ * parser is needed.
+ */
+function containerFields(inner) {
+    if (inner.length >= 8 && inner.subarray(0, 4).toString("latin1") === "BAM\u0001") {
+        const textLength = inner.readInt32LE(4);
+        const header = inner.subarray(8, 8 + Math.min(Math.max(textLength, 0), READOUT_TEXT_BYTES)).toString("utf8");
+        const readout = textFields(header, "sam");
+        return { ...readout, fields: { ...readout.fields, container: "bam" } };
+    }
+    if (inner.subarray(0, 3).toString("latin1") === "BCF")
+        return { fields: { container: "bcf" } };
+    return undefined;
+}
+function decodeText(buf, format) {
+    if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0))
+        return { fields: {}, unavailable: "binary content with no prefix-readable header" };
+    return textFields(buf.subarray(0, READOUT_TEXT_BYTES).toString("utf8"), format);
+}
+function textFields(text, format) {
+    const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
+    const head = lines[0];
+    if (head === undefined)
+        return { fields: {}, unavailable: "no text in the prefix" };
+    if (format === "markdown")
+        return markdownFields(lines);
+    if (format === "json" || head.startsWith("{") || head.startsWith("["))
+        return jsonFields(text, lines);
+    if (format === "yaml" || head.trim() === "---")
+        return yamlFields(lines);
+    if (head.startsWith("##"))
+        return metaHeaderFields(lines);
+    if (head.startsWith(">"))
+        return { fields: { firstRecord: clip(head.slice(1), MAX_RECORD_CHARS), recordsInPrefix: countPrefixed(lines, ">") } };
+    if (head.startsWith("@HD") || head.startsWith("@SQ"))
+        return samFields(lines);
+    if (head.startsWith("@") && lines.length > 1)
+        return { fields: { firstRecord: clip(head.slice(1), MAX_RECORD_CHARS), readLength: lines[1].length } };
+    return delimitedFields(lines) ?? { fields: { firstLine: clip(head, MAX_LINE_CHARS), linesInPrefix: lines.length } };
+}
+/**
+ * The `##` preamble VCF, GFF, and their relatives declare.
+ *
+ * Where the preamble carries no column line of its own, the first data line is
+ * sniffed as a delimited row: a GFF's nine columns are a fact about the file that
+ * a meta-line count alone does not carry.
+ */
+function metaHeaderFields(lines) {
+    const fields = {};
+    let sawColumns = false;
+    for (const line of lines.slice(0, MAX_META_LINES)) {
+        if (line.startsWith("##fileformat="))
+            fields.fileformat = clip(line.slice("##fileformat=".length), 40);
+        else if (line.startsWith("##gff-version"))
+            fields.gffVersion = clip(line.slice("##gff-version".length), 20);
+        else if (line.startsWith("##reference="))
+            fields.reference = clip(line.slice("##reference=".length), 80);
+        else if (line.startsWith("#CHROM")) {
+            const samples = line.split("\t").slice(9);
+            fields.sampleCount = samples.length;
+            fields.samples = clip(samples.slice(0, 5).join(", "), MAX_FIELD_CHARS);
+            sawColumns = true;
+            break;
+        }
+    }
+    fields.metaLines = countPrefixed(lines, "##");
+    if (!sawColumns) {
+        const delimited = delimitedFields(lines);
+        if (delimited)
+            return { fields: { ...fields, ...delimited.fields } };
+    }
+    return { fields };
+}
+function samFields(lines) {
+    const fields = {
+        referenceSequences: countPrefixed(lines, "@SQ"),
+        readGroups: countPrefixed(lines, "@RG"),
+    };
+    const sortOrder = /(?:^|\t)SO:([^\t]+)/.exec(lines.find((line) => line.startsWith("@HD")) ?? "");
+    if (sortOrder)
+        fields.sortOrder = clip(sortOrder[1], 20);
+    return { fields };
+}
+const DELIMITERS = [
+    { char: ",", name: "comma" },
+    { char: "\t", name: "tab" },
+    { char: ";", name: "semicolon" },
+    { char: "|", name: "pipe" },
+];
+function sniffDelimiter(line) {
+    let best;
+    let bestCount = 0;
+    for (const candidate of DELIMITERS) {
+        const count = line.split(candidate.char).length - 1;
+        if (count > bestCount) {
+            best = candidate;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+/**
+ * The delimited-text readout: which separator, which row carries the column names,
+ * and what those names are. The header row is found past any comment preamble, so a
+ * `#`-commented TSV reports its columns rather than its first comment line.
+ */
+function delimitedFields(lines) {
+    const headerIndex = lines.findIndex((line) => !line.startsWith("#"));
+    if (headerIndex < 0)
+        return undefined;
+    const header = lines[headerIndex];
+    const delimiter = sniffDelimiter(header);
+    if (delimiter === undefined)
+        return undefined;
+    const columns = splitDelimited(header, delimiter.char).map((cell) => cell.trim());
+    const fields = {
+        delimiter: delimiter.name,
+        columnCount: columns.length,
+        columns: clip(columns
+            .slice(0, MAX_COLUMNS_REPORTED)
+            .map((cell) => cell.slice(0, MAX_COLUMN_NAME_CHARS))
+            .join(", "), MAX_FIELD_CHARS),
+        headerRow: looksLikeHeader(columns),
+        linesInPrefix: lines.length,
+    };
+    if (headerIndex > 0)
+        fields.commentLines = headerIndex;
+    return { fields };
+}
+/** Distinct, mostly non-numeric cells name columns; a row of numbers is data. */
+function looksLikeHeader(columns) {
+    if (columns.length === 0)
+        return false;
+    const numeric = columns.filter((cell) => cell !== "" && Number.isFinite(Number(cell))).length;
+    return new Set(columns).size === columns.length && numeric * 2 < columns.length;
+}
+function splitDelimited(line, delimiter) {
+    const cells = [];
+    let current = "";
+    let quoted = false;
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index];
+        if (quoted) {
+            if (char !== '"')
+                current += char;
+            else if (line[index + 1] === '"') {
+                current += '"';
+                index++;
+            }
+            else
+                quoted = false;
+            continue;
+        }
+        if (char === '"')
+            quoted = true;
+        else if (char === delimiter) {
+            cells.push(current);
+            current = "";
+        }
+        else
+            current += char;
+    }
+    cells.push(current);
+    return cells;
+}
+function jsonFields(text, lines) {
+    const whole = parseJson(text.slice(0, READOUT_TEXT_BYTES));
+    if (Array.isArray(whole)) {
+        const first = whole[0];
+        return {
+            fields: {
+                jsonType: "array",
+                elementCount: whole.length,
+                ...(isRecord(first) ? { firstElementKeys: joinKeys(Object.keys(first)) } : {}),
+            },
+        };
+    }
+    if (isRecord(whole)) {
+        const keys = Object.keys(whole);
+        return { fields: { jsonType: "object", keyCount: keys.length, keys: joinKeys(keys) } };
+    }
+    if (whole !== undefined)
+        return { fields: { jsonType: typeof whole } };
+    // A prefix of JSON Lines truncates mid-record at worst once, at the tail.
+    const candidates = lines.slice(0, MAX_META_LINES);
+    const parsed = candidates.map((line) => parseJson(line));
+    const complete = parsed.filter((value) => value !== undefined);
+    const record = parsed.find(isRecord);
+    if (record !== undefined && complete.length >= Math.max(1, candidates.length - 1)) {
+        return { fields: { jsonType: "json-lines", recordsInPrefix: lines.length, keys: joinKeys(Object.keys(record)) } };
+    }
+    return { fields: { firstLine: clip(lines[0], MAX_LINE_CHARS) }, unavailable: "JSON document extends past the readout prefix" };
+}
+/** Top-level keys, read positionally: an unindented `key:` line opens a mapping entry. */
+function yamlFields(lines) {
+    const keys = [];
+    for (const line of lines.slice(0, MAX_META_LINES)) {
+        const match = /^([A-Za-z_][\w.-]*):(\s|$)/.exec(line);
+        if (match)
+            keys.push(match[1]);
+    }
+    const documents = lines.filter((line) => line.trim() === "---").length;
+    return {
+        fields: {
+            topLevelKeyCount: keys.length,
+            topLevelKeys: joinKeys(keys),
+            linesInPrefix: lines.length,
+            ...(documents > 0 ? { documentSeparators: documents } : {}),
+        },
+    };
+}
+function markdownFields(lines) {
+    const headings = lines.filter((line) => /^#{1,6}\s/.test(line));
+    return {
+        fields: {
+            title: clip((headings[0] ?? lines[0]).replace(/^#+\s*/, ""), MAX_LINE_CHARS),
+            headings: headings.length,
+            linesInPrefix: lines.length,
+        },
+    };
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function joinKeys(keys) {
+    return clip(keys
+        .slice(0, MAX_COLUMNS_REPORTED)
+        .map((key) => key.slice(0, MAX_COLUMN_NAME_CHARS))
+        .join(", "), MAX_FIELD_CHARS);
+}
+function countPrefixed(lines, prefix) {
+    return lines.filter((line) => line.startsWith(prefix)).length;
+}
+function clip(text, limit) {
+    return text.replace(/\s+/g, " ").trim().slice(0, limit);
+}