rea-agents 6.3.0 → 6.4.0

package/dist/application/DoctorDiagnostics.js

@@ -65,7 +65,7 @@ const hostCheck = async (host) => {
             ? `${host.platform} ${host.architecture}`
             : `${linuxDistribution.id} ${linuxDistribution.versionId ?? "unknown"}`);
     return check("host", supported, detail, {
-        remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
+        remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, Omarchy, and the experimental Windows x64 Ghidra P0 boundary.",
         classification: "unsupported_host",
     });
 };

package/dist/application/EvidenceBundleCommands.js

@@ -3,22 +3,17 @@ import {} from "../domain/analysisErrorBase.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { compareBundles } from "../domain/bundleComparison.js";
-import { EvidenceLedger } from "./investigation/EvidenceLedger.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
-/** Validate and merge one bundle using the session Evidence ledger. */
+/** Validate a standalone bundle and report its complete record/revision counts. */
 export const importEvidenceBundleCommand = async (path) => {
     const loaded = await readEvidenceBundle(path);
     if (!loaded.ok)
         return loaded;
-    const ledger = createLedger();
-    const imported = ledger.import(loaded.value);
-    return imported.ok
-        ? ok({
-            imported: imported.value.recordsAdded,
-            unknowns_added: imported.value.unknownsAdded,
-            total: ledger.export().records.length,
-        })
-        : imported;
+    return ok({
+        imported: loaded.value.records.length,
+        unknowns_added: loaded.value.unknowns.length,
+        total: loaded.value.records.length,
+    });
 };
 /** Validate a source bundle and atomically export canonical bytes. */
 export const exportEvidenceBundleCommand = async (sourcePath, outputPath, overwrite) => {
@@ -46,7 +41,6 @@ export const compareEvidenceBundlesCommand = async (input) => {
         }));
     }
 };
-const createLedger = () => new EvidenceLedger();
 const projectWrite = (bundle, written) => written.ok
     ? ok({
         path: written.value.path,

package/dist/application/GeminiClientSettings.js

@@ -0,0 +1,139 @@
+import { realpath } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { stripComments } from "jsonc-parser";
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { clientConfigurationValuesEqual, clientRegistrationEntry, geminiServerPolicyBlock, parseGeminiMcpPolicy, } from "./ClientConfigurationDocument.js";
+import { readConfigurationFile, readConfigurationText, } from "./ClientConfigurationFiles.js";
+const folderTrustSchema = z
+    .object({
+    security: z
+        .object({
+        folderTrust: z
+            .object({ enabled: z.boolean().optional() })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const trustRulesSchema = z.record(z.string(), z.enum(["TRUST_FOLDER", "TRUST_PARENT", "DO_NOT_TRUST"]));
+const sourceFailure = (path, cause) => ({
+    kind: "malformed",
+    path,
+    detail: `Gemini settings in ${path} are malformed: ${cause instanceof Error ? cause.message : String(cause)}`,
+});
+// Gemini resolves symlinks when possible and compares macOS/Windows paths without case.
+const normalizedPath = async (path, platform) => {
+    const physical = await realpath(path).catch(() => path);
+    const absolute = resolve(physical).replaceAll("\\", "/");
+    return platform === "win32" || platform === "darwin"
+        ? absolute.toLowerCase()
+        : absolute;
+};
+const workspaceTrusted = async (settings, sources) => {
+    let enabled = true;
+    for (const { path, document } of sources) {
+        const parsed = folderTrustSchema.safeParse(document.document);
+        if (!parsed.success)
+            return err(sourceFailure(path, parsed.error));
+        enabled = parsed.data.security?.folderTrust?.enabled ?? enabled;
+    }
+    if (settings.trustOverride !== undefined)
+        return ok(settings.trustOverride);
+    if (!enabled)
+        return ok(true);
+    const text = await readConfigurationText(settings.trustedFoldersPath);
+    if (!text.ok)
+        return text;
+    if (text.value === undefined)
+        return ok(false);
+    let rules;
+    try {
+        // Gemini strips comments, but rejects trailing commas, BOMs and invalid trust levels.
+        rules = trustRulesSchema.parse(JSON.parse(stripComments(text.value)));
+    }
+    catch (cause) {
+        return err(sourceFailure(settings.trustedFoldersPath, cause));
+    }
+    const workspace = await normalizedPath(settings.workspaceDirectory, settings.platform);
+    let longest = -1;
+    let trusted = false;
+    for (const [path, level] of Object.entries(rules)) {
+        const effective = await normalizedPath(level === "TRUST_PARENT" ? dirname(path) : path, settings.platform);
+        if ((workspace === effective ||
+            workspace.startsWith(effective.endsWith("/") ? effective : `${effective}/`)) &&
+            path.length > longest) {
+            longest = path.length;
+            trusted = level !== "DO_NOT_TRUST";
+        }
+    }
+    return ok(trusted);
+};
+/** Check effective Gemini scopes while preserving their authority and source identity. */
+export const readClientPolicyBlock = async (client, userDocument, desiredRegistration) => {
+    if (client.name !== "gemini_cli" || client.geminiSettings === undefined)
+        return ok(undefined);
+    const settings = client.geminiSettings;
+    const sources = [];
+    const higher = [];
+    for (const path of [
+        settings.defaultsPath,
+        client.configPath,
+        settings.systemPath,
+    ]) {
+        const parsed = path === client.configPath && userDocument !== undefined
+            ? ok(userDocument)
+            : await readConfigurationFile(path, "json");
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value !== undefined)
+            sources.push({ path, document: parsed.value });
+    }
+    const workspace = await normalizedPath(settings.workspaceDirectory, settings.platform);
+    const home = await normalizedPath(dirname(dirname(client.configPath)), settings.platform);
+    if (workspace !== home) {
+        const path = resolve(settings.workspaceDirectory, ".gemini", "settings.json");
+        const document = await readConfigurationFile(path, "json");
+        if (!document.ok)
+            return document;
+        if (document.value !== undefined) {
+            const trusted = await workspaceTrusted(settings, sources);
+            if (!trusted.ok)
+                return trusted;
+            if (trusted.value) {
+                const source = { path, document: document.value };
+                const systemIndex = sources.findIndex((item) => item.path === settings.systemPath);
+                sources.splice(systemIndex < 0 ? sources.length : systemIndex, 0, source);
+                higher.push(source);
+            }
+        }
+    }
+    const system = sources.find(({ path }) => path === settings.systemPath);
+    if (system !== undefined)
+        higher.push(system);
+    const policies = [];
+    for (const { path, document } of sources) {
+        try {
+            policies.push(parseGeminiMcpPolicy(document));
+        }
+        catch (cause) {
+            return err(sourceFailure(path, cause));
+        }
+    }
+    const policy = geminiServerPolicyBlock(policies, PRODUCT_IDENTITY.mcpServerKey);
+    if (policy !== undefined)
+        return ok(`${policy} Settings sources: ${sources.map(({ path }) => path).join(", ")}.`);
+    // mcpServers uses shallow merge: the entire same-name definition is replaced.
+    const override = higher.findLast(({ document }) => Object.hasOwn(document.servers, PRODUCT_IDENTITY.mcpServerKey));
+    const desired = desiredRegistration ??
+        userDocument?.servers[PRODUCT_IDENTITY.mcpServerKey] ??
+        clientRegistrationEntry("json", npxRegistrationCommand(), {});
+    if (override !== undefined &&
+        !clientConfigurationValuesEqual(override.document.servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return ok(`Gemini mcpServers.${PRODUCT_IDENTITY.mcpServerKey} in ${override.path} overrides the user registration. Review that settings file before rerunning setup; REA does not modify system or workspace settings.`);
+    return ok(undefined);
+};

package/dist/application/HermesClientHome.js

@@ -0,0 +1,115 @@
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+/** An unresolved Hermes profile must not be configured as the default home. */
+export class HermesClientPathError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+        this.name = "HermesClientPathError";
+    }
+}
+const defaultDirectory = (home, platform, env) => {
+    const suffix = env.HERMES_DATA_DIR_SUFFIX ?? "";
+    return platform === "win32"
+        ? join(env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"), `hermes${suffix}`)
+        : join(home, `.hermes${suffix}`);
+};
+const expandedDirectory = (home, platform, env) => {
+    const override = env.HERMES_HOME?.trim();
+    if (!override)
+        return undefined;
+    const variables = override.replace(/\$(\w+|\{[^}]*\})/gu, (match, variable) => {
+        const key = variable.startsWith("{") ? variable.slice(1, -1) : variable;
+        return env[key] ?? match;
+    });
+    const expanded = platform === "win32"
+        ? variables.replace(/%([^%]+)%/gu, (match, variable) => env[variable] ?? match)
+        : variables;
+    if (expanded === "~")
+        return home;
+    if (expanded.startsWith("~/") ||
+        (platform === "win32" && expanded.startsWith("~\\")))
+        return join(home, expanded.slice(2));
+    return resolve(expanded);
+};
+const physicalPath = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+const within = (root, path) => {
+    const difference = relative(physicalPath(root), physicalPath(path));
+    return (difference === "" ||
+        (!isAbsolute(difference) &&
+            difference !== ".." &&
+            !difference.startsWith(`..${sep}`)));
+};
+const PROFILE_MARKERS = [
+    "config.yaml",
+    ".env",
+    "SOUL.md",
+    "profile.yaml",
+    "auth.json",
+    "state.db",
+];
+const RESERVED_PROFILES = new Set(["hermes", "test", "tmp", "root", "sudo"]);
+const liveProfile = (path) => {
+    try {
+        if (!statSync(path).isDirectory())
+            return false;
+        try {
+            statSync(join(dirname(path), ".deleted", basename(path)));
+            return false;
+        }
+        catch {
+            /* No tombstone. */
+        }
+        return PROFILE_MARKERS.some((marker) => {
+            try {
+                const status = lstatSync(join(path, marker));
+                return status.isFile() || status.isSymbolicLink();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+};
+/** Match Hermes CLI sticky-profile selection while retaining the configured path spelling. */
+export const resolveHermesClientHome = (home, platform, env) => {
+    const native = defaultDirectory(home, platform, env);
+    const root = expandedDirectory(home, platform, env) ?? native;
+    // An explicit named profile bypasses the root's sticky selection in Hermes CLI.
+    if (basename(dirname(root)) === "profiles")
+        return root;
+    const stickyRoot = within(native, root) ? native : root;
+    let name;
+    try {
+        // Python uses utf-8-sig and ignores unreadable / invalid-UTF8 active_profile files.
+        name = new TextDecoder("utf-8", { fatal: true })
+            .decode(readFileSync(join(stickyRoot, "active_profile")))
+            .trim();
+    }
+    catch {
+        return root;
+    }
+    if (name === "" || name === "default")
+        return root;
+    const canonical = name.toLowerCase();
+    if (canonical === "default")
+        return root;
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/u.test(canonical) ||
+        RESERVED_PROFILES.has(canonical))
+        throw new HermesClientPathError(join(stickyRoot, "active_profile"), `Invalid saved Hermes profile ${JSON.stringify(name)}. Run 'hermes profile use default' or repair active_profile.`);
+    const selected = join(root, "profiles", canonical);
+    if (!liveProfile(selected))
+        throw new HermesClientPathError(selected, `Saved Hermes profile ${JSON.stringify(name)} is missing, deleted, or has no profile identity. Run 'hermes profile use default' or restore that profile before configuring it.`);
+    return selected;
+};

package/dist/application/HopperDownload.js

@@ -0,0 +1,39 @@
+/** Maximum admitted vendor response bytes, shared by Hopper setup adapters. */
+export const HOPPER_DOWNLOAD_BYTES = 100_000_000;
+/** Bound observed response bytes before retaining them, including chunked bodies. */
+export const downloadHopperPackage = async (url, options = {}) => {
+    const deadline = AbortSignal.timeout(120_000);
+    const response = await fetch(url, {
+        headers: { accept: "application/json", "user-agent": "rea-installer" },
+        signal: options.signal === undefined
+            ? deadline
+            : AbortSignal.any([options.signal, deadline]),
+    });
+    const refused = { ok: false, bytes: new Uint8Array() };
+    if (!response.ok ||
+        Number(response.headers.get("content-length")) > HOPPER_DOWNLOAD_BYTES) {
+        await response.body?.cancel();
+        return refused;
+    }
+    if (response.body === null)
+        return { ok: true, bytes: new Uint8Array() };
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return { ok: true, bytes: Buffer.concat(chunks, bytes) };
+            if (chunk.value.byteLength > HOPPER_DOWNLOAD_BYTES - bytes) {
+                await reader.cancel();
+                return refused;
+            }
+            chunks.push(chunk.value);
+            bytes += chunk.value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+};

package/dist/application/InvestigationProviders.js

@@ -24,6 +24,12 @@ export const MANAGED_STATIC_PROVIDER = Object.freeze({
     name: "REA managed static analysis provider",
     version: "1",
 });
+/** Provider identity for portable, execution-free PE resource decoding. */
+export const PE_RESOURCES_PROVIDER = Object.freeze({
+    id: "rea-pe-resources",
+    name: "REA PE resource parser",
+    version: "1",
+});
 /** Provider identity for deterministic managed-code comparison workflows. */
 export const MANAGED_WORKFLOW_PROVIDER = {
     id: "rea-dotnet-workflows",

package/dist/application/JsonFiles.js

@@ -3,18 +3,19 @@ import { basename, dirname, resolve } from "node:path";
 import { EvidenceFileError } from "../domain/evidenceErrors.js";
 import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
-import { parseUtf8Json } from "./Utf8JsonInput.js";
-import { readRegularFile } from "./RegularFileRead.js";
+import { readJsonInputFile } from "./JsonInputFile.js";
 import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
 export const readJsonFile = async (path) => {
     const requestedPath = resolve(path);
     try {
-        const encoded = await readRegularFile(requestedPath);
-        const decoded = parseUtf8Json(encoded, "read_evidence_file", requestedPath);
+        const decoded = await readJsonInputFile(requestedPath, "read_evidence_file");
         if (!decoded.ok) {
+            if (decoded.error instanceof AnalysisResourceConstraintError)
+                return err(decoded.error);
             return err(new EvidenceFileError("read", "invalid-json", {
-                cause: decoded.cause,
+                cause: decoded.error.cause ??
+                    new SyntaxError(decoded.error.issues[0]?.message ?? decoded.error.message),
                 path: requestedPath,
             }));
         }

package/dist/{cliJsonFile.js → application/JsonInputFile.js}

@@ -3,35 +3,46 @@ import { pipeline } from "node:stream/promises";
 import { getHeapStatistics } from "node:v8";
 import parser from "stream-json/parser.js";
 import streamValues from "stream-json/streamers/stream-values.js";
-import { withRegularFile } from "./application/RegularFileRead.js";
-import { JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, } from "./application/Utf8JsonInput.js";
-import { AnalysisInputError, AnalysisResourceConstraintError, } from "./domain/analysisErrorCore.js";
-import { err, ok } from "./domain/result.js";
+import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import { withRegularFile } from "./RegularFileRead.js";
+import { JSON_BYTE_ORDER_MARK_MESSAGE, JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, } from "./Utf8JsonInput.js";
+import { AnalysisInputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
 const READ_CHUNK_BYTES = 64 * 1024;
-const PACKED_STRING_PART_CODE_UNITS = 64 * 1024;
+const PACKED_TOKEN_PART_CODE_UNITS = 64 * 1024;
 // Retain native-parser speed for modest inputs while bounding its extra copies.
 // This selects an implementation; larger files remain accepted through streaming.
 const NATIVE_PARSE_READ_BUDGET = 8 * 1024 * 1024;
+/** Keep native parsing only when input copies and value expansion fit live headroom. */
+const nativeParseFits = (inputBytes) => inputBytes <= NATIVE_PARSE_READ_BUDGET &&
+    // The assembler estimate reserves up to 128 bytes per two-byte container.
+    // Allow that 64x expansion plus byte/text copies before native JSON.parse,
+    // whose individual container allocations cannot be intercepted.
+    inputBytes * 72 + READ_CHUNK_BYTES <=
+        getHeapStatistics().total_available_size;
 /** Parse strict UTF-8 JSON without requiring a whole-document string. */
-export const readCliJsonFile = (path, operation, signal) => withRegularFile(path, async (handle, stats) => {
+export const readJsonInputFile = (path, operation, signal) => withRegularFile(path, async (handle, stats) => {
     let found = false;
     let value;
     try {
-        const prefix = stats.size <= NATIVE_PARSE_READ_BUDGET
+        const prefix = nativeParseFits(stats.size)
             ? await readPrefix(handle, stats.size + 1, signal)
             : undefined;
-        if (prefix?.complete === true) {
-            const parsed = parseUtf8Json(prefix.bytes, operation, path, "cli-json-input");
+        if (prefix !== undefined) {
+            if (!prefix.complete || prefix.bytes.length !== stats.size)
+                throw new RegularFileChangedError(path);
+            const parsed = parseUtf8Json(prefix.bytes, operation, path, "json-file-input");
             return parsed.ok
                 ? ok(parsed.value)
                 : err(invalidJson(operation, parsed.error, parsed.cause));
         }
-        await pipeline(decodedChunks(handle, signal, prefix?.bytes), parser.asStream({
+        await pipeline(decodedChunks(handle, stats.size, path, signal), parser.asStream({
             jsonStreaming: false,
             streamValues: false,
             packKeys: false,
             packStrings: false,
-        }), packJsonStrings(operation, stats.size), streamValues.asStream(), async (rows) => {
+            packNumbers: false,
+        }), packJsonScalars(operation, stats.size, path), admitJsonAssembly(operation, stats.size, path), streamValues.asStream(), async (rows) => {
             for await (const row of rows) {
                 if (found ||
                     typeof row !== "object" ||
@@ -62,7 +73,8 @@ export const readCliJsonFile = (path, operation, signal) => withRegularFile(path
             ((cause instanceof RangeError &&
                 cause.message === "Invalid string length") ||
                 ("code" in cause && cause.code === "ERR_STRING_TOO_LONG")))
-            return err(new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string exceeds the runtime string limit", {
+            return err(new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string or number token exceeds the runtime string limit", {
+                input_path: path,
                 input_file_bytes: stats.size,
                 max_string_code_units: constants.MAX_STRING_LENGTH,
             }, {
@@ -71,8 +83,8 @@ export const readCliJsonFile = (path, operation, signal) => withRegularFile(path
             }));
         throw cause;
     }
-}, signal);
-const packJsonStrings = (operation, inputFileBytes) => async function* (tokens) {
+}, { signal });
+const packJsonScalars = (operation, inputFileBytes, path) => async function* (tokens) {
     let kind;
     let length = 0;
     let value = "";
@@ -86,21 +98,25 @@ const packJsonStrings = (operation, inputFileBytes) => async function* (tokens)
             case "startString":
                 kind = token.name === "startKey" ? "keyValue" : "stringValue";
                 break;
+            case "startNumber":
+                kind = "numberValue";
+                break;
+            case "numberChunk":
             case "stringChunk":
                 if (kind === undefined ||
                     !("value" in token) ||
                     typeof token.value !== "string")
-                    throw new Error("Unexpected JSON string fragment");
+                    throw new Error("Unexpected JSON scalar fragment");
                 length += token.value.length;
                 if (length > constants.MAX_STRING_LENGTH)
                     throw new RangeError("Invalid string length");
                 parts.push(token.value);
                 partLength += token.value.length;
-                if (partLength >= PACKED_STRING_PART_CODE_UNITS) {
+                if (partLength >= PACKED_TOKEN_PART_CODE_UNITS) {
                     // The tokenizer emits short fragments. Coalesce them before retaining
-                    // a string so millions of substring/rope nodes cannot exhaust the heap
+                    // a scalar so millions of substring/rope nodes cannot exhaust the heap
                     // before the native string-length constraint can be reported.
-                    requireStringAssemblyHeadroom(operation, inputFileBytes, length);
+                    requireStringAssemblyHeadroom(operation, inputFileBytes, path, length);
                     value += parts.join("");
                     parts = [];
                     partLength = 0;
@@ -108,9 +124,10 @@ const packJsonStrings = (operation, inputFileBytes) => async function* (tokens)
                 break;
             case "endKey":
             case "endString":
+            case "endNumber":
                 if (kind === undefined)
-                    throw new Error("Unexpected JSON string end");
-                requireStringAssemblyHeadroom(operation, inputFileBytes, length);
+                    throw new Error("Unexpected JSON scalar end");
+                requireStringAssemblyHeadroom(operation, inputFileBytes, path, length);
                 yield { name: kind, value: value + parts.join("") };
                 kind = undefined;
                 length = 0;
@@ -123,15 +140,58 @@ const packJsonStrings = (operation, inputFileBytes) => async function* (tokens)
         }
     }
 };
-const requireStringAssemblyHeadroom = (operation, inputFileBytes, stringCodeUnits) => {
-    if (stringCodeUnits < PACKED_STRING_PART_CODE_UNITS)
+/** Admit the retained value graph before the upstream assembler grows it. */
+const admitJsonAssembly = (operation, inputFileBytes, path) => async function* (tokens) {
+    let projectedBytes = 0;
+    let nextCheck = 0;
+    for await (const token of tokens) {
+        if (typeof token !== "object" || token === null || !("name" in token))
+            throw new Error("Unexpected JSON assembly token");
+        if (token.name === "startObject" || token.name === "startArray") {
+            projectedBytes += 128;
+        }
+        else if (token.name === "keyValue" || token.name === "stringValue") {
+            if (!("value" in token) || typeof token.value !== "string")
+                throw new Error("Unexpected packed JSON string");
+            projectedBytes += 64 + token.value.length * 2;
+        }
+        else if (token.name === "numberValue" ||
+            token.name === "nullValue" ||
+            token.name === "trueValue" ||
+            token.name === "falseValue") {
+            projectedBytes += 64;
+        }
+        if (projectedBytes >= nextCheck) {
+            const heap = getHeapStatistics();
+            // Conservative capacity for containers, property/array slots and UTF-16
+            // values. Keep another whole projection available for container growth,
+            // plus the next chunk of estimates between samples. This is admission
+            // against live runtime headroom, not a fixed document-size policy.
+            const requiredBytes = projectedBytes + READ_CHUNK_BYTES;
+            if (requiredBytes > heap.total_available_size)
+                throw new AnalysisResourceConstraintError(operation, "memory", "Insufficient heap headroom to materialize the complete JSON value", {
+                    input_path: path,
+                    input_file_bytes: inputFileBytes,
+                    projected_value_bytes: projectedBytes,
+                    assembly_headroom_bytes: requiredBytes,
+                    available_heap_bytes: heap.total_available_size,
+                    heap_size_limit_bytes: heap.heap_size_limit,
+                }, { remediationAction: JSON_INPUT_RESOURCE_REMEDIATION });
+            nextCheck = projectedBytes + READ_CHUNK_BYTES;
+        }
+        yield token;
+    }
+};
+const requireStringAssemblyHeadroom = (operation, inputFileBytes, path, stringCodeUnits) => {
+    if (stringCodeUnits < PACKED_TOKEN_PART_CODE_UNITS)
         return;
     const heap = getHeapStatistics();
     // Concatenation or key interning may flatten the retained rope. Reserve its
     // UTF-16 representation and the next coalesced part before that allocation.
-    const requiredBytes = 2 * (stringCodeUnits + PACKED_STRING_PART_CODE_UNITS);
+    const requiredBytes = 2 * (stringCodeUnits + PACKED_TOKEN_PART_CODE_UNITS);
     if (requiredBytes > heap.total_available_size)
         throw new AnalysisResourceConstraintError(operation, "memory", "Insufficient heap headroom to assemble a complete JSON string", {
+            input_path: path,
             input_file_bytes: inputFileBytes,
             string_code_units: stringCodeUnits,
             string_assembly_headroom_bytes: requiredBytes,
@@ -141,25 +201,39 @@ const requireStringAssemblyHeadroom = (operation, inputFileBytes, stringCodeUnit
             remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
         });
 };
-async function* decodedChunks(handle, signal, prefix) {
+async function* decodedChunks(handle, admittedBytes, path, signal) {
     const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
-    if (prefix !== undefined)
-        for (let offset = 0; offset < prefix.length; offset += READ_CHUNK_BYTES) {
-            signal?.throwIfAborted();
-            yield decoder.decode(prefix.subarray(offset, offset + READ_CHUNK_BYTES), {
-                stream: true,
-            });
+    let leading = true;
+    const checked = (text) => {
+        if (leading && text.length > 0) {
+            leading = false;
+            if (text.startsWith("\uFEFF"))
+                throw new JsonByteOrderMarkError();
         }
+        return text;
+    };
     const bytes = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+    let observedBytes = 0;
     while (true) {
         signal?.throwIfAborted();
-        const read = await handle.read(bytes, 0, bytes.length, null);
+        const read = await handle.read(bytes, 0, Math.min(bytes.length, admittedBytes - observedBytes + 1), null);
         signal?.throwIfAborted();
         if (read.bytesRead === 0)
             break;
-        yield decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true });
+        observedBytes += read.bytesRead;
+        if (observedBytes > admittedBytes)
+            throw new RegularFileChangedError(path);
+        yield checked(decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true }));
+    }
+    if (observedBytes !== admittedBytes)
+        throw new RegularFileChangedError(path);
+    yield checked(decoder.decode());
+}
+/** A streamed JSON file begins with a byte-order mark; reported as invalid JSON. */
+class JsonByteOrderMarkError extends SyntaxError {
+    constructor() {
+        super(JSON_BYTE_ORDER_MARK_MESSAGE);
     }
-    yield decoder.decode();
 }
 const readPrefix = async (handle, size, signal) => {
     const bytes = Buffer.allocUnsafe(size);
@@ -172,8 +246,7 @@ const readPrefix = async (handle, size, signal) => {
             return { bytes: bytes.subarray(0, offset), complete: true };
         offset += read.bytesRead;
     }
-    // The file grew after admission. Continue from this same handle, preserving
-    // the prefix already read rather than reopening or dropping its bytes.
+    // One byte beyond the admitted extent proves the selected file changed.
     return { bytes, complete: false };
 };
 const invalidJson = (operation, message, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [{ path: [], reason: "invalid_format", expected: "JSON", message }]);