rea-agents 6.4.0 → 6.7.0

package/dist/ghidra/GhidraTargetSnapshot.js

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { open, rm } from "node:fs/promises";
+import { open } from "node:fs/promises";
 import { extname, join } from "node:path";
-import { Transform } from "node:stream";
-import { pipeline } from "node:stream/promises";
+import { withArtifactRegularFile, withArtifactFileHandle, assertArtifactReadActive, mapArtifactFileFailure, } from "../artifacts/ArtifactFileOperation.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";
+import { NonRegularFileReadError, sameRegularFileState, } from "../filesystem/RegularFile.js";
 import { AnalysisArtifactChangedError, AnalysisAccessDeniedError, } from "../domain/analysisErrorCore.js";
-import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { WindowsSnapshotCancelledError, windowsPrivateRuntime, } from "../windows/WindowsPrivateRuntime.js";
 /** Copy one target and require its bytes to match the parsed target identity. */
 export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expectedSha256, options = {}) => {
     if (!/^[a-f0-9]{64}$/u.test(expectedSha256))
@@ -13,7 +15,16 @@ export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expect
     const suffix = safeExtension(sourcePath);
     const snapshotPath = join(runtimeRoot, `target-${expectedSha256.slice(0, 12)}${suffix}`);
     if ((options.platform ?? process.platform) === "win32") {
-        const observed = await windowsPrivateRuntime(runtimeRoot).snapshot(sourcePath, `target-${expectedSha256.slice(0, 12)}${suffix}`, options.signal);
+        const observed = await windowsPrivateRuntime(runtimeRoot)
+            .snapshot(sourcePath, `target-${expectedSha256.slice(0, 12)}${suffix}`, options.signal)
+            .catch((cause) => {
+            if (cause instanceof WindowsSnapshotCancelledError)
+                throw new ArtifactReaderFailure("cancelled", cause.message, {
+                    cause,
+                    cancellation: { reason: cause.reason },
+                });
+            throw cause;
+        });
         if (observed.sha256 !== expectedSha256)
             throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
         return {
@@ -22,57 +33,63 @@ export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expect
             admission: { source: observed.source, snapshot: observed.snapshot },
         };
     }
-    let source;
-    let destination;
+    const resources = options.resourceScope ?? new ArtifactResourceScope();
     try {
-        source = await openSnapshotSource(sourcePath);
-        if (!(await source.stat()).isFile())
-            throw new AnalysisArtifactChangedError("open_binary", sourcePath, "The selected Ghidra source is no longer a regular file");
-        destination = await open(snapshotPath, "wx", 0o600);
-        await destination.chmod(0o600);
-        const hash = createHash("sha256");
-        const digest = new Transform({
-            transform(chunk, _encoding, done) {
-                if (!Buffer.isBuffer(chunk)) {
-                    done(new TypeError("Ghidra snapshot stream must contain bytes"));
-                    return;
+        return await resources.run(() => withArtifactRegularFile(sourcePath, resources, options.signal, async (source) => {
+            const initial = await source.stat({ bigint: true });
+            assertArtifactReadActive(options.signal);
+            return await withArtifactFileHandle(snapshotPath, await open(snapshotPath, "wx", 0o600), resources, options.signal, async (destination) => {
+                await destination.chmod(0o600);
+                const hash = createHash("sha256");
+                const input = readArtifactFileChunks(source, {
+                    end: initial.size,
+                    signal: options.signal,
+                });
+                for await (const chunk of input) {
+                    assertArtifactReadActive(options.signal);
+                    // writeFile completes the entire supplied chunk at the current
+                    // descriptor offset. Only this owner closes either descriptor.
+                    await destination.writeFile(chunk);
+                    hash.update(chunk);
+                    assertArtifactReadActive(options.signal);
                 }
-                hash.update(chunk);
-                done(null, chunk);
-            },
-        });
-        await pipeline(source.createReadStream(), digest, destination.createWriteStream(), options.signal === undefined ? {} : { signal: options.signal });
-        const observedSha256 = hash.digest("hex");
-        if (observedSha256 !== expectedSha256)
-            throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`);
-        return { path: snapshotPath, sha256: observedSha256 };
-    }
-    catch (cause) {
-        if (destination !== undefined)
-            await rm(snapshotPath, { force: true }).catch((cause) => {
-                // best-effort cleanup: snapshot removal must not mask the copy failure.
-                void cause;
+                const coverage = input.readCoverage();
+                const observed = hash.digest("hex");
+                const after = await source.stat({ bigint: true });
+                if (coverage.kind !== "complete" ||
+                    coverage.bytes !== initial.size ||
+                    !sameRegularFileState(initial, after) ||
+                    observed !== expectedSha256)
+                    throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest or source identity changed: expected ${expectedSha256}, observed ${observed}`);
+                assertArtifactReadActive(options.signal);
+                return { path: snapshotPath, sha256: observed };
             });
-        throw cause;
-    }
-    finally {
-        await Promise.all([source?.close(), destination?.close()]);
-    }
-};
-const openSnapshotSource = async (path) => {
-    try {
-        // A path replaced by a FIFO must not block startup before its type is checked.
-        return await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        }, "follow"));
     }
     catch (cause) {
-        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
-        if (code === "EACCES" || code === "EPERM")
-            throw new AnalysisAccessDeniedError("open_binary", path, code, { cause });
-        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
-            throw new AnalysisArtifactChangedError("open_binary", path, `The selected Ghidra source could not be opened (${code})`, { cause });
-        throw cause;
+        // The private runtime owns partial snapshot entries. Its owner removes the
+        // tree after every retained descriptor settles; do not unlink a raw name.
+        throw mapArtifactFileFailure(cause, classifySnapshotFailure);
     }
 };
+const classifySnapshotFailure = (cause) => {
+    if (cause instanceof NonRegularFileReadError)
+        return new AnalysisArtifactChangedError("open_binary", cause.path, "The selected Ghidra source is no longer a regular file", { cause });
+    if (!(cause instanceof Error) || !("code" in cause))
+        return cause;
+    const path = "path" in cause && typeof cause.path === "string"
+        ? cause.path
+        : "Ghidra snapshot file";
+    if (cause.code === "EACCES" || cause.code === "EPERM")
+        return new AnalysisAccessDeniedError("open_binary", path, cause.code, {
+            cause,
+        });
+    if (cause.code === "ENOENT" ||
+        cause.code === "ENOTDIR" ||
+        cause.code === "ELOOP")
+        return new AnalysisArtifactChangedError("open_binary", path, `The selected Ghidra file could not be opened (${cause.code})`, { cause });
+    return cause;
+};
 const safeExtension = (path) => {
     const extension = extname(path);
     return /^\.[A-Za-z0-9]{1,12}$/u.test(extension) ? extension : ".bin";

package/dist/ghidra/GhidraTransport.js

@@ -1,9 +1,16 @@
-import { access, open } from "node:fs/promises";
+import { access, lstat } from "node:fs/promises";
 import { join } from "node:path";
+import { z } from "zod";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { readWindowsPrivateRuntimeFile } from "../windows/WindowsPrivateRuntime.js";
 import { err, ok } from "../domain/result.js";
-import { GhidraSessionError } from "./GhidraSessionError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { assertArtifactReadActive, artifactFilePrimaryFailure, artifactFileCancellationCause, bindArtifactFileCleanup, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";
+import { sameRegularFileState } from "../filesystem/RegularFile.js";
+import { GhidraSessionError, bindGhidraSessionFailure, } from "./GhidraSessionError.js";
 /** Allocate an endpoint that fits the host's Unix sockaddr without moving the project. */
 export const createGhidraEndpoint = async (runtimeRoot, transport, platform) => {
     const path = join(runtimeRoot, transport === "unix-socket" ? "bridge.sock" : "bridge-endpoint.json");
@@ -22,79 +29,96 @@ export const createGhidraEndpoint = async (runtimeRoot, transport, platform) =>
         socketRoot,
     };
 };
-/** Observe a ready endpoint, returning null while its bridge is not listening. */
-export const observeGhidraEndpoint = async (endpoint) => {
-    if (endpoint.transport === "unix-socket") {
-        try {
-            await access(endpoint.path);
-            return ok({ path: endpoint.path });
-        }
-        catch (cause) {
-            return isMissing(cause)
-                ? ok(null)
-                : err(endpointFailure(endpoint, "Ghidra socket observation failed", cause));
-        }
-    }
-    if (process.platform === "win32") {
-        try {
-            return parseTcpEndpoint(endpoint, readWindowsPrivateRuntimeFile(endpoint.path));
-        }
-        catch (cause) {
-            return isMissing(cause) || isWindowsEndpointWriterBusy(cause)
-                ? ok(null)
-                : err(endpointFailure(endpoint, "Ghidra endpoint observation failed", cause));
-        }
-    }
-    let handle;
-    try {
-        handle = await open(endpoint.path, "r");
-    }
-    catch (cause) {
-        return isMissing(cause)
-            ? ok(null)
-            : err(endpointFailure(endpoint, "Ghidra endpoint observation failed", cause));
-    }
+const tcpEndpointSchema = z.strictObject({
+    host: z.literal("127.0.0.1"),
+    port: z.number().int().min(1).max(65_535),
+});
+// ReaGhidraBridge.serveTcp publishes compact Gson JSON followed by one newline.
+// Both fields are fixed ASCII, and the bound includes the longest legal port.
+const MAX_TCP_ENDPOINT_BYTES = Buffer.byteLength(JSON.stringify({ host: "127.0.0.1", port: 65_535 }) + "\n");
+/** Observe one endpoint under the same file owner as its startup and finalization. */
+export const observeGhidraEndpoint = async (endpoint, options = {}) => {
+    const resources = options.resourceScope ?? new ArtifactResourceScope();
     try {
-        const encoded = await handle.readFile("utf8");
-        if (encoded.length === 0)
-            return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid"));
-        return parseTcpEndpoint(endpoint, encoded);
+        const target = await resources.run(async () => {
+            assertArtifactReadActive(options.signal);
+            if (endpoint.transport === "unix-socket") {
+                await access(endpoint.path);
+                assertArtifactReadActive(options.signal);
+                return { path: endpoint.path };
+            }
+            if (process.platform === "win32") {
+                const encoded = readWindowsPrivateRuntimeFile(endpoint.path);
+                assertArtifactReadActive(options.signal);
+                return parseTcpEndpoint(endpoint, encoded);
+            }
+            return withArtifactRegularFile(endpoint.path, resources, options.signal, async (file) => {
+                const initial = await file.stat({ bigint: true });
+                assertArtifactReadActive(options.signal);
+                if (initial.size > BigInt(MAX_TCP_ENDPOINT_BYTES))
+                    throw endpointFailure(endpoint, "Ghidra TCP endpoint is invalid", new ArtifactReaderFailure("limit", `Ghidra endpoint record exceeds its compact publication bound (${initial.size} > ${MAX_TCP_ENDPOINT_BYTES} bytes)`));
+                const input = readArtifactFileChunks(file, {
+                    end: initial.size,
+                    signal: options.signal,
+                });
+                const chunks = [];
+                for await (const chunk of input)
+                    chunks.push(Buffer.from(chunk));
+                const coverage = input.readCoverage();
+                const after = await file.stat({ bigint: true });
+                const named = await lstat(endpoint.path, { bigint: true }).catch((cause) => {
+                    throw endpointFailure(endpoint, "Ghidra TCP endpoint changed during observation", cause);
+                });
+                if (coverage.kind !== "complete" ||
+                    coverage.bytes !== initial.size ||
+                    !sameRegularFileState(initial, after) ||
+                    !sameRegularFileState(initial, named))
+                    throw endpointFailure(endpoint, "Ghidra TCP endpoint changed during observation");
+                assertArtifactReadActive(options.signal);
+                return parseTcpEndpoint(endpoint, Buffer.concat(chunks).toString("utf8"));
+            });
+        });
+        return ok(target);
     }
     catch (cause) {
-        return err(endpointFailure(endpoint, "Ghidra endpoint read failed", cause));
-    }
-    finally {
-        await handle.close();
+        if (isMissing(cause) ||
+            (process.platform === "win32" && isWindowsEndpointWriterBusy(cause)))
+            return ok(null);
+        return err(observationFailure(endpoint, cause));
     }
 };
 const parseTcpEndpoint = (endpoint, encoded) => {
     try {
-        const value = JSON.parse(encoded);
-        if (typeof value !== "object" ||
-            value === null ||
-            Array.isArray(value) ||
-            !hasExactKeys(value, ["host", "port"]) ||
-            value.host !== "127.0.0.1" ||
-            !Number.isSafeInteger(value.port) ||
-            typeof value.port !== "number" ||
-            value.port < 1 ||
-            value.port > 65_535)
-            return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid"));
-        return ok({ host: "127.0.0.1", port: value.port });
+        return tcpEndpointSchema.parse(JSON.parse(encoded));
     }
     catch (cause) {
-        return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid", cause));
+        throw endpointFailure(endpoint, "Ghidra TCP endpoint is invalid", cause);
     }
 };
-const hasExactKeys = (value, expected) => {
-    const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
-    return (keys.length === expected.length &&
-        keys.every((key, index) => key === expected[index]));
+const observationFailure = (endpoint, cause) => {
+    const primary = artifactFilePrimaryFailure(cause);
+    let failure = primary instanceof GhidraSessionError
+        ? primary
+        : cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"
+            ? bindGhidraSessionFailure(() => ({
+                transport: endpoint.transport,
+                endpoint_path: endpoint.path,
+            }))("cancelled", "Ghidra endpoint observation was cancelled", cause, {
+                cancellation: { reason: artifactFileCancellationCause(cause) },
+            })
+            : endpointFailure(endpoint, "Ghidra endpoint observation failed", primary);
+    if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
+        const cleanup = new ProviderCleanupError("ghidra", cause.cleanup.resources, {
+            reason: "Ghidra endpoint descriptor cleanup remains incomplete",
+        }, { cause });
+        bindArtifactFileCleanup(cause, cleanup);
+        failure = failure.withCleanupFailure(cleanup);
+    }
+    return failure;
 };
-const endpointFailure = (endpoint, message, cause) => new GhidraSessionError("start", message, {
+const endpointFailure = (endpoint, message, cause) => bindGhidraSessionFailure(() => ({
     transport: endpoint.transport,
     endpoint_path: endpoint.path,
-    ...(cause instanceof Error ? { error: cause.message } : {}),
-}, cause instanceof Error ? { cause } : undefined);
+}))("start", message, cause);
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
 const isWindowsEndpointWriterBusy = (cause) => cause instanceof Error && "win32Code" in cause && cause.win32Code === 32;

package/dist/ghidra/extensions/GhidraExtensions.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { open, realpath, writeFile, mkdir } from "node:fs/promises";
+import { realpath, mkdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
-import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { assertArtifactReadActive } from "../../artifacts/ArtifactFileOperation.js";
+import { readGhidraProfileArtifact, writeGhidraProfileArtifact, ghidraFileFailure, } from "../GhidraFileArtifacts.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
 import { nativeAotAdapter } from "./nativeaot/NativeAotAdapter.js";
@@ -36,37 +36,19 @@ export const ghidraExtensionResultSchema = z.strictObject({
 });
 const adapters = [nativeAotAdapter];
 const MAX_EXTENSION_BYTES = 8 * 1024 * 1024;
-/** Read a bounded regular artifact through its open handle, without ambient state changes. */
-const readJar = async (path) => {
-    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    try {
-        const stat = await file.stat();
-        if (!stat.isFile() || stat.size < 4 || stat.size > MAX_EXTENSION_BYTES)
-            throw new Error(`Ghidra extension must be a regular JAR of 4..${MAX_EXTENSION_BYTES} bytes: ${path}`);
-        const bytes = Buffer.alloc(stat.size);
-        let offset = 0;
-        while (offset < bytes.length) {
-            const read = await file.read(bytes, offset, bytes.length - offset, offset);
-            if (read.bytesRead === 0)
-                throw new Error(`Incomplete Ghidra extension read: ${path}`);
-            offset += read.bytesRead;
-        }
-        const extra = Buffer.alloc(1);
-        if ((await file.read(extra, 0, 1, offset)).bytesRead !== 0 ||
-            bytes.readUInt32LE(0) !== 0x04034b50)
-            throw new Error(`Ghidra extension changed during read or is not a JAR: ${path}`);
-        return bytes;
-    }
-    finally {
-        await file.close();
-    }
-};
+/** JAR framing belongs to the extension adapter; file lifecycle is shared. */
+const readJar = (path, resources, signal) => readGhidraProfileArtifact(path, MAX_EXTENSION_BYTES, resources, signal, (bytes) => {
+    if (bytes.length < 4 || bytes.readUInt32LE(0) !== 0x04034b50)
+        throw new Error(`Ghidra extension is not a JAR: ${path}`);
+    return bytes;
+});
 /** Resolve explicitly configured optional extensions into the immutable analysis profile. */
-export const resolveGhidraExtensions = async (config, target, platform, signal) => {
+export const resolveGhidraExtensions = async (config, target, platform, resources, signal) => resources
+    .run(async () => {
     const extensions = [];
     for (const adapter of adapters) {
         if (signal?.aborted)
-            return err(new AnalysisCancelledError("open_binary"));
+            return err(new AnalysisCancelledError("open_binary", { cause: signal.reason }));
         const configured = adapter.configuredPath(config);
         if (configured === undefined)
             continue;
@@ -75,7 +57,7 @@ export const resolveGhidraExtensions = async (config, target, platform, signal)
             return err(extensionRefusalError(refusal, target));
         try {
             const path = await realpath(configured);
-            const bytes = await readJar(path);
+            const bytes = await readJar(path, resources, signal);
             extensions.push({
                 id: adapter.id,
                 path,
@@ -86,20 +68,17 @@ export const resolveGhidraExtensions = async (config, target, platform, signal)
             });
         }
         catch (cause) {
-            return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
-                cause,
-                diagnostics: {
-                    extension: adapter.id,
-                    path: configured,
-                    reason: cause instanceof Error ? cause.message : String(cause),
-                },
+            return err(ghidraFileFailure(cause, "resolve_analysis_profile", {
+                extension: adapter.id,
+                path: configured,
             }));
         }
     }
     if (signal?.aborted)
-        return err(new AnalysisCancelledError("open_binary"));
+        return err(new AnalysisCancelledError("open_binary", { cause: signal.reason }));
     return ok(extensions);
-};
+})
+    .catch((cause) => err(ghidraFileFailure(cause, "resolve_analysis_profile")));
 /** Require explicit local configuration before admitting executable code from a profile. */
 export const validateGhidraExtensionProfile = (extensions, config, target, platform) => {
     const enabled = adapters.filter((adapter) => adapter.configuredPath(config) !== undefined);
@@ -129,13 +108,16 @@ const extensionRefusalError = (refusal, target) => refusal.constraint === "host"
     // The reason names the workflows that remain available.
     { remediationAction: refusal.reason });
 /** Snapshot committed extension bytes into the private runtime before Java loads them. */
-export const snapshotGhidraExtensions = async (extensions, runtimeRoot) => {
+export const snapshotGhidraExtensions = async (extensions, runtimeRoot, resources, signal) => resources
+    .run(async () => {
+    assertArtifactReadActive(signal);
     if (extensions.length === 0)
         return [];
     for (const extension of extensions) {
         ghidraExtensionSchema.parse(extension);
         const adapter = adapters.find((value) => value.id === extension.id);
-        if (adapter === undefined || adapter.entryClass !== extension.entry_class)
+        if (adapter === undefined ||
+            adapter.entryClass !== extension.entry_class)
             throw new Error(`Unregistered Ghidra extension identity: ${extension.id}`);
         if ((await realpath(extension.configured_path)) !== extension.path)
             throw new Error(`Ghidra extension resolved path differs from explicit configuration: ${extension.id}`);
@@ -144,15 +126,18 @@ export const snapshotGhidraExtensions = async (extensions, runtimeRoot) => {
     await mkdir(directory, { mode: 0o700 });
     const result = [];
     for (const extension of extensions) {
-        const bytes = await readJar(extension.path);
+        const bytes = await readJar(extension.path, resources, signal);
         if (createHash("sha256").update(bytes).digest("hex") !== extension.sha256)
             throw new Error(`Ghidra extension digest differs from committed profile: ${extension.id} (${extension.path})`);
         const path = join(directory, `${extension.id}.jar`);
-        await writeFile(path, bytes, { flag: "wx", mode: 0o600 });
+        await writeGhidraProfileArtifact(path, bytes, resources, signal);
         result.push({ ...extension, path });
     }
     return result;
-};
+})
+    .catch((cause) => {
+    throw ghidraFileFailure(cause, "open_binary");
+});
 /** Require every configured producer result to match its artifact and registered ABI. */
 export const validateGhidraExtensionResults = (expected, results) => {
     if (results.length !== expected.length ||

package/dist/go/GoBinaryContainer.js

@@ -0,0 +1,140 @@
+/** Distinguish corrupt recognized binaries from containers outside parser coverage. */
+export class GoBinaryFormatFailure extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "GoBinaryFormatFailure";
+    }
+}
+/** Resource boundary exceeded while decoding metadata or native container structure. */
+export class GoBinaryResourceFailure extends Error {
+    boundary;
+    maximum_bytes;
+    constructor(boundary, maximum_bytes, message) {
+        super(message);
+        this.boundary = boundary;
+        this.maximum_bytes = maximum_bytes;
+        this.name = "GoBinaryResourceFailure";
+    }
+}
+/** Reader that checks every structural range before decoding numeric fields. */
+export class GoBinaryReader {
+    bytes;
+    little;
+    constructor(bytes, little) {
+        this.bytes = bytes;
+        this.little = little;
+    }
+    range(offset, size, label) {
+        if (!Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
+            offset < 0 ||
+            size < 0 ||
+            offset > this.bytes.length ||
+            size > this.bytes.length - offset)
+            throw new GoBinaryFormatFailure("malformed", `${label} range is truncated or outside the file`);
+        return this.bytes.subarray(offset, offset + size);
+    }
+    u16(offset) {
+        const value = this.range(offset, 2, "16-bit field");
+        return this.little ? value.readUInt16LE() : value.readUInt16BE();
+    }
+    u32(offset) {
+        const value = this.range(offset, 4, "32-bit field");
+        return this.little ? value.readUInt32LE() : value.readUInt32BE();
+    }
+    word(offset, bits) {
+        if (bits === 32)
+            return BigInt(this.u32(offset));
+        const value = this.range(offset, 8, "64-bit field");
+        return this.little ? value.readBigUInt64LE() : value.readBigUInt64BE();
+    }
+    fileRange(offset, size, label) {
+        if (offset > BigInt(this.bytes.length) ||
+            size > BigInt(this.bytes.length) - offset)
+            throw new GoBinaryFormatFailure("malformed", `${label} range is outside the file`);
+        const result = { address: 0n, offset: Number(offset), size: Number(size) };
+        this.range(result.offset, result.size, label);
+        return result;
+    }
+    table(offset, count, width, label) {
+        const size = BigInt(count) * BigInt(width);
+        if (size > 16n * 1024n * 1024n)
+            throw new GoBinaryResourceFailure("structure", 16 * 1024 * 1024, `${label} exceeds the 16 MiB structural decoding budget`);
+        return this.fileRange(offset, size, label).offset;
+    }
+}
+/** Admit a declared file span, or mark it unbacked when it leaves the file. */
+export const declaredFileRange = (fileBytes, offset, size) => {
+    if (offset < 0n ||
+        size < 0n ||
+        offset > BigInt(Number.MAX_SAFE_INTEGER) ||
+        size > BigInt(Number.MAX_SAFE_INTEGER) ||
+        offset > BigInt(fileBytes) ||
+        size > BigInt(fileBytes) - offset)
+        return { offset: 0, size: 0, file_backed: false };
+    return {
+        offset: Number(offset),
+        size: Number(size),
+        file_backed: size > 0n,
+    };
+};
+/** Map a virtual span without losing precision or selecting an ambiguous alias. */
+export const mappedFileOffset = (mappings, address, size, zeroFills = []) => {
+    let found;
+    for (const mapping of mappings) {
+        const delta = address - mapping.address;
+        if (delta < 0n ||
+            delta > BigInt(mapping.size) ||
+            BigInt(size) > BigInt(mapping.size) - delta)
+            continue;
+        const offset = mapping.offset + Number(delta);
+        if (found !== undefined && found !== offset)
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file mappings");
+        found = offset;
+    }
+    if (found === undefined)
+        throw new GoBinaryFormatFailure("malformed", "Virtual address or string range is not file mapped");
+    for (const zeroFill of zeroFills) {
+        if (spansOverlap(address, BigInt(size), zeroFill.address, zeroFill.size))
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file and zero-fill mappings");
+    }
+    const end = address + BigInt(size);
+    for (const mapping of mappings) {
+        const start = address > mapping.address ? address : mapping.address;
+        const mappingEnd = mapping.address + BigInt(mapping.size);
+        const overlapEnd = end < mappingEnd ? end : mappingEnd;
+        if (start >= overlapEnd)
+            continue;
+        if (BigInt(found) + start - address !==
+            BigInt(mapping.offset) + start - mapping.address)
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file mappings");
+    }
+    return found;
+};
+/** Recognize a wholly zero-filled span while refusing even partial file aliases. */
+export const isZeroFilledSpan = (mappings, zeroFills, address, size) => {
+    const bytes = BigInt(size);
+    if (!zeroFills.some((mapping) => address >= mapping.address &&
+        address + bytes <= mapping.address + mapping.size))
+        return false;
+    for (const mapping of mappings) {
+        if (spansOverlap(address, bytes, mapping.address, BigInt(mapping.size)))
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file and zero-fill mappings");
+    }
+    return true;
+};
+const spansOverlap = (address, size, otherAddress, otherSize) => size > 0n &&
+    otherSize > 0n &&
+    address < otherAddress + otherSize &&
+    otherAddress < address + size;
+/** Decode metadata text without replacing invalid bytes or stripping an initial BOM. */
+export const goUtf8 = (bytes, label) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new GoBinaryFormatFailure("malformed", `${label} contains malformed UTF-8: ${String(cause)}`);
+    }
+};