rea-agents 5.0.0 → 6.0.0

package/dist/domain/reconstructionVerificationSchemas.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { digestSchema } from "./../domain/digests.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
-import { PROCESS_COMPARISON_DIMENSIONS } from "./processComparison.js";
+import { PROCESS_COMPARISON_DIMENSIONS } from "./process/processComparison.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const unknownIdSchema = prefixedDigestSchema("unk");
 const claimIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);

package/dist/domain/residualUnknown.js

@@ -147,9 +147,10 @@ export const recordUnknownInputSchema = residualUnknownObjectSchema
     .extend({
     supporting_evidence_ids: z.array(evidenceIdSchema).default([]),
     contradicting_evidence_ids: z.array(evidenceIdSchema).default([]),
-});
+})
+    .strict();
 /** Explicit optimistic-concurrency update command for one unknown. */
-export const updateUnknownInputSchema = z.object({
+export const updateUnknownInputSchema = z.strictObject({
     unknown_id: unknownIdSchema,
     expected_revision: z.number().int().min(1),
     status: residualUnknownObjectSchema.shape.status,

package/dist/domain/staticRuntimeCorrelation.js

@@ -5,9 +5,9 @@ import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { uniqueSorted } from "./canonicalOrdering.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { functionComparisonResultSchema } from "./functionComparison.js";
-import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./processEvidenceProvider.js";
-import { comparisonStatusSchema, processCaptureComparisonSchema, } from "./processCapture.js";
-import { PROCESS_COMPARISON_DIMENSIONS } from "./processComparison.js";
+import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./process/processEvidenceProvider.js";
+import { comparisonStatusSchema, processCaptureComparisonSchema, } from "./process/processCapture.js";
+import { PROCESS_COMPARISON_DIMENSIONS } from "./process/processComparison.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const functionDimensionSchema = z.enum([

package/dist/domain/webCaptureDiff.js

@@ -118,6 +118,7 @@ const networkMap = (inspection) => {
             status: request.status,
             mime_type: request.mime_type,
             encoded_data_length: request.encoded_data_length,
+            redirects: (request.redirects ?? []).map(({ request_timestamp: _requestTimestamp, redirect_event_timestamp: _redirectEventTimestamp, ...redirect }) => redirect),
             initiator: request.initiator,
             body_shapes: request.body_shapes,
         });

package/dist/domain/webNetworkCapture.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Complete historical evidence budgets; exceeding a budget returns no partial capture. */
+export const WEB_NETWORK_CAPTURE_LIMITS = {
+    inputBytes: 32 * 1024 * 1024,
+    outputBytes: 96 * 1024 * 1024,
+    timeoutMs: 30_000,
+    depth: 64,
+};
+/** Inspect an explicit retained capture without contacting its recorded destinations. */
+export const inspectWebNetworkCaptureInputSchema = z.strictObject({
+    capture_path: z
+        .string()
+        .min(1)
+        .describe("Absolute local HAR or mitmproxy capture path."),
+    format: z.enum(["har", "mitmproxy"]),
+    record_ordinals: z
+        .array(z.number().int().nonnegative())
+        .min(1)
+        .optional()
+        .describe("Zero-based producer record ordinals, in caller-selected order. Omit to inspect every record."),
+    sensitive_values: z
+        .array(z.string().min(1))
+        .default([])
+        .describe("Literal text excluded from capture payloads, byte/numeric projections, producer coordinates, artifact paths/digests and diagnostic text. Declaration strings are never persisted in Evidence parameters. Canonical contract keys, enums and provider identities remain intact."),
+});
+const pointerSchema = z
+    .string()
+    .describe("RFC 6901 pointer in the producer's reported object.");
+const redactionSchema = z.union([
+    z.strictObject({
+        pointer: pointerSchema,
+        reason: z.enum(["transport-credential", "explicit-sensitive-value"]),
+    }),
+    z.strictObject({
+        pointer: pointerSchema,
+        reason: z.literal("explicit-sensitive-value"),
+        scope: z
+            .literal("property-name")
+            .describe("An omitted property name; pointer identifies its actual parent, not an invented child coordinate."),
+    }),
+]);
+const binaryBase = {
+    pointer: pointerSchema,
+    representation: z.enum(["producer-bytes", "har-base64-content"]),
+};
+const binarySchema = z.discriminatedUnion("state", [
+    z.strictObject({
+        ...binaryBase,
+        state: z.literal("retained"),
+        content_base64: z.string(),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    }),
+    z.strictObject({
+        ...binaryBase,
+        state: z.literal("redacted"),
+        content_base64: z.null(),
+        bytes: z.null(),
+        sha256: z.null(),
+    }),
+]);
+const numberSchema = z.strictObject({
+    pointer: pointerSchema,
+    producer_type: z.enum(["json-number", "integer", "float"]),
+    literal: z.string(),
+});
+/** Preserve producer representations with independent sidecars rather than invented browser IDs. */
+export const webNetworkCaptureRecordSchema = z.strictObject({
+    ordinal: z.number().int().nonnegative(),
+    location: z.discriminatedUnion("kind", [
+        z.strictObject({
+            kind: z.literal("unknown"),
+            reason: z.literal("explicit-sensitive-value"),
+        }),
+        z.strictObject({ kind: z.literal("json-pointer"), pointer: pointerSchema }),
+        z.strictObject({
+            kind: z.literal("byte-range"),
+            offset: z.number().int().nonnegative(),
+            bytes: z.number().int().positive(),
+        }),
+    ]),
+    reported: jsonValueSchema,
+    binary_fields: z.array(binarySchema),
+    numeric_literals: z.array(numberSchema),
+    redactions: z.array(redactionSchema),
+    limitations: z.array(z.string()),
+});
+/** Historical capture inspection has file identity, producer provenance and explicit unknowns. */
+export const webNetworkCaptureSchema = z.strictObject({
+    artifact: z.strictObject({
+        path: z
+            .string()
+            .describe("Selected artifact path; empty when explicitly excluded from Evidence."),
+        sha256: z
+            .string()
+            .regex(/^[0-9a-f]{64}$/)
+            .nullable()
+            .describe("Observed artifact SHA-256; null only when explicitly excluded by a sensitive declaration."),
+        bytes: z.number().int().nonnegative(),
+    }),
+    format: z.enum(["har", "mitmproxy"]),
+    decoder: z.strictObject({
+        id: z.string().min(1),
+        name: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    container: z.strictObject({
+        reported: jsonValueSchema,
+        numeric_literals: z.array(numberSchema),
+        redactions: z.array(redactionSchema),
+        records_pointer: pointerSchema.nullable(),
+    }),
+    total_records: z.number().int().nonnegative(),
+    records: z.array(webNetworkCaptureRecordSchema),
+    runtime_attribution: z.literal("unknown"),
+    limitations: z.array(z.string()),
+});

package/dist/domain/webNetworkCaptureCoordinates.js

@@ -0,0 +1,58 @@
+import { redactExplicitText } from "./explicitSensitiveValues.js";
+/** Exclude marked source coordinates without inventing a substitute record identity. */
+export const excludeCaptureCoordinates = (value, sensitiveValues) => {
+    if (sensitiveValues.length === 0)
+        return value;
+    let excluded = false;
+    const sensitive = (pointer) => sensitiveValues.some((literal) => pointer.includes(literal));
+    const sidecars = (items) => items.filter((item) => {
+        if (!sensitive(item.pointer))
+            return true;
+        excluded = true;
+        return false;
+    });
+    const records = value.records.map((record) => {
+        const location = (record.location.kind === "json-pointer" &&
+            sensitive(record.location.pointer)) ||
+            (record.location.kind === "byte-range" &&
+                (sensitive(String(record.location.offset)) ||
+                    sensitive(String(record.location.bytes))))
+            ? {
+                kind: "unknown",
+                reason: "explicit-sensitive-value",
+            }
+            : record.location;
+        if (location !== record.location)
+            excluded = true;
+        return {
+            ...record,
+            location,
+            binary_fields: sidecars(record.binary_fields),
+            numeric_literals: sidecars(record.numeric_literals),
+            redactions: sidecars(record.redactions),
+        };
+    });
+    const recordsPointer = value.container.records_pointer;
+    const records_pointer = recordsPointer !== null && sensitive(recordsPointer)
+        ? null
+        : recordsPointer;
+    if (records_pointer !== recordsPointer)
+        excluded = true;
+    const container = {
+        ...value.container,
+        records_pointer,
+        numeric_literals: sidecars(value.container.numeric_literals),
+        redactions: sidecars(value.container.redactions),
+    };
+    return {
+        ...value,
+        container,
+        records,
+        limitations: excluded
+            ? [
+                ...value.limitations,
+                redactExplicitText("Marked source coordinates and their sidecars are excluded; affected record locations remain unknown.", sensitiveValues),
+            ]
+            : value.limitations,
+    };
+};

package/dist/dotnet/ManagedExceptionRegionValidation.js

@@ -0,0 +1,41 @@
+const clauseFlagsIssue = (region) => [0, 1, 2, 4].includes(region.flags)
+    ? null
+    : `Exception clause has unsupported flags 0x${region.flags.toString(16)}`;
+const methodExtentIssue = (start, length, ilSize, name) => start <= ilSize && length <= ilSize - start
+    ? null
+    : `Exception clause ${name} range leaves the method IL body`;
+const instructionBoundaryIssue = (start, length, boundaries, name) => {
+    const end = start + length;
+    return boundaries.has(start) && boundaries.has(end)
+        ? null
+        : `Exception clause ${name} range does not align with CIL instruction boundaries`;
+};
+const filterOrderingIssue = (region, ilSize) => {
+    if (region.flags !== 1)
+        return null;
+    const offset = region.filter_offset;
+    return offset !== null && offset < ilSize && offset < region.handler_offset
+        ? null
+        : "Exception clause filter must start before its handler within the method IL body";
+};
+const clauseIssue = (region, ilSize, boundaries) => clauseFlagsIssue(region) ??
+    methodExtentIssue(region.try_offset, region.try_length, ilSize, "try") ??
+    instructionBoundaryIssue(region.try_offset, region.try_length, boundaries, "try") ??
+    methodExtentIssue(region.handler_offset, region.handler_length, ilSize, "handler") ??
+    instructionBoundaryIssue(region.handler_offset, region.handler_length, boundaries, "handler") ??
+    (region.flags === 1 && region.filter_offset !== null
+        ? instructionBoundaryIssue(region.filter_offset, 0, boundaries, "filter")
+        : null) ??
+    filterOrderingIssue(region, ilSize);
+/** Validate EH extents and instruction boundaries while retaining each clause. */
+export const validateExceptionRegionRanges = (parsed, ilSize, instructionOffsets) => {
+    if (parsed.status === "malformed")
+        return parsed;
+    const boundaries = new Set([...instructionOffsets, ilSize]);
+    for (const region of parsed.regions) {
+        const issue = clauseIssue(region, ilSize, boundaries);
+        if (issue !== null)
+            return { status: "malformed", regions: parsed.regions, issue };
+    }
+    return parsed;
+};

package/dist/dotnet/ManagedMemberInspector.js

@@ -68,9 +68,11 @@ export const inspectManagedMembersBytes = (bytes, target) => {
         const { layout, inventory } = readMemberInventory(bytes, pe);
         issues.push(...inventory.issues);
         const ranges = typeRanges(bytes, layout);
-        const types = parseTypes(bytes, layout, ranges);
+        const parsedTypes = parseTypes(bytes, layout, ranges);
+        issues.push(...parsedTypes.issues);
         const fields = parseFields(bytes, layout, ranges);
         const memberRefs = parseMemberRefs(bytes, layout);
+        issues.push(...memberRefs.issues);
         const methods = parseMethods({
             bytes,
             layout,
@@ -97,7 +99,7 @@ export const inspectManagedMembersBytes = (bytes, target) => {
                 requires_artifact_sha256: target.sha256,
                 requires_mvid: inventory.module?.mvid ?? null,
             },
-            types,
+            types: parsedTypes.types,
             fields: fields.fields,
             methods: methods.methods,
             member_refs: memberRefs.refs,

package/dist/dotnet/ManagedMemberInspectorCore.js

@@ -1,6 +1,6 @@
 import { managedFailure, ManagedReaderFailure, } from "./ManagedReaderFailure.js";
 import {} from "./ManagedMetadataLayout.js";
-import { metadataRowCursor, metadataCodedToken, metadataToken, readMetadataString, sha256Bytes, } from "./ManagedMetadataHeaps.js";
+import { metadataRowCursor, metadataCodedToken, metadataCodedTokenInvalidReason, metadataToken, readMetadataString, sha256Bytes, } from "./ManagedMetadataHeaps.js";
 const rowRange = (table, start, nextStart) => {
     const total = table?.rowCount ?? 0;
     if (total === 0 || start === 0)
@@ -97,17 +97,27 @@ export const parseTypes = (bytes, layout, ranges) => {
     const fields = layout.table(4);
     const methods = layout.table(6);
     const items = [];
+    const issues = [];
     for (let row = 1; row <= (typeTable?.rowCount ?? 0); row += 1) {
         const cursor = metadataRowCursor(bytes, layout, 2, row);
         const flags = cursor.readUInt32();
         const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), layout.strings.size);
         const namespace = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), layout.strings.size);
+        const extendsOffset = cursor.offset;
         const extendsRaw = cursor.readIndex(layout.codedIndexSize("TypeDefOrRef"));
         const fieldStart = cursor.readIndex(layout.tableIndexSize(4));
         const methodStart = cursor.readIndex(layout.tableIndexSize(6));
         const nextRange = ranges[row] ?? null;
         const fieldRange = rowRange(fields, fieldStart, nextRange?.fieldStart ?? 0);
         const methodRange = rowRange(methods, methodStart, nextRange?.methodStart ?? 0);
+        const extendsReason = metadataCodedTokenInvalidReason(extendsRaw, 2, [2, 1, 27], layout.rowCounts);
+        if (extendsReason !== null)
+            issues.push({
+                code: "invalid-row",
+                scope: `metadata.TypeDef:${metadataToken(2, row)}`,
+                offset: extendsOffset,
+                detail: `TypeDef Extends coded index 0x${extendsRaw.toString(16)} is invalid: ${extendsReason}`,
+            });
         items.push({
             token: metadataToken(2, row),
             row_offset: cursor.start,
@@ -115,7 +125,7 @@ export const parseTypes = (bytes, layout, ranges) => {
             name,
             full_name: fullName(namespace, name),
             flags,
-            extends_token: metadataCodedToken(extendsRaw, 2, [2, 1, 27]),
+            extends_token: metadataCodedToken(extendsRaw, 2, [2, 1, 27], layout.rowCounts),
             field_list: {
                 first_row: fieldRange.first,
                 last_row: fieldRange.last,
@@ -128,7 +138,7 @@ export const parseTypes = (bytes, layout, ranges) => {
             },
         });
     }
-    return items;
+    return { types: items, issues };
 };
 const readCompressed = (bytes, offset) => {
     const first = bytes[offset];
@@ -171,42 +181,38 @@ const ELEMENT_TYPES = new Map([
     [0x19, "native-uint"],
     [0x1c, "object"],
 ]);
-const ELEMENT_TYPE_SUFFIXES = new Map([
-    [0x0f, "*"],
-    [0x10, "&"],
-]);
 const readTypeSignature = (blob, offset) => {
-    const kind = blob[offset];
+    const suffixes = [];
+    let cursor = offset;
+    let kind = blob[cursor];
+    while (kind === 0x0f || kind === 0x10 || kind === 0x1d) {
+        suffixes.push(kind === 0x0f ? "*" : kind === 0x10 ? "&" : "[]");
+        cursor += 1;
+        kind = blob[cursor];
+    }
     if (kind === undefined)
-        throw managedFailure("invalid-blob", "signature", "truncated type signature", offset);
+        throw managedFailure("invalid-blob", "signature", "truncated type signature", cursor);
     const named = ELEMENT_TYPES.get(kind);
-    if (named !== undefined)
-        return { value: named, next: offset + 1 };
-    const suffix = ELEMENT_TYPE_SUFFIXES.get(kind);
-    if (suffix !== undefined) {
-        const inner = readTypeSignature(blob, offset + 1);
-        return { value: `${inner.value}${suffix}`, next: inner.next };
-    }
-    if (kind === 0x11 || kind === 0x12) {
-        const token = readCompressed(blob, offset + 1);
-        return {
-            value: `${kind === 0x11 ? "valuetype" : "class"}:${String(token.value)}`,
-            next: token.next,
-        };
+    let value;
+    let next;
+    if (named !== undefined) {
+        value = named;
+        next = cursor + 1;
     }
-    if (kind === 0x1d) {
-        const inner = readTypeSignature(blob, offset + 1);
-        return { value: `${inner.value}[]`, next: inner.next };
+    else if (kind === 0x11 || kind === 0x12) {
+        const token = readCompressed(blob, cursor + 1);
+        value = `${kind === 0x11 ? "valuetype" : "class"}:${String(token.value)}`;
+        next = token.next;
     }
-    if (kind === 0x1e) {
-        const variable = readCompressed(blob, offset + 1);
-        return { value: `mvar:${String(variable.value)}`, next: variable.next };
+    else if (kind === 0x1e || kind === 0x13) {
+        const variable = readCompressed(blob, cursor + 1);
+        value = `${kind === 0x1e ? "mvar" : "var"}:${String(variable.value)}`;
+        next = variable.next;
     }
-    if (kind === 0x13) {
-        const variable = readCompressed(blob, offset + 1);
-        return { value: `var:${String(variable.value)}`, next: variable.next };
+    else {
+        throw managedFailure("unsupported-signature", "signature", `unsupported element type 0x${kind.toString(16)}`, cursor);
     }
-    throw managedFailure("unsupported-signature", "signature", `unsupported element type 0x${kind.toString(16)}`, offset);
+    return { value: value + suffixes.reverse().join(""), next };
 };
 const callingConvention = (value) => {
     const base = value & 0x0f;

package/dist/dotnet/ManagedMemberInstructionDecoder.js

@@ -1,4 +1,11 @@
 const opcode = (code) => OPCODES.get(code);
+const PREFIX_OPCODES = new Set([
+    "unaligned.",
+    "volatile.",
+    "tail.",
+    "constrained.",
+    "readonly.",
+]);
 const OPCODES = new Map([
     [0x00, { name: "nop", operand: "none" }],
     [0x01, { name: "break", operand: "none" }],
@@ -344,7 +351,9 @@ const readOperand = (il, offset, kind) => {
 };
 export const decodeInstructions = (il) => {
     const parsed = [];
+    const instructionStarts = [];
     let offset = 0;
+    let prefixStart = null;
     let issue = null;
     try {
         while (offset < il.length) {
@@ -363,6 +372,13 @@ export const decodeInstructions = (il) => {
                 break;
             }
             offset = operand.next;
+            if (PREFIX_OPCODES.has(descriptor.name)) {
+                prefixStart ??= start;
+            }
+            else {
+                instructionStarts.push(prefixStart ?? start);
+                prefixStart = null;
+            }
             parsed.push({
                 offset: start,
                 opcode: descriptor.name,
@@ -376,7 +392,7 @@ export const decodeInstructions = (il) => {
             cause instanceof Error ? cause.message : "Instruction decode failed";
     }
     const truncated = offset < il.length && issue === null ? 1 : 0;
-    return { parsed, count: parsed.length, truncated, issue };
+    return { parsed, instructionStarts, count: parsed.length, truncated, issue };
 };
 export const parseExceptionRegions = (bytes, offset, methodEnd) => {
     const regions = [];
@@ -387,10 +403,10 @@ export const parseExceptionRegions = (bytes, offset, methodEnd) => {
             sectionOffset < 0 ||
             sectionOffset > methodEnd - 4 ||
             sectionOffset > bytes.length - 4)
-            return malformedExceptionRegions("Exception section header leaves artifact");
+            return malformedExceptionRegions("Exception section header leaves artifact", regions);
         const kind = bytes.readUInt8(sectionOffset);
         if ((kind & 0x3f) !== 1)
-            return malformedExceptionRegions(`Unsupported method data section kind ${String(kind & 0x3f)}`);
+            return malformedExceptionRegions(`Unsupported method data section kind ${String(kind & 0x3f)}`, regions);
         const fat = (kind & 0x40) !== 0;
         const size = fat
             ? bytes.readUInt8(sectionOffset + 1) |
@@ -401,12 +417,12 @@ export const parseExceptionRegions = (bytes, offset, methodEnd) => {
         if (size < 4 ||
             sectionOffset > methodEnd - size ||
             sectionOffset > bytes.length - size)
-            return malformedExceptionRegions("Exception section size leaves artifact");
+            return malformedExceptionRegions("Exception section size leaves artifact", regions);
         if ((size - 4) % clauseSize !== 0)
-            return malformedExceptionRegions("Exception section size does not contain whole clauses");
+            return malformedExceptionRegions("Exception section size does not contain whole clauses", regions);
         if (!fat &&
             (bytes[sectionOffset + 2] !== 0 || bytes[sectionOffset + 3] !== 0))
-            return malformedExceptionRegions("Small exception section reserved bytes are nonzero");
+            return malformedExceptionRegions("Small exception section reserved bytes are nonzero", regions);
         const count = (size - 4) / clauseSize;
         regions.push(...readExceptionClauses(bytes, sectionOffset + 4, count, fat));
         hasMoreSections = (kind & 0x80) !== 0;
@@ -414,7 +430,7 @@ export const parseExceptionRegions = (bytes, offset, methodEnd) => {
     }
     return { status: "complete", regions };
 };
-const malformedExceptionRegions = (issue) => ({ status: "malformed", regions: [], issue });
+const malformedExceptionRegions = (issue, regions = []) => ({ status: "malformed", regions, issue });
 const readExceptionClauses = (bytes, start, count, fat) => {
     const regions = [];
     const clauseSize = fat ? 24 : 12;

package/dist/dotnet/ManagedMemberRows.js

@@ -1,5 +1,5 @@
 import { createDeclaringTypeLookup, signature, } from "./ManagedMemberInspectorCore.js";
-import { metadataToken, metadataRowCursor, metadataCodedToken, readMetadataBlob, readMetadataString, } from "./ManagedMetadataHeaps.js";
+import { metadataToken, metadataRowCursor, metadataCodedToken, metadataCodedTokenInvalidReason, readMetadataBlob, readMetadataString, } from "./ManagedMetadataHeaps.js";
 import { methodBody } from "./ManagedMethodBodyReader.js";
 export const parseFields = (bytes, layout, ranges) => {
     const fields = [];
@@ -29,6 +29,7 @@ export const parseFields = (bytes, layout, ranges) => {
 export const parseMemberRefs = (bytes, layout) => {
     const refs = [];
     const core = new Map();
+    const issues = [];
     const table = layout.table(10);
     for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
         const cursor = metadataRowCursor(bytes, layout, 10, row);
@@ -36,16 +37,26 @@ export const parseMemberRefs = (bytes, layout) => {
         const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), layout.strings.size);
         const sig = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), layout.blob.size);
         const token = metadataToken(10, row);
+        const parentReason = metadataCodedTokenInvalidReason(parentRaw, 3, [2, 1, 26, 6, 27], layout.rowCounts);
+        if (parentReason !== null || parentRaw === 0)
+            issues.push({
+                code: "invalid-row",
+                scope: `metadata.MemberRef:${token}`,
+                offset: cursor.start,
+                detail: parentReason === null
+                    ? "MemberRef parent coded index 0x0 is null, but the Class column must reference a row"
+                    : `MemberRef parent coded index 0x${parentRaw.toString(16)} is invalid: ${parentReason}`,
+            });
         refs.push({
             token,
             row_offset: cursor.start,
-            parent_token: metadataCodedToken(parentRaw, 3, [2, 1, 26, 6, 27]),
+            parent_token: metadataCodedToken(parentRaw, 3, [2, 1, 26, 6, 27], layout.rowCounts),
             name,
             signature: signature(sig),
         });
         core.set(token, { token, name });
     }
-    return { refs, core };
+    return { refs, core, issues };
 };
 export const parseMethods = ({ bytes, layout, pe, ranges, }) => {
     const methods = [];

package/dist/dotnet/ManagedMetadataHeaps.js

@@ -140,11 +140,29 @@ export const metadataRowCursor = (bytes, layout, table, row) => {
     return new MetadataRowCursor(bytes, start, start + descriptor.rowSize, `metadata.${descriptor.name}`);
 };
 /** Decode a metadata coded index without signed 32-bit coercion. */
-export const metadataCodedToken = (raw, bits, tables) => {
+export const metadataCodedToken = (raw, bits, tables, rowCounts) => {
     if (raw === 0)
         return null;
     const tag = raw & (2 ** bits - 1);
     const row = Math.floor(raw / 2 ** bits);
     const table = tables[tag];
-    return table === undefined || row === 0 ? null : metadataToken(table, row);
+    return table === undefined || row === 0 || row > (rowCounts[table] ?? 0)
+        ? null
+        : metadataToken(table, row);
+};
+/** Explain why a non-null coded index cannot name an admitted metadata row. */
+export const metadataCodedTokenInvalidReason = (raw, bits, tables, rowCounts) => {
+    if (raw === 0)
+        return null;
+    const tag = raw & (2 ** bits - 1);
+    const row = Math.floor(raw / 2 ** bits);
+    const table = tables[tag];
+    if (table === undefined)
+        return `coded index tag ${tag} is not defined`;
+    if (row === 0)
+        return `coded index selects row zero in table ${table}`;
+    const count = rowCounts[table] ?? 0;
+    return row > count
+        ? `coded index selects row ${row} in table ${table}, which has ${count} rows`
+        : null;
 };