rea-agents 6.3.0 → 6.5.0

package/dist/dotnet/ManagedPeReader.js

@@ -1,4 +1,17 @@
+import { decodePeMachine } from "../domain/peMachine.js";
 import { managedFailure, ManagedReaderFailure, } from "./ManagedReaderFailure.js";
+/**
+ * How the CLI header constrains process bitness. 32BITREQUIRED and
+ * 32BITPREFERRED are one two-bit field: required alone is x86-only, both set
+ * is platform-neutral code that prefers a 32-bit process, and preferred alone
+ * is reserved and constrains nothing.
+ */
+export const managedCli32BitRequirement = (flags) => {
+    const pair = flags & 0x0002_0002;
+    if (pair === 0x0000_0002)
+        return "required";
+    return pair === 0x0002_0002 ? "preferred" : "none";
+};
 const requireRange = (bytes, offset, length, scope) => {
     if (!Number.isSafeInteger(offset) ||
         !Number.isSafeInteger(length) ||
@@ -13,41 +26,57 @@ const add = (left, right, scope) => {
         throw managedFailure("invalid-directory", scope, `${scope} offset arithmetic overflowed`, left);
     return result;
 };
-const architectureFor = (machine) => {
-    switch (machine) {
-        case 0x014c:
-            return "x86";
-        case 0x8664:
-            return "x86_64";
-        case 0x01c0:
-        case 0x01c2:
-        case 0x01c4:
-            return "arm";
-        case 0xaa64:
-            return "arm64";
-        default:
-            throw managedFailure("invalid-directory", "pe.machine", `Unsupported PE machine 0x${machine.toString(16).padStart(4, "0")}`);
-    }
+const architectureFor = (machine, managed) => {
+    const decoded = decodePeMachine(machine);
+    if (decoded === undefined || (decoded.nativeOsOverride && !managed))
+        throw managedFailure("invalid-directory", "pe.machine", `Unsupported PE machine 0x${machine.toString(16).padStart(4, "0")}`);
+    return decoded.architecture;
 };
-const mapRva = (mapping) => {
+/** Resolve one section identity for both exact reads and available-byte queries. */
+const resolveRva = (mapping) => {
     const { bytes, sections, rva, size, scope } = mapping;
-    if (rva === 0 && size === 0)
-        return 0;
-    for (const section of sections) {
-        const mappedSize = Math.max(section.virtualSize, section.rawSize);
-        if (rva < section.virtualAddress)
-            continue;
+    if (!Number.isSafeInteger(rva) ||
+        !Number.isSafeInteger(size) ||
+        rva < 0 ||
+        size < 0 ||
+        rva > 0xffff_ffff ||
+        (size > 0 && size > 0x1_0000_0000 - rva))
+        throw managedFailure("invalid-directory", scope, `${scope} has an invalid RVA range`);
+    // VirtualSize owns RVA containment; raw size also includes alignment padding.
+    const selected = sections.find((section) => {
         const within = rva - section.virtualAddress;
-        if (within > mappedSize || size > mappedSize - within)
+        return (section.virtualSize > 0 &&
+            within >= 0 &&
+            within < section.virtualSize &&
+            size <= section.virtualSize - within);
+    });
+    if (selected === undefined)
+        throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by one PE section`);
+    for (const section of sections) {
+        if (section === selected || section.virtualSize === 0)
             continue;
-        if (within > section.rawSize || size > section.rawSize - within)
-            throw managedFailure("invalid-directory", scope, `${scope} occupies virtual bytes without file-backed data`);
-        const offset = add(section.rawOffset, within, scope);
-        requireRange(bytes, offset, size, scope);
-        return offset;
+        const end = section.virtualAddress + section.virtualSize;
+        const intersects = size === 0
+            ? rva >= section.virtualAddress && rva < end
+            : rva < end && rva + size > section.virtualAddress;
+        if (intersects)
+            throw managedFailure("invalid-directory", scope, `${scope} RVA range has ambiguous overlapping PE section mappings`);
     }
-    throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by a PE section`);
+    const within = rva - selected.virtualAddress;
+    if (within > selected.rawSize || size > selected.rawSize - within)
+        throw managedFailure("invalid-directory", scope, `${scope} occupies virtual bytes without file-backed data`);
+    const offset = add(selected.rawOffset, within, scope);
+    requireRange(bytes, offset, size, scope);
+    let available = Math.min(selected.virtualSize - within, selected.rawSize - within, bytes.length - offset, 0x1_0000_0000 - rva);
+    // A future overlap ends the uniquely mapped extent even if the current byte is unique.
+    for (const section of sections)
+        if (section !== selected &&
+            section.virtualAddress > rva &&
+            section.virtualSize > 0)
+            available = Math.min(available, section.virtualAddress - rva);
+    return { offset, available };
 };
+const mapRva = (mapping) => mapping.rva === 0 && mapping.size === 0 ? 0 : resolveRva(mapping).offset;
 const readDirectory = (bytes, offset) => {
     requireRange(bytes, offset, 8, "pe.data-directory");
     return {
@@ -147,12 +176,36 @@ const readSections = (bytes, coff, optional) => {
     return sections;
 };
 const readCliDirectory = (bytes, coff, optional) => {
-    requireRange(bytes, optional.directoryCountOffset, 4, "pe.data-directories");
+    const countOffset = optional.directoryCountOffset - optional.optionalOffset;
+    if (countOffset + 4 > coff.optionalSize)
+        return {
+            kind: "unreadable",
+            issue: {
+                code: "invalid-directory",
+                scope: "pe.optional-header",
+                detail: "PE optional header does not contain its directory count",
+                offset: optional.directoryCountOffset,
+            },
+        };
     const directoryCount = bytes.readUInt32LE(optional.directoryCountOffset);
-    if (directoryCount <= 14 ||
-        coff.optionalSize < optional.directoryOffset - optional.optionalOffset + 120)
-        return { rva: 0, size: 0 };
-    return readDirectory(bytes, optional.directoryOffset + 14 * 8);
+    if (directoryCount <= 14)
+        return { kind: "absent" };
+    const availableDirectoryCount = Math.floor((coff.optionalSize - (optional.directoryOffset - optional.optionalOffset)) /
+        8);
+    if (availableDirectoryCount < 15)
+        return {
+            kind: "unreadable",
+            issue: {
+                code: "invalid-directory",
+                scope: "pe.data-directories",
+                detail: "PE data-directory count exceeds the optional-header extent",
+                offset: optional.directoryCountOffset,
+            },
+        };
+    const directory = readDirectory(bytes, optional.directoryOffset + 14 * 8);
+    return directory.rva !== 0 || directory.size !== 0
+        ? { kind: "present", directory }
+        : { kind: "absent" };
 };
 /** Parse the file-backed PE and CLI layout without loading target code. */
 export const readManagedPeLayout = (bytes) => {
@@ -162,40 +215,31 @@ export const readManagedPeLayout = (bytes) => {
     const coff = readCoffHeader(bytes);
     const optional = readOptionalHeader(bytes, coff);
     const sections = readSections(bytes, coff, optional);
-    const cliDirectory = readCliDirectory(bytes, coff, optional);
-    const cliDirectoryPresent = cliDirectory.rva !== 0 || cliDirectory.size !== 0;
+    const cliDirectoryRead = readCliDirectory(bytes, coff, optional);
+    const cliDirectoryState = cliDirectoryRead.kind;
     let cli = null;
-    let cliIssue = null;
-    if (cliDirectoryPresent)
+    let cliIssue = cliDirectoryRead.kind === "unreadable" ? cliDirectoryRead.issue : null;
+    if (cliDirectoryRead.kind === "present") {
         try {
-            cli = readCliHeader(bytes, sections, cliDirectory);
+            cli = readCliHeader(bytes, sections, cliDirectoryRead.directory);
         }
         catch (cause) {
             if (!(cause instanceof ManagedReaderFailure))
                 throw cause;
             cliIssue = cause.issue;
         }
+    }
     return {
         machine: coff.machine,
-        architecture: architectureFor(coff.machine),
+        architecture: architectureFor(coff.machine, cliDirectoryState !== "absent"),
         optionalHeader: optional.optionalHeader,
         sectionCount: coff.sectionCount,
         characteristics: coff.characteristics,
         sections,
         cli,
-        cliDirectoryPresent,
+        cliDirectoryState,
         cliIssue,
         rvaToOffset: (rva, size, scope) => mapRva({ bytes, sections, rva, size, scope }),
-        rvaAvailableBytes: (rva, scope) => {
-            mapRva({ bytes, sections, rva, size: 1, scope });
-            for (const section of sections) {
-                if (rva < section.virtualAddress)
-                    continue;
-                const within = rva - section.virtualAddress;
-                if (within < section.rawSize)
-                    return Math.min(section.rawSize - within, bytes.length - section.rawOffset - within);
-            }
-            throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by file-backed PE section data`);
-        },
+        rvaAvailableBytes: (rva, scope) => resolveRva({ bytes, sections, rva, size: 1, scope }).available,
     };
 };

package/dist/dotnet/ManagedReaderFailure.js

@@ -14,7 +14,8 @@ export const readManagedValue = (operation, issues) => {
         return operation();
     }
     catch (cause) {
-        if (!(cause instanceof ManagedReaderFailure))
+        if (!(cause instanceof ManagedReaderFailure) ||
+            cause.issue.code === "resource-limit")
             throw cause;
         issues.push(cause.issue);
         return undefined;
@@ -24,3 +25,12 @@ export const readManagedValue = (operation, issues) => {
 export const uniqueManagedParseIssues = (issues) => [
     ...new Map(issues.map((issue) => [JSON.stringify(issue), issue])).values(),
 ];
+/**
+ * Append issue lists one issue at a time. Spreading a list into `push` passes
+ * one argument per issue, which overflows the stack on large malformed inputs.
+ */
+export const appendManagedParseIssues = (issues, ...found) => {
+    for (const list of found)
+        for (const issue of list)
+            issues.push(issue);
+};

package/dist/dotnet/ManagedSnapshot.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
+import { classifyBinaryTargetFilesystemFailure } from "../application/BinaryTargetResolver.js";
+import { withRegularFile } from "../application/RegularFileRead.js";
+import { RegularFileCleanupFailure, } from "../application/RegularFileRead.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+// Managed static inspection retains the complete PE snapshot in memory.
+export const MAX_MANAGED_SNAPSHOT_BYTES = 128 * 1024 * 1024;
+const managedSnapshotCapacityError = (operation) => new AnalysisResourceConstraintError(operation, "memory", "Managed static inspection requires an eagerly retained PE snapshot within its input byte budget.", { max_snapshot_bytes: MAX_MANAGED_SNAPSHOT_BYTES });
+export const readManagedSnapshot = async (path, operation, options = {}) => {
+    return readManagedFile(path, operation, async (handle, metadata) => {
+        const signal = options.signal;
+        if (metadata.size > MAX_MANAGED_SNAPSHOT_BYTES)
+            throw managedSnapshotCapacityError(operation);
+        const bytes = await readBoundedFileBytes(handle, MAX_MANAGED_SNAPSHOT_BYTES, signal);
+        if (bytes === undefined)
+            throw managedSnapshotCapacityError(operation);
+        signal?.throwIfAborted();
+        return {
+            byteLength: bytes.length,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            bytes,
+        };
+    }, options);
+};
+export const hashManagedSource = async (path, operation, options = {}) => readManagedFile(path, operation, async (handle, metadata) => {
+    const signal = options.signal;
+    if (metadata.size > MAX_MANAGED_SNAPSHOT_BYTES)
+        throw managedSnapshotCapacityError(operation);
+    const digest = createHash("sha256");
+    let byteLength = 0;
+    const stream = handle.createReadStream({
+        autoClose: false,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    for await (const chunk of stream) {
+        signal?.throwIfAborted();
+        if (!Buffer.isBuffer(chunk))
+            throw new TypeError("Managed source stream returned non-buffer data");
+        if (chunk.length > MAX_MANAGED_SNAPSHOT_BYTES - byteLength)
+            throw managedSnapshotCapacityError(operation);
+        byteLength += chunk.length;
+        digest.update(chunk);
+    }
+    return { byteLength, sha256: digest.digest("hex") };
+}, options);
+const readManagedFile = (path, operation, read, options) => withRegularFile(path, read, options).catch((cause) => {
+    throw normalizeManagedReadFailure(cause, path, operation, options.signal);
+});
+/** Keep cleanup ownership and the original typed read failure at this boundary. */
+const normalizeManagedReadFailure = (cause, fallbackPath, operation, signal) => {
+    const cleanupError = managedCleanupError(cause, fallbackPath, operation, signal);
+    if (cleanupError !== undefined)
+        return cleanupError;
+    return normalizeReadFailure(cause, fallbackPath, operation, signal);
+};
+/** Project cleanup failures owned by managed file reads or their shared scope. */
+export const managedCleanupError = (cause, fallbackPath, operation, signal) => {
+    if (cause instanceof RegularFileCleanupFailure) {
+        const cleanup = new ProviderCleanupError(MANAGED_STATIC_PROVIDER.id, [cause.path], { reason: "A managed input file handle could not be closed" }, { cause, operation });
+        const failure = cause.outcome.kind === "failed"
+            ? normalizeReadFailure(cause.outcome.cause, cause.path, operation, signal)
+            : undefined;
+        return failure instanceof AnalysisError
+            ? analysisErrorWithCleanupFailure(failure, cleanup, operation)
+            : cleanup;
+    }
+    if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+        return new ProviderCleanupError(MANAGED_STATIC_PROVIDER.id, cause.cleanup.resources.length > 0
+            ? cause.cleanup.resources
+            : [fallbackPath], { reason: cause.cleanup.reason }, { cause, operation });
+    return undefined;
+};
+const normalizeReadFailure = (cause, path, operation, signal) => cause instanceof RegularFileChangedError
+    ? new EvidenceIntegrityError(`Managed source changed while ${operation} was reading ${path}.`, { cause })
+    : cause instanceof AnalysisError
+        ? cause
+        : (classifyBinaryTargetFilesystemFailure(path, cause) ??
+            (signal?.aborted === true
+                ? new AnalysisCancelledError(operation, { cause })
+                : cause));

package/dist/dotnet/ManagedStaticProvider.js

@@ -1,17 +1,21 @@
-import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 import { managedStaticCapabilities } from "./ManagedStaticProviderMetadata.js";
 import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
-import { MANAGED_TOOL_CONTRACTS, managedTargetInputSchema, } from "../contracts/managed/managedToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { MANAGED_TOOL_CONTRACTS, managedMembersInputSchema, managedTargetInputSchema, } from "../contracts/managed/managedToolContracts.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js";
 import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js";
 import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js";
+import { RegularFileCleanupFailure } from "../application/RegularFileRead.js";
+import { ManagedReaderFailure } from "./ManagedReaderFailure.js";
+import { hashManagedSource, managedCleanupError, readManagedSnapshot, } from "./ManagedSnapshot.js";
 /** Execution-free managed PE/CLI auxiliary provider. */
 export class ManagedStaticProvider {
     #capabilities = managedStaticCapabilities();
@@ -28,6 +32,7 @@ export class ManagedStaticProvider {
 class ManagedStaticClient {
     target;
     #snapshotBytes;
+    #resources = new ArtifactResourceScope();
     constructor(target) {
         this.target = target;
     }
@@ -43,8 +48,14 @@ class ManagedStaticClient {
                 return err(new AnalysisCancelledError(operation));
             const snapshot = this.#snapshotBytes;
             const observed = snapshot === undefined
-                ? await readManagedSnapshot(this.target.path, options?.signal)
-                : await hashManagedSource(this.target.path, options?.signal);
+                ? await readManagedSnapshot(this.target.path, operation, {
+                    signal: options?.signal,
+                    resources: this.#resources,
+                })
+                : await hashManagedSource(this.target.path, operation, {
+                    signal: options?.signal,
+                    resources: this.#resources,
+                });
             if (observed.sha256 !== this.target.sha256)
                 return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observed.sha256} at ${this.target.path}`));
             const bytes = snapshot ?? observed.bytes;
@@ -60,50 +71,61 @@ class ManagedStaticClient {
             }));
         }
         catch (cause) {
+            if (isCleanupFailure(cause))
+                return err(this.#cleanupError(operation, cause));
+            if (cause instanceof AnalysisError)
+                return err(cause);
             if (options?.signal?.aborted === true)
                 return err(new AnalysisCancelledError(operation));
+            // A PE header or section table the reader cannot map is malformed input.
+            if (cause instanceof ManagedReaderFailure &&
+                cause.issue.code !== "resource-limit")
+                return err(new AnalysisInputError(operation, { cause }, [
+                    {
+                        path: ["path"],
+                        reason: "invalid_format",
+                        message: `Selected artifact ${this.target.path}: ${cause.issue.detail}`,
+                    },
+                ]));
             return err(new ProviderAdapterError(MANAGED_STATIC_PROVIDER.id, operation, {
                 cause,
             }));
         }
     }
-    close() {
+    async close() {
         this.#snapshotBytes = undefined;
-        return Promise.resolve(ok(null));
+        try {
+            await this.#resources.close();
+            return ok(null);
+        }
+        catch (cause) {
+            return err(this.#cleanupError("close", cause));
+        }
     }
-}
-const readManagedSnapshot = async (path, signal) => {
-    const bytes = await readFile(path, signal === undefined ? undefined : { signal });
-    return {
-        byteLength: bytes.length,
-        sha256: createHash("sha256").update(bytes).digest("hex"),
-        bytes,
-    };
-};
-const hashManagedSource = async (path, signal) => {
-    const digest = createHash("sha256");
-    let byteLength = 0;
-    const stream = createReadStream(path, signal === undefined ? undefined : { signal });
-    for await (const chunk of stream) {
-        if (!Buffer.isBuffer(chunk))
-            throw new TypeError("Managed source stream returned non-buffer data");
-        if (chunk.length > Number.MAX_SAFE_INTEGER - byteLength)
-            throw new RangeError("Managed source byte length overflowed");
-        byteLength += chunk.length;
-        digest.update(chunk);
+    #cleanupError(operation, cause) {
+        const failure = managedCleanupError(cause, this.target.path, operation);
+        if (failure instanceof ProviderCleanupError)
+            return failure;
+        const cleanup = cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
+        return new ProviderCleanupError(MANAGED_STATIC_PROVIDER.id, cleanup?.resources ?? [this.target.path], {
+            reason: cleanup?.reason ??
+                (cause instanceof Error ? cause.message : String(cause)),
+        }, { cause, operation });
     }
-    return { byteLength, sha256: digest.digest("hex") };
-};
+}
+const isCleanupFailure = (cause) => cause instanceof RegularFileCleanupFailure ||
+    (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined);
 const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const inspectManagedOperation = (operation, parameters, bytes, target) => {
+    if (operation === "inspect_managed_members") {
+        const { type_names: typeNames } = managedMembersInputSchema.parse(parameters);
+        return inspectManagedMembersBytes(bytes, target, typeNames === undefined ? {} : { typeNames });
+    }
     managedTargetInputSchema.parse(parameters);
     if (operation === "inspect_managed_artifact") {
         return inspectManagedArtifactBytes(bytes, target);
     }
-    if (operation === "inspect_managed_native_boundaries") {
-        return inspectManagedNativeBoundariesBytes(bytes, target);
-    }
-    return inspectManagedMembersBytes(bytes, target);
+    return inspectManagedNativeBoundariesBytes(bytes, target);
 };
 const managedLocations = (result) => {
     if ("pe" in result) {

package/dist/dotnet/ManagedTypeMemberLists.js

@@ -0,0 +1,105 @@
+import { managedDecodeBudget } from "./ManagedDecodeBudget.js";
+import { metadataRowCursor, metadataToken } from "./ManagedMetadataHeaps.js";
+import { memberListIndexSize, memberListTable, validatedMemberListStart, } from "./ManagedMemberPointers.js";
+export const readTypeMemberListFacts = (bytes, layout) => {
+    const fields = memberListTable(layout, 4);
+    const methods = memberListTable(layout, 6);
+    const rows = [];
+    const issues = [];
+    const types = layout.table(2);
+    const typeCount = types?.rowCount ?? 0;
+    // Peak retained shape includes both the parsed-start and range arrays, their
+    // nested records, plus each eventual JSON object/key projection. Malformed
+    // row diagnostics are admitted separately before they are allocated.
+    managedDecodeBudget(layout).reserve(typeCount * 512 + 256, types?.offset ?? null);
+    for (let row = 1; row <= typeCount; row += 1) {
+        const cursor = metadataRowCursor(bytes, layout, 2, row);
+        cursor.readUInt32();
+        cursor.readIndex(layout.stringIndexSize);
+        cursor.readIndex(layout.stringIndexSize);
+        cursor.readIndex(layout.codedIndexSize("TypeDefOrRef"));
+        const field = {
+            offset: cursor.offset,
+            raw: cursor.readIndex(memberListIndexSize(layout, 4)),
+        };
+        const method = {
+            offset: cursor.offset,
+            raw: cursor.readIndex(memberListIndexSize(layout, 6)),
+        };
+        const entry = {
+            field: { ...field, value: validatedMemberListStart(field.raw, fields) },
+            method: {
+                ...method,
+                value: validatedMemberListStart(method.raw, methods),
+            },
+        };
+        rows.push(entry);
+        for (const [name, start, table] of [
+            ["FieldList", entry.field, fields],
+            ["MethodList", entry.method, methods],
+        ])
+            if (start.value === null) {
+                managedDecodeBudget(layout).reserve(512, start.offset);
+                issues.push({
+                    code: "invalid-row",
+                    scope: `metadata.TypeDef:${metadataToken(2, row)}`,
+                    offset: start.offset,
+                    detail: `TypeDef ${name} start ${String(start.raw)} is outside the one-based list range 1..${String((table?.rowCount ?? 0) + 1)}`,
+                });
+            }
+    }
+    const nonmonotonicFields = new Set();
+    const nonmonotonicMethods = new Set();
+    for (let index = 0; index + 1 < rows.length; index += 1) {
+        const current = rows[index];
+        const next = rows[index + 1];
+        if (current === undefined || next === undefined)
+            continue;
+        for (const [name, before, after, affected] of [
+            ["FieldList", current.field, next.field, nonmonotonicFields],
+            ["MethodList", current.method, next.method, nonmonotonicMethods],
+        ])
+            if (before.value !== null &&
+                after.value !== null &&
+                after.value < before.value) {
+                managedDecodeBudget(layout).reserve(512, after.offset);
+                affected.add(index);
+                affected.add(index + 1);
+                issues.push({
+                    code: "invalid-row",
+                    scope: `metadata.TypeDef:${metadataToken(2, index + 2)}`,
+                    offset: after.offset,
+                    detail: `TypeDef ${name} start ${String(after.raw)} decreases from preceding start ${String(before.raw)}; adjacent member ranges are unknown`,
+                });
+            }
+    }
+    const entries = rows.map((entry, index) => {
+        const next = rows[index + 1];
+        return {
+            field: {
+                start: {
+                    ...entry.field,
+                    value: nonmonotonicFields.has(index) ? null : entry.field.value,
+                },
+                end: next === undefined
+                    ? (fields?.rowCount ?? 0) + 1
+                    : nonmonotonicFields.has(index) || nonmonotonicFields.has(index + 1)
+                        ? null
+                        : next.field.value,
+            },
+            method: {
+                start: {
+                    ...entry.method,
+                    value: nonmonotonicMethods.has(index) ? null : entry.method.value,
+                },
+                end: next === undefined
+                    ? (methods?.rowCount ?? 0) + 1
+                    : nonmonotonicMethods.has(index) ||
+                        nonmonotonicMethods.has(index + 1)
+                        ? null
+                        : next.method.value,
+            },
+        };
+    });
+    return { entries, issues };
+};

package/dist/dotnet/ManagedTypeNames.js

@@ -0,0 +1,98 @@
+import { managedDecodeBudget } from "./ManagedDecodeBudget.js";
+import { fullName, readCompressed, specSignature, } from "./ManagedMemberInspectorCore.js";
+import { metadataRowOffset, } from "./ManagedMetadataLayout.js";
+import { metadataCodedTokenInvalidReason, metadataRowCursor, metadataToken, readMetadataBlob, readMetadataString, } from "./ManagedMetadataHeaps.js";
+import { managedFailure, readManagedValue } from "./ManagedReaderFailure.js";
+/**
+ * Name the type a TypeDef, TypeRef, or generic-instantiation TypeSpec token
+ * denotes, in the namespace-qualified form TypeDef `full_name` uses, once per
+ * token. Other decoded TypeSpecs stay null: the type is unknown. Malformed or
+ * unsupported rows and blobs are reported to `issues` and also stay null,
+ * except that a TypeRef with an invalid ResolutionScope keeps its readable name.
+ */
+export const typeNameLookup = (bytes, layout, ranges, issues) => {
+    const names = new Map();
+    const checkedScopes = new Set();
+    const validateScopeChain = (row) => {
+        const path = new Set();
+        let current = row;
+        while (!checkedScopes.has(current)) {
+            const cursor = metadataRowCursor(bytes, layout, 1, current);
+            if (path.has(current)) {
+                issues.push({
+                    code: "invalid-row",
+                    scope: `metadata.TypeRef:${metadataToken(1, current)}`,
+                    offset: cursor.start,
+                    detail: "TypeRef ResolutionScope chain contains a cycle",
+                });
+                break;
+            }
+            // Admit the chain's visited entry and retained validation-cache entry.
+            managedDecodeBudget(layout).reserve(128, cursor.start);
+            path.add(current);
+            const raw = cursor.readIndex(layout.codedIndexSize("ResolutionScope"));
+            const reason = metadataCodedTokenInvalidReason(raw, 2, [0, 26, 35, 1], layout.rowCounts);
+            if (reason !== null) {
+                issues.push({
+                    code: "invalid-row",
+                    scope: `metadata.TypeRef:${metadataToken(1, current)}`,
+                    offset: cursor.start,
+                    detail: `TypeRef ResolutionScope coded index 0x${raw.toString(16)} is invalid: ${reason}`,
+                });
+                break;
+            }
+            // Null scopes are legal; non-TypeRef scopes terminate local validation.
+            if (raw === 0 || (raw & 3) !== 3)
+                break;
+            current = Math.floor(raw / 4);
+        }
+        for (const visited of path)
+            checkedScopes.add(visited);
+    };
+    const definitionName = (table, row) => {
+        if (table === 2) {
+            metadataRowOffset(layout, 2, row);
+            return ranges[row - 1]?.fullName ?? null;
+        }
+        const cursor = metadataRowCursor(bytes, layout, 1, row);
+        cursor.readIndex(layout.codedIndexSize("ResolutionScope"));
+        readManagedValue(() => validateScopeChain(row), issues);
+        const name = cursor.readIndex(layout.stringIndexSize);
+        const namespace = cursor.readIndex(layout.stringIndexSize);
+        return fullName(readMetadataString(bytes, layout, namespace, layout.strings.size), readMetadataString(bytes, layout, name, layout.strings.size));
+    };
+    const specName = (row) => {
+        const cursor = metadataRowCursor(bytes, layout, 27, row);
+        const spec = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), layout.blob.size);
+        const owner = {
+            form: "type",
+            scope: `metadata.TypeSpec:${metadataToken(27, row)}`,
+            offset: cursor.start,
+        };
+        specSignature(layout, spec, owner);
+        if (spec[0] !== 0x15)
+            return null;
+        // GENERICINST (CLASS | VALUETYPE) TypeDefOrRefEncoded: never a TypeSpec,
+        // so naming never recurses.
+        const encoded = readCompressed(spec, 2).value;
+        const table = [2, 1][encoded & 3];
+        if (table === undefined)
+            throw managedFailure("invalid-blob", owner.scope, "Generic instantiation does not name a TypeDef or TypeRef", owner.offset);
+        return definitionName(table, Math.floor(encoded / 4));
+    };
+    return (token) => {
+        if (token === null)
+            return null;
+        if (names.has(token))
+            return names.get(token) ?? null;
+        const table = Number.parseInt(token.slice(2, 4), 16);
+        const row = Number.parseInt(token.slice(4), 16);
+        const name = readManagedValue(() => table === 27
+            ? specName(row)
+            : table === 1 || table === 2
+                ? definitionName(table, row)
+                : null, issues) ?? null;
+        names.set(token, name);
+        return name;
+    };
+};