@vibe-agent-toolkit/utils 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/testing/tree-snapshot.js

@@ -0,0 +1,163 @@
+/**
+ * `snapshotTree` — a comparable, content-addressed picture of a directory tree.
+ *
+ * The fault matrix asks one question of every injected run: did the tree end
+ * byte-equal to BEFORE or to GOLDEN, never a third state? Answering it needs the
+ * trees as values: a map from relative path to what is there (kind, mode, content
+ * hash, link target), and a diff that names every difference in words.
+ *
+ * ## What it will not do
+ *
+ * - It never follows a link: a link is `{ kind: 'link', target }` and nothing under it is
+ *   walked, so a snapshot cannot wander out of its root or loop.
+ * - It never opens a special file (FIFO, socket, device): `lstat` decides the kind first and
+ *   only a regular file is opened, `O_NONBLOCK`, so a FIFO that slipped in between cannot hang it.
+ * - It never swallows an unreadable entry. A directory the OS refuses is a loud error naming
+ *   it, because a gap in the picture would read as "unchanged".
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so the `./testing`
+ * subpath keeps the empty third-party set its purity pin asserts.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, readlinkSync } from 'node:fs';
+import { isPathAbsentError } from '../errors/errno-table.js';
+import { safePath } from '../path-core.js';
+import { decodeTextContent } from '../text-content.js';
+const NON_BLOCKING = constants.O_NONBLOCK ?? 0;
+const PERMISSION_BITS = 0o7777;
+const ROOT_KEY = '.';
+function unreadable(path, error) {
+    return new Error(`snapshotTree: cannot read ${path}: ${error.message}`, { cause: error });
+}
+/** The file's content as it is hashed: byte rewrites first, then (decoded once) text rewrites. */
+function rewritten(content, key, rewrites) {
+    const applicable = rewrites.filter((rule) => rule.applies(key));
+    let bytes = content;
+    for (const rule of applicable)
+        if ('rewriteBytes' in rule)
+            bytes = rule.rewriteBytes(bytes);
+    const textRules = applicable.filter((rule) => 'rewrite' in rule);
+    return textRules.length === 0 ? bytes : textRules.reduce((text, rule) => rule.rewrite(text), decodeTextContent(bytes).text);
+}
+function hashFile(path, key, rewrites) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | NON_BLOCKING);
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return undefined;
+        throw unreadable(path, error);
+    }
+    try {
+        const stats = fstatSync(fd);
+        if (!stats.isFile())
+            return undefined;
+        return { mode: stats.mode & PERMISSION_BITS, sha256: createHash('sha256').update(rewritten(readFileSync(fd), key, rewrites)).digest('hex') };
+    }
+    catch (error) {
+        throw unreadable(path, error);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function linkTarget(path) {
+    try {
+        return readlinkSync(path);
+    }
+    catch (error) {
+        throw unreadable(path, error);
+    }
+}
+/** The entry at `path`, or undefined when it vanished between listing and looking. */
+function entryAt(path, key, rewrites) {
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return undefined;
+        throw unreadable(path, error);
+    }
+    if (stats.isSymbolicLink())
+        return { kind: 'link', target: linkTarget(path) };
+    if (stats.isDirectory())
+        return { kind: 'dir', mode: stats.mode & PERMISSION_BITS };
+    if (!stats.isFile())
+        return { kind: 'special' };
+    const hashed = hashFile(path, key, rewrites);
+    return hashed === undefined ? { kind: 'special' } : { kind: 'file', ...hashed };
+}
+function walk(path, key, rewrites, out) {
+    const entry = entryAt(path, key, rewrites);
+    if (entry === undefined)
+        return;
+    out.set(key, entry);
+    if (entry.kind !== 'dir')
+        return;
+    let names;
+    try {
+        names = readdirSync(path);
+    }
+    catch (error) {
+        throw unreadable(path, error);
+    }
+    for (const name of names) {
+        walk(safePath.join(path, name), key === ROOT_KEY ? name : `${key}/${name}`, rewrites, out);
+    }
+}
+/**
+ * Snapshot the tree at `root`.
+ *
+ * @param root - A directory, a file or a link; absent yields the empty map
+ * @param options - Content rewrites applied before hashing; a key prefix for merging roots
+ * @returns Entries in walk order; compare with {@link diffSnapshots}
+ */
+export function snapshotTree(root, options = {}) {
+    const out = new Map();
+    walk(root, options.keyPrefix ?? ROOT_KEY, options.rewrites ?? [], out);
+    return out;
+}
+function describeEntry(entry) {
+    switch (entry.kind) {
+        case 'file': return `file mode ${entry.mode.toString(8)} sha256 ${entry.sha256.slice(0, 12)}`;
+        case 'dir': return `dir mode ${entry.mode.toString(8)}`;
+        case 'link': return `link -> ${entry.target}`;
+        case 'special': return 'special file';
+    }
+}
+/** Everything an entry is compared by: what a diff line prints shows only the head of a file's hash. */
+function stateOf(entry) {
+    return entry.kind === 'file' ? `${describeEntry(entry)} ${entry.sha256}` : describeEntry(entry);
+}
+function compareKeys(x, y) {
+    if (x === y)
+        return 0;
+    return x < y ? -1 : 1;
+}
+/**
+ * Every difference between two snapshots, in words: `+ key (…)` added, `- key (…)`
+ * removed, `~ key: … => …` changed. Sorted by key; empty means identical.
+ */
+export function diffSnapshots(a, b) {
+    const lines = [];
+    for (const [key, before] of a) {
+        const after = b.get(key);
+        if (after === undefined)
+            lines.push({ key, line: `- ${key} (${describeEntry(before)})` });
+        else if (stateOf(before) !== stateOf(after))
+            lines.push({ key, line: `~ ${key}: ${describeEntry(before)} => ${describeEntry(after)}` });
+    }
+    for (const [key, after] of b) {
+        if (!a.has(key))
+            lines.push({ key, line: `+ ${key} (${describeEntry(after)})` });
+    }
+    return lines.toSorted((x, y) => compareKeys(x.key, y.key)).map((item) => item.line);
+}
+/** The entries at `prefix` and under it (keys unchanged); a sibling sharing the spelling is not under it. */
+export function subtree(s, prefix) {
+    return new Map([...s].filter(([key]) => key === prefix || key.startsWith(`${prefix}/`)));
+}
+//# sourceMappingURL=tree-snapshot.js.map

package/dist/testing/tree-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-snapshot.js","sourceRoot":"","sources":["../../src/testing/tree-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -21,10 +21,16 @@
 import type { UnreadablePolicy } from './listing-refusal.js';
 export * from './test-helpers.js';
 export { __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
+export * from './testing/archive-fixtures.js';
 export * from './testing/executables.js';
+export * from './testing/fault-fs.js';
+export { faultFsSpecOf, faultRuleOf, INJECTED_ERRNOS, injectedErrnoError } from './testing/fault-spec.js';
+export type { FaultFsSpec, FaultRule, FaultSpec, FsApi, FsOpFamily, InjectedErrno } from './testing/fault-spec.js';
 export * from './testing/hostile-tree.js';
 export * from './testing/platform-gates.js';
 export * from './testing/temp-dir.js';
+export * from './testing/tier-timeout.js';
+export * from './testing/tree-snapshot.js';
 /** A planted fixture tree and the means to remove it. */
 export interface TempCorpus {
     /** Absolute path to the tree's root. */

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAG3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AAEtC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,UAAU,CAMZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,iBAAiB,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAEtE"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAG3B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1G,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACnH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAE3C,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,UAAU,CAMZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,iBAAiB,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAEtE"}

package/dist/testing.js

@@ -31,10 +31,17 @@ export * from './test-helpers.js';
 export { __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
 // The three fixture modules the sinks' suites share: the ONE temp-dir family,
 // the host gates, and the hostile tree every sink is tested against.
+export * from './testing/archive-fixtures.js';
 export * from './testing/executables.js';
+export * from './testing/fault-fs.js';
+// By name: the harness's vocabulary, not its op table (`OPS`, `OpSpec`, `PathShape` are `fault-fs.ts`'s
+// own wiring, and an `export *` here made them this subpath's API). Pinned by `module-subpaths.test.ts`.
+export { faultFsSpecOf, faultRuleOf, INJECTED_ERRNOS, injectedErrnoError } from './testing/fault-spec.js';
 export * from './testing/hostile-tree.js';
 export * from './testing/platform-gates.js';
 export * from './testing/temp-dir.js';
+export * from './testing/tier-timeout.js';
+export * from './testing/tree-snapshot.js';
 /**
  * Write a literal corpus into a fresh temp directory.
  *
@@ -119,6 +126,6 @@ export function replantableCorpus(prefix, corpus) {
  * @returns A `refuse` policy for `crawlDirectory` and the git listings
  */
 export function refuseUnreadableFixture(root) {
-    return { refuse: { root, remedy: 'A test fixture must be listable in full; fix the fixture, not the walk.' } };
+    return { refuse: { root, remedy: 'A test fixture must be listable in full; fix the fixture, not the walk.', side: 'source' } };
 }
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,sEAAsE;AACtE,cAAc,mBAAmB,CAAC;AAClC,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,qEAAqE;AACrE,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AAUtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAwC;IAExC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAAwC;IAExC,IAAI,OAA+B,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,0EAA0E;YAC1E,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,iEAAiE,CAC9F,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,yEAAyE,EAAE,EAAE,CAAC;AACjH,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,sEAAsE;AACtE,cAAc,mBAAmB,CAAC;AAClC,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,qEAAqE;AACrE,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,wGAAwG;AACxG,yGAAyG;AACzG,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE1G,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAU3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAwC;IAExC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAAwC;IAExC,IAAI,OAA+B,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,0EAA0E;YAC1E,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,iEAAiE,CAC9F,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,yEAAyE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;AACjI,CAAC"}

package/dist/text-content.d.ts

@@ -130,6 +130,34 @@
  * NOT shift is the content key, which is computed over the raw bytes; see
  * `resources`' `content-key.ts`.
  */
+import { VatError } from './errors/vat-error.js';
+/**
+ * Thrown when bytes are too many to become one JS string — the engine's refusal,
+ * made a coded error so a caller can treat it as a fact about a file.
+ *
+ * The limit is the engine's, not VAT's: V8 caps a string at
+ * `buffer.constants.MAX_STRING_LENGTH` (0x1fffffe8) UTF-16 code units, and
+ * decoding past it throws. One near-gigabyte CSV in a corpus used to abort a
+ * whole projection population on that throw.
+ *
+ * Two places raise it, and they agree by construction rather than by a shared
+ * literal. The `./fs` read path (`readDecodableBytes` in `text-file.ts`) refuses
+ * by `stat` BEFORE reading, against `MAX_DECODABLE_BYTES`, so half a gigabyte is
+ * never pulled into memory only to be refused. {@link decodeTextContent} — pure,
+ * so it cannot ask `node:buffer` for the limit (`subpath-purity.test.ts`) —
+ * translates the engine's own refusal for bytes that arrive by any other route.
+ * Dispatch with `isVatError(error, TextTooLargeError.code)`, never on the message.
+ */
+export declare class TextTooLargeError extends VatError {
+    readonly byteLength: number;
+    /** The code every instance carries, for `isVatError(error, TextTooLargeError.code)`. */
+    static readonly code = "TEXT_TOO_LARGE";
+    /**
+     * @param byteLength - How many bytes the refused content holds
+     * @param options - `cause`, when an engine refusal is being translated
+     */
+    constructor(byteLength: number, options?: ErrorOptions);
+}
 /** An encoding this module can decode. */
 export type TextEncoding = 'utf-8' | 'utf-16le' | 'utf-16be' | 'utf-32le' | 'utf-32be';
 /**
@@ -184,6 +212,7 @@ export interface DecodedText extends TextProvenance {
  * @param bytes - The exact bytes read from disk
  * @returns The decoded text, the encoding used, whether that was a fact, and how
  *   many characters the decode had to replace
+ * @throws {@link TextTooLargeError} when the engine refuses a string that long
  *
  * @example
  * ```typescript

package/dist/text-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-content.d.ts","sourceRoot":"","sources":["../src/text-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmIG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkLD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAiChE"}
+{"version":3,"file":"text-content.d.ts","sourceRoot":"","sources":["../src/text-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAS3C,QAAQ,CAAC,UAAU,EAAE,MAAM;IAR7B,wFAAwF;IACxF,MAAM,CAAC,QAAQ,CAAC,IAAI,oBAAoB;IAExC;;;OAGG;gBAEQ,UAAU,EAAE,MAAM,EAC3B,OAAO,CAAC,EAAE,YAAY;CAQzB;AAkBD,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkLD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAOhE"}

package/dist/text-content.js

@@ -130,6 +130,51 @@
  * NOT shift is the content key, which is computed over the raw bytes; see
  * `resources`' `content-key.ts`.
  */
+import { VatError } from './errors/vat-error.js';
+/**
+ * Thrown when bytes are too many to become one JS string — the engine's refusal,
+ * made a coded error so a caller can treat it as a fact about a file.
+ *
+ * The limit is the engine's, not VAT's: V8 caps a string at
+ * `buffer.constants.MAX_STRING_LENGTH` (0x1fffffe8) UTF-16 code units, and
+ * decoding past it throws. One near-gigabyte CSV in a corpus used to abort a
+ * whole projection population on that throw.
+ *
+ * Two places raise it, and they agree by construction rather than by a shared
+ * literal. The `./fs` read path (`readDecodableBytes` in `text-file.ts`) refuses
+ * by `stat` BEFORE reading, against `MAX_DECODABLE_BYTES`, so half a gigabyte is
+ * never pulled into memory only to be refused. {@link decodeTextContent} — pure,
+ * so it cannot ask `node:buffer` for the limit (`subpath-purity.test.ts`) —
+ * translates the engine's own refusal for bytes that arrive by any other route.
+ * Dispatch with `isVatError(error, TextTooLargeError.code)`, never on the message.
+ */
+export class TextTooLargeError extends VatError {
+    byteLength;
+    /** The code every instance carries, for `isVatError(error, TextTooLargeError.code)`. */
+    static code = 'TEXT_TOO_LARGE';
+    /**
+     * @param byteLength - How many bytes the refused content holds
+     * @param options - `cause`, when an engine refusal is being translated
+     */
+    constructor(byteLength, options) {
+        super(TextTooLargeError.code, `${byteLength} bytes is too large to decode into a JavaScript string`, options);
+        this.byteLength = byteLength;
+    }
+}
+/**
+ * The code Node's `TextDecoder` attaches when the decoded string would pass the
+ * engine's string-length limit. Matched as a `code`, never as its message.
+ */
+const ENGINE_STRING_TOO_LONG = 'ERR_STRING_TOO_LONG';
+/**
+ * Whether `error` is the engine refusing to build a string that long.
+ *
+ * @param error - What a decode threw
+ * @returns True for Node's `ERR_STRING_TOO_LONG`
+ */
+function isEngineStringTooLong(error) {
+    return error instanceof Error && error.code === ENGINE_STRING_TOO_LONG;
+}
 /**
  * Byte-order marks, **longest first**.
  *
@@ -308,6 +353,7 @@ function countReplacementCharacters(text) {
  * @param bytes - The exact bytes read from disk
  * @returns The decoded text, the encoding used, whether that was a fact, and how
  *   many characters the decode had to replace
+ * @throws {@link TextTooLargeError} when the engine refuses a string that long
  *
  * @example
  * ```typescript
@@ -318,6 +364,24 @@ function countReplacementCharacters(text) {
  * ```
  */
 export function decodeTextContent(bytes) {
+    try {
+        return decodeWithinEngineLimits(bytes);
+    }
+    catch (error) {
+        if (isEngineStringTooLong(error))
+            throw new TextTooLargeError(bytes.byteLength, { cause: error });
+        throw error;
+    }
+}
+/**
+ * {@link decodeTextContent} without the translation of the engine's
+ * string-length refusal — split out so the translation wraps BOTH decodes, the
+ * fatal first pass and the lenient retry, either of which can reach the limit.
+ *
+ * @param bytes - The exact bytes read from disk
+ * @returns The decoded text and its provenance
+ */
+function decodeWithinEngineLimits(bytes) {
     const bom = bomAt(bytes);
     const encoding = bom?.encoding ?? 'utf-8';
     const body = bom === null ? bytes : bytes.subarray(bom.length);

package/dist/text-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"text-content.js","sourceRoot":"","sources":["../src/text-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"text-content.js","sourceRoot":"","sources":["../src/text-content.ts"],"names":[],"mappings":"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"}

package/dist/text-file.d.ts

@@ -14,18 +14,20 @@
  * it worse rather than more consistent.
  *
  * A caller that needs the RAW bytes as well as the text — to hash them, key
- * them, or report `stat().size` — must not use these: read the bytes once itself
- * and call `decodeTextContent` on them, so the digest and the characters come
- * from the same read. `readContentWithKey` in `@vibe-agent-toolkit/resources` is
- * that caller and is shaped exactly that way.
+ * them, or report `stat().size` — must not use these: read the bytes once with
+ * {@link readDecodableBytes} and call `decodeTextContent` on them, so the digest
+ * and the characters come from the same read. `readContentWithKey` in
+ * `@vibe-agent-toolkit/resources` is that caller and is shaped exactly that way.
  */
+import { type FileHandle } from 'node:fs/promises';
 import { type DecodedText } from './text-content.js';
 /**
  * Read a file and decode it through {@link decodeTextContent}.
  *
  * @param filePath - Path to read
  * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
- * @throws Whatever `readFile` throws — callers decide whether that is fatal
+ * @throws Whatever `readFile` throws — callers decide whether that is fatal — and
+ *   {@link TextTooLargeError} for a file too large to decode, before reading it
  *
  * @example
  * ```typescript
@@ -39,7 +41,57 @@ export declare function readTextContent(filePath: string): Promise<DecodedText>;
  *
  * @param filePath - Path to read
  * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
- * @throws Whatever `readFileSync` throws
+ * @throws Whatever `readFileSync` throws, and {@link TextTooLargeError} as {@link readDecodableBytes} does
  */
 export declare function readTextContentSync(filePath: string): DecodedText;
+/**
+ * The most bytes that can be decoded into one JS string: the engine's own
+ * string-length limit, read from `node:buffer` rather than written down.
+ *
+ * A bound on BYTES stated in UTF-16 code units, which is exact-or-safe for UTF-8
+ * (a UTF-8 byte never yields more than one code unit) and conservative for
+ * UTF-16/UTF-32, whose bytes yield half or a quarter as many.
+ */
+export declare const MAX_DECODABLE_BYTES: number;
+/**
+ * Whether content of this many bytes is past what can be decoded to a string.
+ *
+ * @param byteLength - The content's size in bytes, as `stat` reports it
+ * @returns True when decoding it would exceed {@link MAX_DECODABLE_BYTES}
+ */
+export declare function exceedsDecodableLength(byteLength: number): boolean;
+/**
+ * Open `filePath` for reading without ever blocking on it: a named pipe, socket
+ * or device is refused (`EFTYPE`) and its handle closed, so only a regular file
+ * (or a directory, which the read refuses itself) comes back. The open a caller
+ * uses to PROVE a source readable before copying it — a bare `open(path, 'r')`
+ * of a pipe waits for a writer forever.
+ *
+ * @param filePath - Path to open
+ * @returns The open handle; the caller closes it
+ * @throws an `EFTYPE` errno for a special file, and whatever `open` throws otherwise
+ */
+export declare function openForReading(filePath: string): Promise<FileHandle>;
+/**
+ * Read a file's raw bytes for decoding — refusing, by `stat` and before reading
+ * a byte, one too large to decode at all.
+ *
+ * The one read path for "bytes that are about to go through
+ * {@link decodeTextContent}": {@link readTextContent} uses it, and so does
+ * `readContentWithKey` in `@vibe-agent-toolkit/resources`, which needs the raw
+ * bytes as well to key them. Without the stat, a 966 MB file is read whole and
+ * only then refused by the decoder, and past 2 GiB `readFile` fails first with
+ * its own `ERR_FS_FILE_TOO_LARGE` — two different errors for one fact.
+ *
+ * The size comes from `fstat` on the handle that is then read, not from a
+ * separate `stat` of the path, so a rename between the two cannot substitute
+ * another file. A file that GROWS past the limit after the `fstat` still reaches
+ * the decoder, which raises the same {@link TextTooLargeError}.
+ *
+ * @param filePath - Path to read
+ * @returns The file's bytes
+ * @throws {@link TextTooLargeError} when the file is past {@link MAX_DECODABLE_BYTES},
+ *   an `EFTYPE` errno when it is not a regular file, and whatever `open`/`readFile` throw otherwise
+ */
+export declare function readDecodableBytes(filePath: string): Promise<Buffer>;
 //# sourceMappingURL=text-file.d.ts.map

package/dist/text-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-file.d.ts","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAEjE"}
+{"version":3,"file":"text-file.d.ts","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAUjE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAoC,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElE;AAoBD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAS1E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1E"}

package/dist/text-file.js

@@ -14,20 +14,23 @@
  * it worse rather than more consistent.
  *
  * A caller that needs the RAW bytes as well as the text — to hash them, key
- * them, or report `stat().size` — must not use these: read the bytes once itself
- * and call `decodeTextContent` on them, so the digest and the characters come
- * from the same read. `readContentWithKey` in `@vibe-agent-toolkit/resources` is
- * that caller and is shaped exactly that way.
+ * them, or report `stat().size` — must not use these: read the bytes once with
+ * {@link readDecodableBytes} and call `decodeTextContent` on them, so the digest
+ * and the characters come from the same read. `readContentWithKey` in
+ * `@vibe-agent-toolkit/resources` is that caller and is shaped exactly that way.
  */
-import { readFileSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { decodeTextContent } from './text-content.js';
+import { constants } from 'node:buffer';
+import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { refuseSpecialFile } from './special-file.js';
+import { decodeTextContent, TextTooLargeError } from './text-content.js';
 /**
  * Read a file and decode it through {@link decodeTextContent}.
  *
  * @param filePath - Path to read
  * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
- * @throws Whatever `readFile` throws — callers decide whether that is fatal
+ * @throws Whatever `readFile` throws — callers decide whether that is fatal — and
+ *   {@link TextTooLargeError} for a file too large to decode, before reading it
  *
  * @example
  * ```typescript
@@ -36,16 +39,113 @@ import { decodeTextContent } from './text-content.js';
  * ```
  */
 export async function readTextContent(filePath) {
-    return decodeTextContent(await readFile(filePath));
+    return decodeTextContent(await readDecodableBytes(filePath));
 }
 /**
  * {@link readTextContent}, synchronously.
  *
  * @param filePath - Path to read
  * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
- * @throws Whatever `readFileSync` throws
+ * @throws Whatever `readFileSync` throws, and {@link TextTooLargeError} as {@link readDecodableBytes} does
  */
 export function readTextContentSync(filePath) {
-    return decodeTextContent(readFileSync(filePath));
+    const handle = openSync(filePath, readWithoutBlocking());
+    try {
+        const stats = fstatSync(handle);
+        refuseSpecialFile(stats, filePath);
+        refuseUndecodableSize(stats.size);
+        return decodeTextContent(readFileSync(handle));
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+/**
+ * The most bytes that can be decoded into one JS string: the engine's own
+ * string-length limit, read from `node:buffer` rather than written down.
+ *
+ * A bound on BYTES stated in UTF-16 code units, which is exact-or-safe for UTF-8
+ * (a UTF-8 byte never yields more than one code unit) and conservative for
+ * UTF-16/UTF-32, whose bytes yield half or a quarter as many.
+ */
+export const MAX_DECODABLE_BYTES = constants.MAX_STRING_LENGTH;
+/**
+ * Whether content of this many bytes is past what can be decoded to a string.
+ *
+ * @param byteLength - The content's size in bytes, as `stat` reports it
+ * @returns True when decoding it would exceed {@link MAX_DECODABLE_BYTES}
+ */
+export function exceedsDecodableLength(byteLength) {
+    return byteLength > MAX_DECODABLE_BYTES;
+}
+/**
+ * The flags to open for reading without waiting on a writer. Opening a named
+ * pipe blocks until one appears — a FIFO reached by a parse lane hung the whole
+ * run — and `O_NONBLOCK` returns at once so the handle's `fstat` can refuse it.
+ * It changes nothing for a regular file. Windows defines no `O_NONBLOCK` (and no
+ * FIFOs). Read at the call, not at import, so a test's partial `node:fs` mock
+ * that never reads a file does not have to supply `constants`.
+ */
+function readWithoutBlocking() {
+    const nonBlocking = fsConstants.O_NONBLOCK;
+    return fsConstants.O_RDONLY | (nonBlocking ?? 0);
+}
+/** Throw {@link TextTooLargeError} for a size no decode can hold. */
+function refuseUndecodableSize(byteLength) {
+    if (exceedsDecodableLength(byteLength))
+        throw new TextTooLargeError(byteLength);
+}
+/**
+ * Open `filePath` for reading without ever blocking on it: a named pipe, socket
+ * or device is refused (`EFTYPE`) and its handle closed, so only a regular file
+ * (or a directory, which the read refuses itself) comes back. The open a caller
+ * uses to PROVE a source readable before copying it — a bare `open(path, 'r')`
+ * of a pipe waits for a writer forever.
+ *
+ * @param filePath - Path to open
+ * @returns The open handle; the caller closes it
+ * @throws an `EFTYPE` errno for a special file, and whatever `open` throws otherwise
+ */
+export async function openForReading(filePath) {
+    const handle = await open(filePath, readWithoutBlocking());
+    try {
+        refuseSpecialFile(await handle.stat(), filePath);
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/**
+ * Read a file's raw bytes for decoding — refusing, by `stat` and before reading
+ * a byte, one too large to decode at all.
+ *
+ * The one read path for "bytes that are about to go through
+ * {@link decodeTextContent}": {@link readTextContent} uses it, and so does
+ * `readContentWithKey` in `@vibe-agent-toolkit/resources`, which needs the raw
+ * bytes as well to key them. Without the stat, a 966 MB file is read whole and
+ * only then refused by the decoder, and past 2 GiB `readFile` fails first with
+ * its own `ERR_FS_FILE_TOO_LARGE` — two different errors for one fact.
+ *
+ * The size comes from `fstat` on the handle that is then read, not from a
+ * separate `stat` of the path, so a rename between the two cannot substitute
+ * another file. A file that GROWS past the limit after the `fstat` still reaches
+ * the decoder, which raises the same {@link TextTooLargeError}.
+ *
+ * @param filePath - Path to read
+ * @returns The file's bytes
+ * @throws {@link TextTooLargeError} when the file is past {@link MAX_DECODABLE_BYTES},
+ *   an `EFTYPE` errno when it is not a regular file, and whatever `open`/`readFile` throw otherwise
+ */
+export async function readDecodableBytes(filePath) {
+    const handle = await openForReading(filePath);
+    try {
+        refuseUndecodableSize((await handle.stat()).size);
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
 }
 //# sourceMappingURL=text-file.js.map