@inflexa-ai/harness 0.28.0 → 0.29.0

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

@@ -4,8 +4,8 @@
  * 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.
+ * needs a container. Only a footer-indexed container reaches the sandbox, and only
+ * through the per-shape header readout (`enrich.ts`).
  *
  * 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
@@ -19,8 +19,8 @@ import type { InputScan, InputScanManifest, ScannedFile } from "./types.js";
  *
  * 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
+ * of stat-and-prefix work against a 20-minute profile deadline, and well above the
+ * largest input trees the platform is expected to stage. 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.
@@ -39,6 +39,7 @@ export interface ScanInputTreeArgs {
 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>;
+export declare function formatBytes(bytes: number): string;
 /**
  * Render a manifest for a briefing or a tool result.
  *

package/dist/input-scan/scan.js

@@ -4,8 +4,8 @@
  * 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.
+ * needs a container. Only a footer-indexed container reaches the sandbox, and only
+ * through the per-shape header readout (`enrich.ts`).
  *
  * 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
@@ -19,8 +19,8 @@ import { observeShapes } from "./shapes.js";
  *
  * 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
+ * of stat-and-prefix work against a 20-minute profile deadline, and well above the
+ * largest input trees the platform is expected to stage. 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.
@@ -95,7 +95,7 @@ export async function scanInputTree(args) {
     const { files, truncated } = await walk(args);
     return buildManifest(args.root, files, truncated, limit);
 }
-function formatBytes(bytes) {
+export function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
     const units = ["KB", "MB", "GB", "TB"];

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

@@ -0,0 +1,209 @@
+/**
+ * Detected-set vocabulary.
+ *
+ * A **set** is a mechanical fact: these paths instantiate one template. A **slot** is
+ * a position in that template whose token varies, reported with its class, its
+ * distinct-value count, and a bounded sample of the values themselves — a count alone
+ * cannot tell an entity identifier from a categorical label from a shard index, and
+ * those readings imply entirely different groupings.
+ *
+ * Nothing here decides a grouping, and nothing here is named `groups` or `dimensions`:
+ * that half belongs to the profiler agent, and a result an agent could copy into its
+ * submission would make its central judgement invisible (see the input-scan-manifest
+ * spec).
+ */
+import type { FormatCount, UnstructuredEntry } from "./types.js";
+import type { SlotTokenClass } from "./tokens.js";
+/** Why a file never reached the menu. */
+export type QuarantineReason = "os-junk" | "editor-temp" | "partial-download" | "atomic-write-temp";
+export interface QuarantineReasonCount {
+    readonly reason: QuarantineReason;
+    readonly count: number;
+}
+/**
+ * Quarantine is visible, never silent: a wrongly excluded file has to be discoverable
+ * by the agent and the user, so the counts and a bounded path sample are reported.
+ */
+export interface QuarantineSummary {
+    readonly count: number;
+    readonly totalBytes: number;
+    readonly reasons: readonly QuarantineReasonCount[];
+    readonly sample: readonly string[];
+}
+/** A helper file that carries no meaning apart from the data file it serves. */
+export interface CompanionFile {
+    readonly path: string;
+    /** The suffix that identified it — `.tbi`, `.bai`, `.md5`. */
+    readonly suffix: string;
+    readonly size: number;
+}
+/**
+ * A data file plus its companions — the logical unit the pipeline mines and counts.
+ *
+ * Membership counts logical units, so a variant file and its index are one member, and
+ * "N files, M indexed" becomes a computed completeness rather than a claim.
+ */
+export interface MemberFile {
+    readonly path: string;
+    readonly name: string;
+    readonly size: number;
+    readonly format: string;
+    readonly wrapper?: string;
+    readonly companions: readonly CompanionFile[];
+}
+export interface SetMember extends MemberFile {
+    /** Companion suffixes the rest of the set carries and this member does not. */
+    readonly missingCompanions: readonly string[];
+}
+export interface IncompleteMember {
+    readonly path: string;
+    readonly missingCompanions: readonly string[];
+}
+/**
+ * Companion coverage across a set, reported per member rather than averaged: an
+ * average hides the one member whose index is missing, which is exactly the fact a
+ * downstream step will fail on.
+ */
+export interface SetCompleteness {
+    /** Suffixes enough of the set carries that their absence is a gap, not a variation. */
+    readonly expectedCompanions: readonly string[];
+    readonly completeMembers: number;
+    readonly incompleteMembers: number;
+    readonly incompleteSample: readonly IncompleteMember[];
+}
+export type SlotLocation = "directory" | "name";
+/**
+ * A varying position in a set's path template.
+ *
+ * `sampleValues` is bounded and normative — it is the material a grouping decision
+ * rests on. The complete value set stays on {@link DetectedSets.slotValues},
+ * host-side, for arithmetic a bounded sample cannot do.
+ */
+export interface SetSlot {
+    /** Unique within one scan, so a cross-check can name the slot it links to. */
+    readonly id: string;
+    readonly location: SlotLocation;
+    /** Directory segment index, or token index within the name. */
+    readonly index: number;
+    readonly tokenClass: SlotTokenClass;
+    readonly width?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly skeleton?: string;
+    /** Literal text fused to the front of the token, recovered from what every value shares. */
+    readonly prefix?: string;
+    readonly suffix?: string;
+    readonly distinctValues: number;
+    readonly sampleValues: readonly string[];
+    /** The slot this one repeats. A token in both a directory and the stem is ONE identity, not two. */
+    readonly sameAsSlot?: string;
+    /** Members whose two positions disagreed, when the link was made despite them. */
+    readonly crossCheckMismatches?: number;
+}
+/** A template rendered as a sequence: concatenating it reproduces {@link DetectedSet.pathTemplate}. */
+export type TemplateSegment = {
+    readonly kind: "literal";
+    readonly text: string;
+} | {
+    readonly kind: "slot";
+    readonly slotId: string;
+};
+/**
+ * How a set came to be.
+ *
+ * A consumer has to be able to tell these apart: a `catch-all` set is evidence that
+ * the same directory shape repeats, not that the filenames agree, and reading it as a
+ * name-structure fact would overstate what the scan established.
+ */
+export type SetOrigin = "marker" | "mined" | "prefix" | "family" | "catch-all";
+/** Compression wrappers observed across a set's members. `none` names the uncompressed. */
+export interface WrapperCount {
+    readonly wrapper: string;
+    readonly count: number;
+}
+export interface DetectedSet {
+    /** Stable within one scan (`set-1`, `set-2`, …). */
+    readonly id: string;
+    readonly origin: SetOrigin;
+    /** The catalogue entry that claimed this subtree, when `origin` is `marker`. */
+    readonly marker?: string;
+    readonly pathTemplate: string;
+    readonly segments: readonly TemplateSegment[];
+    /** Logical units — a data file and its companions count once. */
+    readonly memberCount: number;
+    /** Files, companions included. */
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    /**
+     * Format and wrapper disagreement inside a set is a property OF the set, never a
+     * partition key: members that differ only in compression are one set that says so.
+     */
+    readonly formats: readonly FormatCount[];
+    readonly wrappers: readonly WrapperCount[];
+    readonly slots: readonly SetSlot[];
+    readonly completeness: SetCompleteness;
+    readonly examplePaths: readonly string[];
+    /** Complete membership. Host-side: the bounded projection is everything above. */
+    readonly members: readonly SetMember[];
+}
+/**
+ * Files no set speaks for, in aggregate.
+ *
+ * Never one set per file: a tree of arbitrarily named files would otherwise produce a
+ * set count proportional to the file count. Whether these are notable singletons worth
+ * describing or an unclassified remainder is the agent's determination.
+ */
+export interface LeftoverFiles {
+    readonly memberCount: number;
+    /** Members plus the companions riding on them, so it adds up against `keptFileCount`. */
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly sample: readonly UnstructuredEntry[];
+}
+export interface SetRepresentative {
+    readonly setId: string;
+    readonly path: string;
+}
+/**
+ * Which files a header readout should open.
+ *
+ * One representative per set plus every leftover: within a set the members are alike
+ * by construction, so a readout per file buys nothing and costs the enrichment budget
+ * this pipeline exists to bound.
+ */
+export interface ReadoutSelection {
+    readonly representatives: readonly SetRepresentative[];
+    /** Leftover paths — the files no set speaks for, each read on its own. Bounded. */
+    readonly individual: readonly string[];
+    /**
+     * Leftovers past that bound. Reported rather than dropped: a tree of thousands of
+     * one-off files would otherwise buy an unbounded read budget, and an agent shown a
+     * header for some leftovers and not others has to be told which.
+     */
+    readonly individualElided: number;
+}
+export interface DetectedSets {
+    readonly fileCount: number;
+    /** Files that survived quarantine — the denominator coverage is measured against. */
+    readonly keptFileCount: number;
+    readonly coverage: number;
+    readonly quarantine: QuarantineSummary;
+    readonly sets: readonly DetectedSet[];
+    readonly leftovers: LeftoverFiles;
+    /** Complete leftover membership. Host-side, for the same reason as {@link DetectedSet.members}. */
+    readonly leftoverMembers: readonly MemberFile[];
+    readonly readout: ReadoutSelection;
+    /**
+     * Complete value sets, keyed by slot id. Host-side only: completeness arithmetic,
+     * cross-set identity checks, and the index build need every value, while anything
+     * rendered or persisted carries {@link SetSlot.sampleValues}.
+     */
+    readonly slotValues: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Per slot id, the value each member of that slot's set carries, aligned to
+     * {@link DetectedSet.members}. Host-side only, and the material a split resolves
+     * against: partitioning a set by one of its slots is a lookup here, never a
+     * re-tokenisation of the member's name.
+     */
+    readonly memberSlotValues: ReadonlyMap<string, readonly string[]>;
+}

package/dist/input-scan/set-types.js

@@ -0,0 +1,15 @@
+/**
+ * Detected-set vocabulary.
+ *
+ * A **set** is a mechanical fact: these paths instantiate one template. A **slot** is
+ * a position in that template whose token varies, reported with its class, its
+ * distinct-value count, and a bounded sample of the values themselves — a count alone
+ * cannot tell an entity identifier from a categorical label from a shard index, and
+ * those readings imply entirely different groupings.
+ *
+ * Nothing here decides a grouping, and nothing here is named `groups` or `dimensions`:
+ * that half belongs to the profiler agent, and a result an agent could copy into its
+ * submission would make its central judgement invisible (see the input-scan-manifest
+ * spec).
+ */
+export {};

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

@@ -0,0 +1,93 @@
+/**
+ * Stage 3 — name-template mining within one directory context.
+ *
+ * Literal versus slot is decided by per-position distinct counts: a position whose
+ * token is the same in every member is literal text, and one that varies is a slot.
+ * Groups that differ in exactly one position, or only in extension, merge — variance
+ * inside a set is a property of the set, never a partition key.
+ *
+ * Proliferation is bounded three ways, because a template per file is the same failure
+ * as no templates at all: a prefix trie claims residual singletons that share literal
+ * text, a family collapse claims singletons that share only a token-kind sequence
+ * (one template for the family costs less than one template each), and a catch-all
+ * claims the rest where the repetition across directories is itself the structure.
+ */
+import type { MemberFile, SlotLocation } from "./set-types.js";
+import type { NameToken, SlotTokenClass, TokenKind } from "./tokens.js";
+/** A member with the directory-slot values of the context it was found in. */
+export interface ContextFile extends MemberFile {
+    readonly varValues: readonly string[];
+}
+export interface MinedItem {
+    readonly file: ContextFile;
+    readonly tokens: readonly NameToken[];
+    readonly suffix: string;
+    readonly skeleton: string;
+}
+export type MinedKind = "tokens" | "prefix" | "family" | "catch-all";
+export interface MinedGroup {
+    readonly kind: MinedKind;
+    readonly tokenKinds: readonly TokenKind[];
+    /** The shared literal head, when the group was claimed by prefix mining. */
+    readonly prefixTokens: readonly NameToken[];
+    readonly suffix: string;
+    /** Extension chains observed across the members, with counts. */
+    readonly suffixes: Map<string, number>;
+    items: MinedItem[];
+    distinct?: number[];
+}
+/** A slot before the assembly stamps it with an id. */
+export interface DraftSlot {
+    readonly location: SlotLocation;
+    readonly index: number;
+    readonly tokenClass: SlotTokenClass;
+    readonly width?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly skeleton?: string;
+    readonly prefix?: string;
+    readonly suffix?: string;
+    readonly distinctValues: number;
+    readonly sampleValues: readonly string[];
+    /** The complete value set — bounded projection is `sampleValues`. */
+    readonly values: readonly string[];
+    /** The value each member carries, aligned to the order the raw values arrived in. */
+    readonly memberValues: readonly string[];
+    sameAs?: number;
+    crossCheckMismatches?: number;
+}
+export type DraftSegment = {
+    readonly kind: "literal";
+    readonly text: string;
+} | {
+    readonly kind: "slot";
+    readonly slot: number;
+};
+/**
+ * Fold what is left of a cross-directory context into one set.
+ *
+ * Where the same directory shape repeats, that repetition is the structure, and the
+ * residual names inside it are one set whatever they are called. Extension
+ * disagreement is carried as the format census, never used to split.
+ */
+export declare function catchAll(residue: readonly MinedItem[], hasDirectorySlot: boolean): {
+    sets: MinedGroup[];
+    rest: MinedItem[];
+};
+/** Mine one directory context: every file whose directory path instantiates one template. */
+export declare function mineContext(files: readonly ContextFile[]): {
+    sets: MinedGroup[];
+    residue: MinedItem[];
+};
+/** Describe one varying position: its class, its cardinality, and a bounded value sample. */
+export declare function describeSlot(rawValues: readonly string[], location: SlotLocation, index: number): DraftSlot;
+/** The template token a slot renders as. */
+export declare function slotToken(slot: DraftSlot): string;
+/**
+ * The name half of a set's template: its literal text, its slots, and the order they
+ * appear in. Directory slots are prepended by the assembly, which knows the context.
+ */
+export declare function describeGroup(group: MinedGroup): {
+    slots: DraftSlot[];
+    segments: DraftSegment[];
+};