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

package/README.md

@@ -25,10 +25,10 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 | Subpath | Contents | Node builtins reached | Third-party | Resolves with zero deps installed? |
 |---|---|---|---|---|
 | `./path` | `safePath`, `toForwardSlash`, `toForwardSlashAnyPlatform`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `relativeEscapesRoot`, `isSingleFsSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
-| `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted | **none** | — | **yes** |
+| `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted. `TextTooLargeError` (`TEXT_TOO_LARGE`) when the engine refuses a string that long | **none** | — | **yes** |
 | `./zod` | `ZodTypeNames`, `getZodTypeName`, `isZodType`, `unwrapZodType`, `isZodOptional`, `isZodNullable` | **none** | — | **yes** |
 | `./glob` | `isGlob`, static base extraction, magic remainder | `path` only | — | **yes** |
-| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync` | `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
+| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync`, `readDecodableBytes` (refuses a file past `MAX_DECODABLE_BYTES` by `fstat`, before reading it), `exceedsDecodableLength`, `MAX_DECODABLE_BYTES`, `TextTooLargeError` | `buffer`, `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
 | `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `createTempDir`, `removeTempDir`, `tempDirTracker`, `CANNOT_DENY_READS`, `buildHostileTree`, `HOSTILE_NAMES`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
 | `./asset` | `resolveAssetReference` — paths and npm bare specifiers | `fs`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./yaml` | `updateYamlIn`, `verifyConfinedYamlEdit` — byte-surgical YAML edits | **none** | `yaml` | no — needs `yaml` |

package/dist/env-flag.d.ts

@@ -20,21 +20,27 @@
  * needs it rather than speculatively. That second package arrived:
  * `packages/cli`'s `projectionStoreSelected()` reads the same `VAT_CACHE` the
  * `resources` parse cache does, and two independent readings of one variable is
- * the defect, not the fix. The four consumers today:
+ * the defect, not the fix. The consumers today:
  *
  * | Caller | Variable | Reads `undefined` as | Why |
  * |---|---|---|---|
- * | `link-auth/resolve-token.ts` | `VAT_LINKAUTH_ALLOW_COMMAND` | **deny** | gates a capability — fail closed |
+ * | `resources/link-auth/resolve-token.ts` | `VAT_LINKAUTH_ALLOW_COMMAND` | **deny** | gates a capability — fail closed |
  * | `resources/parse-cache.ts` | `VAT_CACHE` | cache stays on | gates a cache — an unreadable value must not silently change behaviour |
  * | `cli/utils/projection-store.ts` | `VAT_CACHE` | not a veto | same variable, same reading, one implementation |
  * | `cli/utils/projection-store.ts` | `VAT_PROJECTION_STORE` | not a veto | the projection store is ON by default; only an explicit off spelling (or an empty value, which that call site handles before asking) turns it off |
+ * | `resources/parse-dispatcher.ts` | `VAT_PARSE_POOL` | pool stays on | gates a measured speed-up — only an explicit off spelling disables it; a typo must not silently cost it |
  *
  * Same parser, different safe sides, each chosen at its own call site. That is
  * the contract; do not move a default in here.
  *
- * 🔑 The last two rows are the interesting pair: one variable defaults OFF and
- * the other defaults ON, and both are still read through this one function,
- * because what it answers is not "is this on" but "did the operator say no".
+ * 🔑 The two `projection-store.ts` rows are the interesting pair: one variable
+ * defaults OFF and the other defaults ON, and both are still read through this
+ * one function, because what it answers is not "is this on" but "did the
+ * operator say no".
+ *
+ * The table is asserted both ways, per (file, variable), against every
+ * `parseEnvBoolean` call (aliased imports included) in every package's `src` by
+ * `test/env-flag.test.ts`.
  */
 /**
  * Parse an env value as a boolean.

package/dist/env-flag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-flag.d.ts","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAM5E"}
+{"version":3,"file":"env-flag.d.ts","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAM5E"}

package/dist/env-flag.js

@@ -20,21 +20,27 @@
  * needs it rather than speculatively. That second package arrived:
  * `packages/cli`'s `projectionStoreSelected()` reads the same `VAT_CACHE` the
  * `resources` parse cache does, and two independent readings of one variable is
- * the defect, not the fix. The four consumers today:
+ * the defect, not the fix. The consumers today:
  *
  * | Caller | Variable | Reads `undefined` as | Why |
  * |---|---|---|---|
- * | `link-auth/resolve-token.ts` | `VAT_LINKAUTH_ALLOW_COMMAND` | **deny** | gates a capability — fail closed |
+ * | `resources/link-auth/resolve-token.ts` | `VAT_LINKAUTH_ALLOW_COMMAND` | **deny** | gates a capability — fail closed |
  * | `resources/parse-cache.ts` | `VAT_CACHE` | cache stays on | gates a cache — an unreadable value must not silently change behaviour |
  * | `cli/utils/projection-store.ts` | `VAT_CACHE` | not a veto | same variable, same reading, one implementation |
  * | `cli/utils/projection-store.ts` | `VAT_PROJECTION_STORE` | not a veto | the projection store is ON by default; only an explicit off spelling (or an empty value, which that call site handles before asking) turns it off |
+ * | `resources/parse-dispatcher.ts` | `VAT_PARSE_POOL` | pool stays on | gates a measured speed-up — only an explicit off spelling disables it; a typo must not silently cost it |
  *
  * Same parser, different safe sides, each chosen at its own call site. That is
  * the contract; do not move a default in here.
  *
- * 🔑 The last two rows are the interesting pair: one variable defaults OFF and
- * the other defaults ON, and both are still read through this one function,
- * because what it answers is not "is this on" but "did the operator say no".
+ * 🔑 The two `projection-store.ts` rows are the interesting pair: one variable
+ * defaults OFF and the other defaults ON, and both are still read through this
+ * one function, because what it answers is not "is this on" but "did the
+ * operator say no".
+ *
+ * The table is asserted both ways, per (file, variable), against every
+ * `parseEnvBoolean` call (aliased imports included) in every package's `src` by
+ * `test/env-flag.test.ts`.
  */
 const TRUE_SPELLINGS = new Set(['1', 'true', 'yes', 'y', 'on']);
 const FALSE_SPELLINGS = new Set(['0', 'false', 'no', 'n', 'off']);

package/dist/env-flag.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-flag.js","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACrF,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"env-flag.js","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACrF,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/fs.d.ts

@@ -8,7 +8,8 @@
  * `@vibe-agent-toolkit/utils/path` instead — it is dramatically cheaper.
  */
 export { normalizePath, normalizedTmpdir, mkdirSyncReal, resolveFromImportMeta, dynamicImportPath, } from './path-utils.js';
-export { readTextContent, readTextContentSync } from './text-file.js';
+export { exceedsDecodableLength, MAX_DECODABLE_BYTES, readDecodableBytes, readTextContent, readTextContentSync, } from './text-file.js';
+export { TextTooLargeError } from './text-content.js';
 export type { DecodedText, EncodingSource, TextEncoding, TextProvenance } from './text-content.js';
 export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
 export { copyDirectory, DirectorySpellingIndex, fillPathSpellings, fillRealpaths, FsLookupCache, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKnG,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GACd,MAAM,eAAe,CAAC"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKnG,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GACd,MAAM,eAAe,CAAC"}

package/dist/fs.js

@@ -11,7 +11,8 @@ export { normalizePath, normalizedTmpdir, mkdirSyncReal, resolveFromImportMeta,
 // Read a file and decode it through the one content-decoding seam. The DECISION
 // about what the bytes say is pure and lives on `./text`; these two are that
 // plus a `readFile`, which is why they are here and not there.
-export { readTextContent, readTextContentSync } from './text-file.js';
+export { exceedsDecodableLength, MAX_DECODABLE_BYTES, readDecodableBytes, readTextContent, readTextContentSync, } from './text-file.js';
+export { TextTooLargeError } from './text-content.js';
 // Two materialized columns, each a fill+judge pair and nothing else. In both the
 // row IS the answer, so the row lookup — `pathSpellingFrom`, `realpathFrom` — is
 // itself the judge and is exported. See `index.ts` for the full reasoning.

package/dist/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,gFAAgF;AAChF,6EAA6E;AAC7E,+DAA+D;AAC/D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGtE,iFAAiF;AACjF,iFAAiF;AACjF,2EAA2E;AAC3E,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,gFAAgF;AAChF,6EAA6E;AAC7E,+DAA+D;AAC/D,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,iFAAiF;AACjF,iFAAiF;AACjF,2EAA2E;AAC3E,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC"}

package/dist/path-containment.d.ts

@@ -34,6 +34,21 @@
  *   inside the root. A create sink proceeds; a delete sink has nothing to do.
  */
 export type Containment = 'inside' | 'outside' | 'absent';
+/**
+ * The canonical (realpath) spelling of `target`, whether or not it exists.
+ *
+ * The same canonicalization {@link isUnderRoot} applies to both of its sides,
+ * exposed for a caller that must COMPARE two spellings rather than ask a
+ * containment question — a root discovered from the physical `process.cwd()`
+ * against a path the operator typed through a symlink (macOS `/tmp` →
+ * `/private/tmp`). A missing target is canonicalized from its deepest existing
+ * ancestor with the missing tail re-appended.
+ *
+ * @param target - Absolute, or relative to cwd; either separator
+ * @returns The canonical spelling, forward-slashed
+ * @throws When the OS refuses to examine the path for any reason but absence
+ */
+export declare function canonicalPath(target: string): string;
 /**
  * Is `candidate` strictly under `root`, as the filesystem judges it?
  *

package/dist/path-containment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-containment.d.ts","sourceRoot":"","sources":["../src/path-containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAkD1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAQxE"}
+{"version":3,"file":"path-containment.d.ts","sourceRoot":"","sources":["../src/path-containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAuC1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAQxE"}

package/dist/path-containment.js

@@ -61,6 +61,23 @@ function canonicalFromAncestor(target) {
         candidate = parent;
     }
 }
+/**
+ * The canonical (realpath) spelling of `target`, whether or not it exists.
+ *
+ * The same canonicalization {@link isUnderRoot} applies to both of its sides,
+ * exposed for a caller that must COMPARE two spellings rather than ask a
+ * containment question — a root discovered from the physical `process.cwd()`
+ * against a path the operator typed through a symlink (macOS `/tmp` →
+ * `/private/tmp`). A missing target is canonicalized from its deepest existing
+ * ancestor with the missing tail re-appended.
+ *
+ * @param target - Absolute, or relative to cwd; either separator
+ * @returns The canonical spelling, forward-slashed
+ * @throws When the OS refuses to examine the path for any reason but absence
+ */
+export function canonicalPath(target) {
+    return canonicalFromAncestor(target).canonical;
+}
 /** Whether an entry (a file, a directory, or a link — dangling or not) is at `p`. */
 function entryExists(p) {
     try {

package/dist/path-containment.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-containment.js","sourceRoot":"","sources":["../src/path-containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgB1E;;;;;;;;;;;;;;GAcG;AACH,SAAS,qBAAqB,CAAC,MAAc;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC;gBAC9E,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;aAC7B,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QACvD,0EAA0E;QAC1E,0EAA0E;QAC1E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAChD,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1C,SAAS,GAAG,MAAM,CAAC;IACrB,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC;QACH,SAAS,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAAiB;IACzD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;IACvD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"path-containment.js","sourceRoot":"","sources":["../src/path-containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgB1E;;;;;;;;;;;;;;GAcG;AACH,SAAS,qBAAqB,CAAC,MAAc;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC;gBAC9E,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;aAC7B,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QACvD,0EAA0E;QAC1E,0EAA0E;QAC1E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAChD,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1C,SAAS,GAAG,MAAM,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED,qFAAqF;AACrF,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC;QACH,SAAS,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAAiB;IACzD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;IACvD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC7C,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,10 +14,10 @@
  * 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 DecodedText } from './text-content.js';
 /**
@@ -25,7 +25,8 @@ import { type DecodedText } from './text-content.js';
  *
  * @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 +40,45 @@ 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;
+/**
+ * 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},
+ *   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;AAMH,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,CAQjE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAoC,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElE;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1E"}

package/dist/text-file.js

@@ -14,20 +14,22 @@
  * 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, fstatSync, openSync, readFileSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+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 +38,81 @@ 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, 'r');
+    try {
+        refuseUndecodableSize(fstatSync(handle).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;
+}
+/**
+ * Throw {@link TextTooLargeError} for a size no decode can hold.
+ *
+ * @param byteLength - The content's size in bytes
+ */
+function refuseUndecodableSize(byteLength) {
+    if (exceedsDecodableLength(byteLength))
+        throw new TextTooLargeError(byteLength);
+}
+/**
+ * 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},
+ *   and whatever `open`/`readFile` throw otherwise
+ */
+export async function readDecodableBytes(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        refuseUndecodableSize((await handle.stat()).size);
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
 }
 //# sourceMappingURL=text-file.js.map

package/dist/text-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"text-file.js","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,OAAO,iBAAiB,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,OAAO,iBAAiB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"text-file.js","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,OAAO,iBAAiB,CAAC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,iBAAiB,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAW,SAAS,CAAC,iBAAiB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,OAAO,UAAU,GAAG,mBAAmB,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,UAAkB;IAC/C,IAAI,sBAAsB,CAAC,UAAU,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,UAAU,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB;IACvD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,qBAAqB,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/text.d.ts

@@ -12,5 +12,5 @@
  * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
  * `readFile`.
  */
-export { decodeTextContent, type DecodedText, type EncodingSource, type TextEncoding, type TextProvenance, } from './text-content.js';
+export { decodeTextContent, type DecodedText, type EncodingSource, type TextEncoding, type TextProvenance, TextTooLargeError, } from './text-content.js';
 //# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/text.js

@@ -12,5 +12,5 @@
  * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
  * `readFile`.
  */
-export { decodeTextContent, } from './text-content.js';
+export { decodeTextContent, TextTooLargeError, } from './text-content.js';
 //# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,GAKlB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EAKjB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/eslint/rules/no-literal-process-exit.cjs

@@ -20,17 +20,69 @@
  * segment boundary via `exempt-path-matcher.cjs`; give the full repo-relative
  * path, not a bare basename.
  *
+ * ## Option `derived` — the code is DERIVED from the document, not chosen
+ *
+ * Naming a member is not enough. `process.exit(refused ? ExitCode.FINDINGS :
+ * ExitCode.OK)` names members and still re-decides, beside the document, what
+ * the document means — and one outcome shipped with different codes in
+ * different verbs that way (a budget kill 1-or-2 by timing; an unreadable root
+ * 2 in one verb and 1 in another). Under `derived.paths`:
+ *
+ * - `ExitCode.FINDINGS` may not be NAMED at all. "What it examined failed its
+ *   gate" is a claim about a published document, so it comes from
+ *   `exitCodeForReport(document)` (`@vibe-agent-toolkit/schema`) and nowhere else.
+ * - `process.exit(x)` / `process.exitCode = x` takes `ExitCode.OK`,
+ *   `ExitCode.ERROR`, or a call to one of `derived.calls` (the derivations:
+ *   `exitCodeForReport`, `exitCodeOfChild`, …). A ternary, a variable or a
+ *   forwarded field is a code decided somewhere this rule cannot see.
+ * - `derived.legacy` names the files not yet migrated. It is a RATCHET asserted
+ *   both ways: a listed file that no longer decides a code by hand is itself an
+ *   error (`staleLegacy`), so the list can only shrink and never holds a dead entry.
+ *
+ * ⚠️ What this cannot see: a document verb ending on a bare `ExitCode.OK` over a
+ * document that says `error`. That is a runtime fact, pinned by the exit-code
+ * matrix system test, not a syntactic one.
+ *
  * @example
  * // BAD — 1 means what, exactly?
  * process.exit(1);
  *
- * // GOOD — the meaning is the code
- * process.exit(ExitCode.FINDINGS);
+ * // BAD under `derived` — the call site decides what the document means
+ * process.exit(errors > 0 ? ExitCode.FINDINGS : ExitCode.OK);
+ *
+ * // GOOD — derived from what was published
+ * process.exit(exitCodeForReport(report));
  */
 
 'use strict';
 
-const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+const { createExemptDirectoryMatcher, createExemptPathMatcher, isTestFile } = require('./exempt-path-matcher.cjs');
+
+/** The members a call site may name outright: neither is a claim about a document. */
+const UNDERIVED_MEMBERS = new Set(['OK', 'ERROR']);
+
+/** Whether `node` is `ExitCode.<name>` (non-computed). */
+function isExitCodeMember(node, name) {
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object.type === 'Identifier' &&
+    node.object.name === 'ExitCode' &&
+    node.property.type === 'Identifier' &&
+    (name === undefined ? UNDERIVED_MEMBERS.has(node.property.name) : node.property.name === name)
+  );
+}
+
+/** The called function's own name — `f(…)` or `x.f(…)` — or null. */
+function calleeName(node) {
+  if (node.type !== 'CallExpression') return null;
+  const { callee } = node;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+    return callee.property.name;
+  }
+  return null;
+}
 
 /** Whether `node` is the member expression `process.<name>` (non-computed). */
 function isProcessMember(node, name) {
@@ -84,6 +136,16 @@ module.exports = {
         type: 'object',
         properties: {
           allow: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          derived: {
+            type: 'object',
+            properties: {
+              paths: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+              calls: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+              legacy: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+            },
+            required: ['paths', 'calls', 'legacy'],
+            additionalProperties: false,
+          },
         },
         additionalProperties: false,
       },
@@ -96,34 +158,73 @@ module.exports = {
       literalExitCode:
         'process.exitCode = {{literal}} re-decides the exit contract at this site. Assign an ' +
         'ExitCode member from @vibe-agent-toolkit/schema instead.',
+      findingsNotDerived:
+        'ExitCode.FINDINGS is a claim about a published document ("what it examined failed its ' +
+        'gate"). Derive it: process.exit(exitCodeForReport(document)) — never name it at a call site.',
+      exitNotDerived:
+        'This exit code is decided here, beside the document, where it can disagree with it. Exit ' +
+        'with ExitCode.OK, ExitCode.ERROR, or a derivation: {{calls}}.',
+      staleLegacy:
+        'This file is listed in no-literal-process-exit derived.legacy but decides no exit code by ' +
+        'hand any more. Remove it from the list — the ratchet only shrinks.',
     },
   },
 
   create(context) {
     const allow = context.options?.[0]?.allow ?? [];
+    const derived = context.options?.[0]?.derived;
     const filename = context.filename ?? context.getFilename();
     if (createExemptPathMatcher(allow)(filename)) {
       return {};
     }
 
+    const inDerived = derived !== undefined
+      && !isTestFile(filename)
+      && createExemptDirectoryMatcher(derived.paths)(filename);
+    const isLegacy = inDerived && createExemptPathMatcher(derived.legacy)(filename);
+    const derivations = new Set(derived?.calls ?? []);
+    let handDecided = 0;
+
+    /** Report a derivation violation — or, in a legacy file, only count it. */
+    function reportDerived(node, messageId) {
+      handDecided += 1;
+      if (isLegacy) return;
+      context.report({ node, messageId, data: { calls: [...derivations].join(', ') } });
+    }
+
+    /** @returns {boolean} Whether a literal was reported (so nothing else is). */
     function reportLiteral(node, expr, messageId) {
       const leaf = numericLiteralLeaf(expr);
-      if (leaf !== null) {
-        context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
-      }
+      if (leaf === null) return false;
+      context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
+      return true;
+    }
+
+    function checkExitValue(node, expr, literalMessageId) {
+      if (reportLiteral(node, expr, literalMessageId) || !inDerived) return;
+      if (isExitCodeMember(expr) || derivations.has(calleeName(expr))) return;
+      // `ExitCode.FINDINGS` itself is reported by the member visitor below.
+      if (isExitCodeMember(expr, 'FINDINGS')) return;
+      reportDerived(node, 'exitNotDerived');
     }
 
     return {
       CallExpression(node) {
         if (isProcessMember(node.callee, 'exit') && node.arguments.length > 0) {
-          reportLiteral(node, node.arguments[0], 'literalExit');
+          checkExitValue(node, node.arguments[0], 'literalExit');
         }
       },
       AssignmentExpression(node) {
         if (isProcessMember(node.left, 'exitCode')) {
-          reportLiteral(node, node.right, 'literalExitCode');
+          checkExitValue(node, node.right, 'literalExitCode');
         }
       },
+      MemberExpression(node) {
+        if (inDerived && isExitCodeMember(node, 'FINDINGS')) reportDerived(node, 'findingsNotDerived');
+      },
+      'Program:exit'(node) {
+        if (isLegacy && handDecided === 0) context.report({ node, messageId: 'staleLegacy' });
+      },
     };
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.2.0-rc.10",
+  "version": "0.2.0-rc.11",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": [