From 7df462cbfa837ba7f082eaa20903b4eaf691f959 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:03:27 -0500 Subject: [PATCH] feat(managed): retain unresolved definition coordinates (#12462) * feat(managed): retain unresolved definition coordinates * fix(managed): describe unresolved definition scope in summaries * test(managed): isolate the selected coordinate fixture * test(managed): use owned member scope guidance * test(managed): use historical evidence for unknown method scope --------- Co-authored-by: Cursor Agent --- .../references/native-and-artifacts.md | 3 +- .../references/native-and-artifacts.md | 3 +- docs/guides/managed/managed-code-analysis.md | 11 + src/contracts/managed/managedToolContracts.ts | 2 +- .../analysisView/managedMemberView.test.ts | 10 + src/domain/analysisView/managedMemberView.ts | 74 ++++++- .../analysisView/managedMemberViewSchemas.ts | 15 ++ src/domain/managed/managedArtifact.ts | 10 + .../managed/managedMemberInspectorCore.ts | 43 +++- src/domain/managed/managedReaderFailure.ts | 22 +- .../managed/managedTypeDefinitionRows.ts | 3 + .../managed/managedUnresolvedDefinitions.ts | 190 ++++++++++++++++++ src/dotnet/ManagedMemberInspector.test.ts | 55 +++++ src/dotnet/ManagedMemberInspector.ts | 10 + src/dotnet/ManagedMemberRecovery.ts | 19 +- src/dotnet/ManagedMemberRows.ts | 37 +++- src/dotnet/ManagedMemberTypeInventory.test.ts | 29 +++ .../managedUnresolvedModuleName.test.ts | 134 +++++++++++- .../mcp/managedMemberSummaryMcp.test.ts | 13 +- ...anagedMemberComparisonFromMetadata.test.ts | 3 +- .../managedApplicationGraph.test.ts | 9 +- 21 files changed, 656 insertions(+), 39 deletions(-) create mode 100644 src/domain/managed/managedUnresolvedDefinitions.ts diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index db398d05df..46c62ecb2d 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -738,7 +738,8 @@ for one selected type. For questions about a selected type, select names), coverage and per-collection counts. Page rows with `view: {kind: "managed-members", collection: "call_edges", offset: 0, limit: 64}` over `types`, `exported_types`, `fields`, `methods`, `member_refs`, `call_edges`, -`field_accesses` or `user_strings`. +`field_accesses`, `user_strings` or `unresolved_definitions`. The last collection +pages checked TypeDef and MethodDef coordinates with failed name columns. Use exact `names` and `declaring_types` filters before paging supported collections. For a compact method lookup, request `fields: ["name", "declaring_type", "signature"]`; omit `body` to avoid anchors. Identity tokens, diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index db398d05df..46c62ecb2d 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -738,7 +738,8 @@ for one selected type. For questions about a selected type, select names), coverage and per-collection counts. Page rows with `view: {kind: "managed-members", collection: "call_edges", offset: 0, limit: 64}` over `types`, `exported_types`, `fields`, `methods`, `member_refs`, `call_edges`, -`field_accesses` or `user_strings`. +`field_accesses`, `user_strings` or `unresolved_definitions`. The last collection +pages checked TypeDef and MethodDef coordinates with failed name columns. Use exact `names` and `declaring_types` filters before paging supported collections. For a compact method lookup, request `fields: ["name", "declaring_type", "signature"]`; omit `body` to avoid anchors. Identity tokens, diff --git a/docs/guides/managed/managed-code-analysis.md b/docs/guides/managed/managed-code-analysis.md index 47ab07f0f5..6e2749d35f 100644 --- a/docs/guides/managed/managed-code-analysis.md +++ b/docs/guides/managed/managed-code-analysis.md @@ -113,6 +113,17 @@ TypeDef, MethodDef, or Field name leaves member inventory and cross-build comparison coverage partial when the unreadable name could affect a match. A nil TypeDef namespace is valid and leaves the type name unqualified. +Member inspection records readable row coordinates for unresolved names in +`unresolved_definitions`. It reports the TypeDef or MethodDef token, file offset, +and each failed Name or Namespace column with its original heap index. Method +rows also retain the raw RVA and any known declaring TypeDef token. TypeDef +coordinates cover the assembly-wide name scan. MethodDef coordinates cover the +source method interval and any exact declaring-type selection. Use +`inspect_analysis_view` with `kind: "managed-members"` and +`collection: "unresolved_definitions"` to page retained coordinates. A missing +collection in earlier Evidence means the inspection did not record it. When +capacity recovery keeps only the type inventory, `method_names_examined` is false. + If the metadata root declares both compressed (`#~`) and uncompressed (`#-`) tables, REA reports both declarations and leaves the row layout unresolved. The metadata version and PE/CLI evidence remain available. Member inventories, diff --git a/src/contracts/managed/managedToolContracts.ts b/src/contracts/managed/managedToolContracts.ts index 9c9ffdefde..fa058fd825 100644 --- a/src/contracts/managed/managedToolContracts.ts +++ b/src/contracts/managed/managedToolContracts.ts @@ -88,7 +88,7 @@ export const MANAGED_TOOL_CONTRACTS = [ retainedSummary: { evidenceParameters: "omit-detail" }, ...toolContractMetadata("inspect_managed_members", evidenceEffects), description: - "Inspect PE/CLI types, members, signatures, CIL hashes/instruction tuples, exception regions, static calls, field accesses and loaded #US strings without executing code. type_names selects exact declaring types and their body literals; assembly-wide member_refs/exported_types are still included. Tokens remain local to artifact SHA-256/MVID; tuple hashes do not resolve them or fully commit control flow. Default complete returns collections; detail summary retains them for inspect_analysis_view kind managed-members using parent_evidence_id. Page types/exported_types/fields/methods/member_refs/call_edges/field_accesses/user_strings; exact names/declaring_types and fields narrow supported rows. Omit body to avoid IL anchors. Unmatched names and incomplete coverage stay explicit.", + "Inspect PE/CLI types, members, signatures, CIL hashes/instruction tuples, exception regions, static calls, field accesses and loaded #US strings without executing code. type_names selects exact declaring types and their body literals; assembly-wide member_refs/exported_types are still included. Tokens remain local to artifact SHA-256/MVID; tuple hashes do not resolve them or fully commit control flow. Default complete returns collections; detail summary retains them for inspect_analysis_view kind managed-members using parent_evidence_id. Page types/exported_types/fields/methods/member_refs/call_edges/field_accesses/user_strings or unresolved_definitions for checked rows with failed name columns. Exact names/declaring_types and fields narrow supported rows. Omit body to avoid IL anchors. Unmatched names and incomplete coverage stay explicit.", kind: "managed-provider", inputSchema: managedMembersInputSchema, outputSchema: memberOutputSchema, diff --git a/src/domain/analysisView/managedMemberView.test.ts b/src/domain/analysisView/managedMemberView.test.ts index 3f2360a39f..28093b5c86 100644 --- a/src/domain/analysisView/managedMemberView.test.ts +++ b/src/domain/analysisView/managedMemberView.test.ts @@ -48,6 +48,16 @@ it("keeps unexamined collections unknown while normalizing immutable managed par field_accesses: [], }; const input = parent(freezeOwnedJsonTreeSnapshot(unexamined)); + const coordinates = managedMembersViewRequestSchema.parse({ + kind: "managed-members", + collection: "unresolved_definitions", + offset: 0, + limit: 1, + }); + expect(projectManagedMemberView(input, coordinates)).toMatchObject({ + ok: false, + error: { _tag: "AnalysisInputError" }, + }); for (let attempt = 0; attempt < 2; attempt++) { expect(projectManagedMemberView(input, { kind: "summary" })).toMatchObject({ ok: true, diff --git a/src/domain/analysisView/managedMemberView.ts b/src/domain/analysisView/managedMemberView.ts index d601ea3e58..8b21633ec4 100644 --- a/src/domain/analysisView/managedMemberView.ts +++ b/src/domain/analysisView/managedMemberView.ts @@ -31,6 +31,17 @@ import type { ManagedMemberViewRow as Row, } from "./managedMemberViewSchemas.js"; +export const MANAGED_MEMBER_SCOPE_GUIDANCE = { + selectedNominalRows: + "Exported types and member references cover the whole assembly. Named type rows, fields, methods, call edges, field accesses and user strings follow the declaring-type selection.", + unresolvedTypeRows: + "Unresolved TypeDef coordinates cover the assembly-wide name scan.", + unresolvedMethodRows: + "Unresolved MethodDef coordinates follow the recorded source method interval and any declaring-type selection.", + unexaminedMethodRows: + "MethodDef name coordinates are unavailable in this capacity recovery.", +} as const; + type Selection = { readonly collection: C; readonly rows: readonly T[] | null | undefined; @@ -129,9 +140,30 @@ const collectionPage = ( }, view, ); + case "unresolved_definitions": + return sliceMemberRows( + collection, + report.unresolved_definitions?.rows, + view, + ); } }; +const sliceMemberRows = ( + collection: C, + rows: readonly T[] | undefined, + view: { readonly offset: number; readonly limit: number }, +) => + rows === undefined + ? null + : { + page: { + collection, + rows: rows.slice(view.offset, view.offset + view.limit), + }, + total: rows.length, + }; + /** Keep only one page while counting matches; never copy the matched inventory. */ const selectRows = < C extends MemberCollection, @@ -151,16 +183,12 @@ const selectRows = < ? new Set(view.declaring_types) : undefined; const fields = - view.fields === undefined ? undefined : new Set(view.fields); + "fields" in view && view.fields !== undefined + ? new Set(view.fields) + : undefined; const filtering = names !== undefined || declaringTypes !== undefined; if (!filtering && fields === undefined) - return { - page: { - collection: source.collection, - rows: source.rows.slice(view.offset, view.offset + view.limit), - }, - total: source.rows.length, - }; + return sliceMemberRows(source.collection, source.rows, view); const selected: (Partial & Pick & { source_index: number })[] = []; const start = filtering ? 0 : Math.min(view.offset, source.rows.length); const end = filtering @@ -257,10 +285,17 @@ const summarizeMembers = ( call_edges, field_accesses, user_strings, + unresolved_definitions, ...identity } = report; return { ...identity, + ...(unresolved_definitions === undefined + ? {} + : { + unresolved_method_names_examined: + unresolved_definitions.method_names_examined, + }), user_strings: user_strings === null ? null @@ -274,6 +309,9 @@ const summarizeMembers = ( call_edges: call_edges.length, field_accesses: field_accesses.length, user_strings: user_strings?.literals.length ?? null, + ...(unresolved_definitions === undefined + ? {} + : { unresolved_definitions: unresolved_definitions.rows.length }), }, }; }; @@ -312,6 +350,7 @@ export const projectManagedMemberView = ( parent.evidenceId, ); if (!scope.ok) return scope; + const coordinates = report.unresolved_definitions; const shared = { parent_evidence_id: parent.evidenceId, parent_operation: "inspect_managed_members" as const, @@ -321,9 +360,15 @@ export const projectManagedMemberView = ( unknowns: [ "Collection counts and pages cover producer-returned rows; member completeness remains the original coverage, not an absence claim about unreturned rows.", ...(report.selection === null + ? [] + : [MANAGED_MEMBER_SCOPE_GUIDANCE.selectedNominalRows]), + ...(coordinates === undefined ? [] : [ - "Exported types and member references cover the whole assembly; the other collections cover only the selected declaring types.", + MANAGED_MEMBER_SCOPE_GUIDANCE.unresolvedTypeRows, + coordinates.method_names_examined + ? MANAGED_MEMBER_SCOPE_GUIDANCE.unresolvedMethodRows + : MANAGED_MEMBER_SCOPE_GUIDANCE.unexaminedMethodRows, ]), ...managedViewIdentityUnknowns( parent, @@ -352,7 +397,10 @@ export const projectManagedMemberView = ( { path: ["view", "collection"], reason: "invalid_value", - message: `The parent Evidence did not examine ${view.collection}; repeat inspect_managed_members with the current runtime to record it.`, + message: + view.collection === "unresolved_definitions" + ? "The parent Evidence did not record unresolved_definitions. Repeat inspect_managed_members to obtain checked coordinates." + : `The parent Evidence did not examine ${view.collection}; repeat inspect_managed_members with the current runtime to record it.`, }, ]), ); @@ -376,6 +424,12 @@ export const projectManagedMemberView = ( identity_scope: report.identity_scope, selection: report.selection, method_rows: report.method_rows, + ...(view.collection === "unresolved_definitions" && + coordinates !== undefined + ? { + unresolved_method_names_examined: coordinates.method_names_examined, + } + : {}), source_metadata_status: report.metadata.status, ...(report.metadata.unresolved_module_name === undefined ? {} diff --git a/src/domain/analysisView/managedMemberViewSchemas.ts b/src/domain/analysisView/managedMemberViewSchemas.ts index 6f623a51e4..0709be2ac0 100644 --- a/src/domain/analysisView/managedMemberViewSchemas.ts +++ b/src/domain/analysisView/managedMemberViewSchemas.ts @@ -1,5 +1,6 @@ import { z } from "zod"; import { managedMemberInspectionSchema } from "../managed/managedArtifact.js"; +import { unresolvedDefinitionSchema } from "../managed/managedUnresolvedDefinitions.js"; const member = managedMemberInspectionSchema.shape; @@ -12,6 +13,7 @@ const rows = { call_edges: member.call_edges.element, field_accesses: member.field_accesses.element, user_strings: member.user_strings.unwrap().shape.literals.element, + unresolved_definitions: unresolvedDefinitionSchema, }; const pageRequest = { kind: z.literal("managed-members"), @@ -89,6 +91,10 @@ export const managedMembersViewRequestSchema = z.discriminatedUnion( collection: z.literal("user_strings"), fields: fieldsOf(rows.user_strings.keyof()), }), + z.strictObject({ + ...pageRequest, + collection: z.literal("unresolved_definitions"), + }), ], ); @@ -155,6 +161,12 @@ export const managedMembersViewPageSchema = z.discriminatedUnion("collection", [ "user_strings", rows.user_strings.partial().required({ token: true, offset: true }), ), + z.strictObject({ + collection: z.literal("unresolved_definitions"), + rows: z.array(rows.unresolved_definitions), + source_count: z.int().nonnegative().exactOptional(), + unresolved_filter_rows: z.int().nonnegative().exactOptional(), + }), ]); const nullableCount = z.int().nonnegative().nullable(); @@ -170,6 +182,7 @@ export const managedMemberSummarySchema = z.strictObject({ identity_scope: member.identity_scope, selection: member.selection, method_rows: member.method_rows, + unresolved_method_names_examined: z.boolean().exactOptional(), coverage: member.coverage, user_strings: z .strictObject({ @@ -187,6 +200,7 @@ export const managedMemberSummarySchema = z.strictObject({ call_edges: z.int().nonnegative(), field_accesses: z.int().nonnegative(), user_strings: nullableCount, + unresolved_definitions: z.int().nonnegative().exactOptional(), }), }); @@ -200,6 +214,7 @@ export const managedMembersViewContextSchema = z.strictObject({ source_metadata_status: member.metadata.shape.status, unresolved_module_name: member.metadata.shape.unresolved_module_name, source_coverage: member.coverage, + unresolved_method_names_examined: z.boolean().exactOptional(), }); export type ManagedMembersViewRequest = z.infer< diff --git a/src/domain/managed/managedArtifact.ts b/src/domain/managed/managedArtifact.ts index 27291d8e9f..24a1fa6204 100644 --- a/src/domain/managed/managedArtifact.ts +++ b/src/domain/managed/managedArtifact.ts @@ -4,6 +4,10 @@ import type { CoverageStatus } from "../coverage.js"; import { digestSchema } from "../digests.js"; import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; import { managedFieldConstantSchema } from "./managedFieldConstant.js"; +import { + unresolvedDefinitionsSchema, + validateUnresolvedDefinitions, +} from "./managedUnresolvedDefinitions.js"; /** Build-local ECMA-335 metadata token emitted as an eight-digit lowercase hex value. */ export const managedMetadataTokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u); @@ -630,6 +634,11 @@ export const managedMemberInspectionSchema = z .describe( "Examined zero-based MethodDef row interval before declaring-type selection; null means the row scope was not recorded. Row coordinates are build-local and cannot prove cross-build member absence for a page.", ), + unresolved_definitions: unresolvedDefinitionsSchema + .exactOptional() + .describe( + "Checked build-local TypeDef and MethodDef rows whose names could not be established. Omitted when the inspection did not record this projection.", + ), coverage: z.object({ state: managedInspectionStateSchema, issues: z.array(managedParseIssueSchema), @@ -637,6 +646,7 @@ export const managedMemberInspectionSchema = z limitations: z.array(z.string()), }) .superRefine((result, context) => { + validateUnresolvedDefinitions(result, context); if (result.signature_resolution !== null) return; // Null resolution means member decoding exceeded capacity, so no member was // examined; a member beside it would carry an unattested signature digest. diff --git a/src/domain/managed/managedMemberInspectorCore.ts b/src/domain/managed/managedMemberInspectorCore.ts index 1c8cce4e5a..17e976c7e8 100644 --- a/src/domain/managed/managedMemberInspectorCore.ts +++ b/src/domain/managed/managedMemberInspectorCore.ts @@ -13,6 +13,7 @@ import type { ManagedParseIssue, } from "./managedArtifact.js"; import { + admitManagedProjection, managedDecodeBudget, type ManagedDecodeBudget, } from "./managedDecodeBudget.js"; @@ -42,6 +43,10 @@ import type { TypeMemberListFacts, } from "./managedTypeMemberLists.js"; import type { TypeDefinitionRowFacts } from "./managedTypeDefinitionRows.js"; +import { + readDefinitionField, + type UnresolvedDefinition, +} from "./managedUnresolvedDefinitions.js"; import { sha256Hex } from "../../kernel/sha256Hex.js"; export type ManagedType = ManagedMemberInspection["types"][number]; @@ -84,6 +89,7 @@ interface TypeDefinition extends TypeRange { readonly row: number; readonly name: string | undefined; readonly namespace: string | undefined; + readonly unresolved: UnresolvedDefinition | null; } /** @@ -189,19 +195,43 @@ const readTypeDefinition = ( const { source } = current; const token = metadataToken(2, row); // Keep both independent name failures, but decode each heap coordinate once. - const namespace = readManagedValue( + const namespaceField = readDefinitionField( () => readMetadataString(bytes, layout, source.namespaceIndex), issues, + "Namespace", + source.namespaceOffset, + source.namespaceIndex, ); - const name = readManagedValue( + const nameField = readDefinitionField( () => readRequiredMetadataName(bytes, layout, "TypeDef", token, source), issues, + "Name", + source.nameOffset, + source.nameIndex, ); + const name = typeof nameField === "string" ? nameField : undefined; + const namespace = + typeof namespaceField === "string" ? namespaceField : undefined; + const unresolved = + name === undefined || namespace === undefined + ? admitManagedProjection( + { + kind: "TypeDef" as const, + token, + row_offset: source.rowOffset, + failed_fields: [nameField, namespaceField].filter( + (field) => typeof field !== "string", + ), + }, + managedDecodeBudget(layout), + ) + : null; return { source, row, name, namespace, + unresolved, token, fullName: namespace === undefined || name === undefined @@ -241,11 +271,13 @@ export const parseTypes = ( readonly types: readonly DecodedTypeDefinition[]; readonly issues: readonly ManagedParseIssue[]; readonly nesting: ManagedTypeNesting; + readonly unresolvedDefinitions: UnresolvedDefinition[]; } => { const fields = memberListTable(layout, 4); const methods = memberListTable(layout, 6); const items: DecodedTypeDefinition[] = []; const issues: ManagedParseIssue[] = []; + const unresolvedDefinitions: UnresolvedDefinition[] = []; const nesting = readManagedTypeNesting(bytes, layout, issues); for (const definition of definitions) { const { row, name, namespace, token } = definition; @@ -253,8 +285,11 @@ export const parseTypes = ( name === undefined || namespace === undefined || definition.fullName === null - ) + ) { + if (definition.unresolved !== null) + unresolvedDefinitions.push(definition.unresolved); continue; + } const { flags, extendsRaw, extendsOffset, rowOffset } = definition.source; const fieldRange = rowRange( fields, @@ -308,7 +343,7 @@ export const parseTypes = ( }, }); } - return { types: items, issues, nesting }; + return { types: items, issues, nesting, unresolvedDefinitions }; }; export const readCompressed = ( diff --git a/src/domain/managed/managedReaderFailure.ts b/src/domain/managed/managedReaderFailure.ts index 91c1b67a9e..31f3ddf6a2 100644 --- a/src/domain/managed/managedReaderFailure.ts +++ b/src/domain/managed/managedReaderFailure.ts @@ -60,6 +60,20 @@ export const managedFailure = ( ): ManagedReaderFailure => new ManagedReaderFailure({ code, scope, offset, detail }); +/** Retain a local malformed fact; capacity and unexpected failures still escape. */ +export const retainManagedValueFailure = ( + cause: unknown, + issues: ManagedParseIssue[], +): ManagedReaderFailure => { + if ( + !(cause instanceof ManagedReaderFailure) || + managedMetadataFailureStatus(cause.issue) === "partial" + ) + throw cause; + if (!(cause instanceof ManagedHeapAmbiguityFailure)) issues.push(cause.issue); + return cause; +}; + /** Retain one malformed item's location while allowing independent items to be read. */ export const readManagedValue = ( operation: () => Value, @@ -68,13 +82,7 @@ export const readManagedValue = ( try { return operation(); } catch (cause: unknown) { - if ( - !(cause instanceof ManagedReaderFailure) || - managedMetadataFailureStatus(cause.issue) === "partial" - ) - throw cause; - if (!(cause instanceof ManagedHeapAmbiguityFailure)) - issues.push(cause.issue); + retainManagedValueFailure(cause, issues); return undefined; } }; diff --git a/src/domain/managed/managedTypeDefinitionRows.ts b/src/domain/managed/managedTypeDefinitionRows.ts index 4e6aa3e76f..f807e018d2 100644 --- a/src/domain/managed/managedTypeDefinitionRows.ts +++ b/src/domain/managed/managedTypeDefinitionRows.ts @@ -9,6 +9,7 @@ export interface TypeDefinitionRowFacts { readonly nameIndex: number; readonly nameOffset: number; readonly namespaceIndex: number; + readonly namespaceOffset: number; readonly extendsRaw: number; readonly extendsOffset: number; readonly fieldListRaw: number; @@ -26,6 +27,7 @@ export const readTypeDefinitionRowFacts = ( const flags = cursor.u32(); const nameOffset = cursor.offset; const nameIndex = cursor.readIndex(layout.stringIndexSize); + const namespaceOffset = cursor.offset; const namespaceIndex = cursor.readIndex(layout.stringIndexSize); const extendsOffset = cursor.offset; const extendsRaw = cursor.readIndex(layout.codedIndexSize("TypeDefOrRef")); @@ -39,6 +41,7 @@ export const readTypeDefinitionRowFacts = ( nameIndex, nameOffset, namespaceIndex, + namespaceOffset, extendsRaw, extendsOffset, fieldListRaw, diff --git a/src/domain/managed/managedUnresolvedDefinitions.ts b/src/domain/managed/managedUnresolvedDefinitions.ts new file mode 100644 index 0000000000..cf5f30a223 --- /dev/null +++ b/src/domain/managed/managedUnresolvedDefinitions.ts @@ -0,0 +1,190 @@ +import { z } from "zod"; +import type { + ManagedMemberInspection, + ManagedParseIssue, +} from "./managedArtifact.js"; +import { + ManagedHeapAmbiguityFailure, + retainManagedValueFailure, +} from "./managedReaderFailure.js"; + +const uint32 = z.int().min(0).max(0xffff_ffff); +const typeToken = z.string().regex(/^0x02[0-9a-f]{6}$/u); +const methodToken = z.string().regex(/^0x06[0-9a-f]{6}$/u); + +const failedDefinitionFieldSchema = z.strictObject({ + field: z.enum(["Name", "Namespace"]), + field_offset: z.int().nonnegative(), + heap_index: uint32, + reason: z.enum([ + "ambiguous-string-heap", + "invalid-heap-index", + "invalid-string", + "empty-required-name", + ]), +}); + +const coordinates = { + row_offset: z.int().nonnegative(), + failed_fields: z.array(failedDefinitionFieldSchema).min(1).max(2), +}; + +export const unresolvedDefinitionSchema = z.discriminatedUnion("kind", [ + z.strictObject({ + kind: z.literal("TypeDef"), + token: typeToken, + ...coordinates, + }), + z.strictObject({ + kind: z.literal("MethodDef"), + token: methodToken, + ...coordinates, + declaring_type_token: typeToken.nullable(), + rva: uint32.describe( + "Raw MethodDef RVA, including zero; a nonzero value does not establish a file-backed body.", + ), + }), +]); + +export const unresolvedDefinitionsSchema = z.strictObject({ + rows: z + .array(unresolvedDefinitionSchema) + .describe( + "Physical TypeDef coordinates from the assembly-wide name scan, then MethodDef coordinates within the source method interval and selected declaring types. These rows carry local coordinates only and do not satisfy nominal selectors.", + ), + method_names_examined: z + .boolean() + .describe( + "Whether method names were examined within the recorded method interval and any exact declaring-type selection. False means capacity recovery retained only the type coordinates.", + ), +}); + +export type FailedDefinitionField = z.infer; +export type UnresolvedDefinition = z.infer; + +/** Keep the checked field coordinate even when its heap value is unreadable. */ +export const readDefinitionField = ( + operation: () => string, + issues: ManagedParseIssue[], + field: FailedDefinitionField["field"], + offset: number, + heapIndex: number, +): string | FailedDefinitionField => { + try { + return operation(); + } catch (cause: unknown) { + const failure = retainManagedValueFailure(cause, issues); + let reason: FailedDefinitionField["reason"]; + if (failure instanceof ManagedHeapAmbiguityFailure) + reason = "ambiguous-string-heap"; + else + switch (failure.issue.code) { + case "invalid-heap-index": + case "invalid-string": + reason = failure.issue.code; + break; + case "invalid-row": + reason = "empty-required-name"; + break; + default: + throw failure; + } + return { field, field_offset: offset, heap_index: heapIndex, reason }; + } +}; + +const tokenRow = (token: string): number => Number.parseInt(token.slice(4), 16); + +export const validateUnresolvedDefinitions = ( + report: ManagedMemberInspection, + context: z.RefinementCtx, +): void => { + const projection = report.unresolved_definitions; + if (projection === undefined) return; + const fail = (path: (string | number)[], message: string) => + context.addIssue({ + code: "custom", + path: ["unresolved_definitions", ...path], + message, + }); + if ( + projection.method_names_examined !== + (report.signature_resolution !== null) || + (projection.method_names_examined && report.method_rows === null) + ) + fail( + ["method_names_examined"], + "Method name coverage must agree with member examination and the recorded MethodDef interval.", + ); + if (projection.rows.length === 0) return; + if ( + report.coverage.state !== "partial" || + report.metadata.status !== "partial" + ) + fail( + ["rows"], + "Unresolved definitions require partial metadata and coverage.", + ); + + const typeTokens = new Set(report.types.map(({ token }) => token)); + const methodTokens = new Set(report.methods.map(({ token }) => token)); + const { byte_length: byteLength } = report.artifact; + const counts = report.metadata.table_row_counts; + let previous = ""; + for (const [index, row] of projection.rows.entries()) { + const rid = tokenRow(row.token); + if ( + rid < 1 || + rid > (counts[row.kind] ?? 0) || + row.token <= previous || + (row.kind === "TypeDef" ? typeTokens : methodTokens).has(row.token) + ) + fail( + ["rows", index, "token"], + "Expected a unique, in-table token in order, distinct from named rows.", + ); + previous = row.token; + if (row.kind === "MethodDef") { + const interval = report.method_rows; + if ( + !projection.method_names_examined || + interval === null || + rid <= interval.offset || + rid - interval.offset > interval.count + ) + fail( + ["rows", index, "token"], + "MethodDef coordinate is outside the examined interval.", + ); + const owner = row.declaring_type_token; + if ( + (owner !== null && + (tokenRow(owner) < 1 || tokenRow(owner) > (counts.TypeDef ?? 0))) || + (report.selection !== null && + (owner === null || !typeTokens.has(owner))) + ) + fail( + ["rows", index, "declaring_type_token"], + "MethodDef owner must be an admitted TypeDef within the applicable selection.", + ); + } + const fields = new Set(); + let previousFieldOffset = row.row_offset; + for (const [column, fact] of row.failed_fields.entries()) { + if ( + (row.kind === "MethodDef" && fact.field !== "Name") || + fields.has(fact.field) || + fact.field_offset <= previousFieldOffset || + fact.field_offset > byteLength - 2 || + (fact.reason === "empty-required-name" && fact.field !== "Name") || + (fact.heap_index === 0 && fact.reason !== "empty-required-name") + ) + fail( + ["rows", index, "failed_fields", column], + "Expected a distinct failed name column within the checked row and artifact.", + ); + fields.add(fact.field); + previousFieldOffset = fact.field_offset; + } + } +}; diff --git a/src/dotnet/ManagedMemberInspector.test.ts b/src/dotnet/ManagedMemberInspector.test.ts index 561bf8568e..63bfe16441 100644 --- a/src/dotnet/ManagedMemberInspector.test.ts +++ b/src/dotnet/ManagedMemberInspector.test.ts @@ -3155,6 +3155,61 @@ describe("managed member type selection", () => { }); describe("managed member method paging", () => { + it("records a checked unresolved MethodDef only inside the source interval and selected type", () => { + const bytes = buildManagedPeFixture({ methodRowCount: 3 }); + const pe = readManagedPeLayout(bytes); + if (pe.cli === null) throw new Error("Fixture omitted CLI metadata"); + const { rva, size } = pe.cli.metadata; + const layout = readManagedMetadataLayout( + bytes, + pe.rvaToOffset(rva, size, "fixture"), + size, + ); + const first = metadataRowOffset(layout, 6, 1); + const third = metadataRowOffset(layout, 6, 3); + bytes.writeUInt16LE(0xffff, first + 8); + bytes.writeUInt16LE(0, third + 8); + const target = managedPeFixtureTarget(bytes); + const report = inspectManagedMembersBytes(bytes, target, { + typeNames: ["Fixture.Program"], + methodOffset: 1, + methodLimit: 2, + }); + expect(report.method_rows).toEqual({ offset: 1, count: 2, total: 3 }); + expect(report.methods.map(({ token }) => token)).toEqual(["0x06000002"]); + expect(report.unresolved_definitions).toEqual({ + method_names_examined: true, + rows: [ + { + kind: "MethodDef", + token: "0x06000003", + row_offset: third, + declaring_type_token: "0x02000001", + rva: bytes.readUInt32LE(third), + failed_fields: [ + { + field: "Name", + field_offset: third + 8, + heap_index: 0, + reason: "empty-required-name", + }, + ], + }, + ], + }); + expect( + inspectManagedMembersBytes(bytes, target, { typeNames: ["Other.Type"] }) + .unresolved_definitions, + ).toEqual({ method_names_examined: true, rows: [] }); + const invalid = structuredClone(report); + if (invalid.unresolved_definitions?.rows[0] === undefined) + throw new Error("Missing MethodDef coordinate"); + invalid.unresolved_definitions.rows[0].token = "0x06000001"; + expect(managedMemberInspectionSchema.safeParse(invalid).success).toBe( + false, + ); + }); + it("returns only the requested MethodDef rows", () => { const image = buildMultiMethodManagedPeFixture({ methods: [ diff --git a/src/dotnet/ManagedMemberInspector.ts b/src/dotnet/ManagedMemberInspector.ts index b62fc4f9d7..bf44b2378f 100644 --- a/src/dotnet/ManagedMemberInspector.ts +++ b/src/dotnet/ManagedMemberInspector.ts @@ -309,6 +309,10 @@ export const inspectManagedMembersBytes = ( nesting_read: parsedTypes.nesting.complete, selection, method_rows: methodRows, + unresolved_definitions: { + rows: parsedTypes.unresolvedDefinitions, + method_names_examined: false, + }, limitations: [...typeIdentityLimitations, ...selectionLimitations], }, uniqueManagedParseIssues(issues), @@ -508,6 +512,12 @@ export const inspectManagedMembersBytes = ( user_strings: userStrings, selection, method_rows: methodRows, + unresolved_definitions: { + rows: parsedTypes.unresolvedDefinitions.concat( + methods.unresolvedDefinitions, + ), + method_names_examined: true, + }, coverage: { state: issues.length === 0 && !incompleteMembers diff --git a/src/dotnet/ManagedMemberRecovery.ts b/src/dotnet/ManagedMemberRecovery.ts index b3d3106bfc..1e32d1d246 100644 --- a/src/dotnet/ManagedMemberRecovery.ts +++ b/src/dotnet/ManagedMemberRecovery.ts @@ -19,6 +19,7 @@ type TypeInventory = Pick< | "nesting_read" | "selection" | "method_rows" + | "unresolved_definitions" | "limitations" >; @@ -32,12 +33,23 @@ export const prepareManagedMemberRecovery = ( issues: readonly ManagedParseIssue[], budget: ManagedDecodeBudget, ): ((offset: number | null) => ManagedMemberInspection) => { + const { unresolved_definitions, ...retained } = inventory; const capacityIssue = new ManagedRepresentationFailure( Number.MAX_SAFE_INTEGER, budget.maximumBytes, ).issue; const report: ManagedMemberInspection = { - ...inventory, + ...retained, + ...(unresolved_definitions === undefined + ? {} + : { + unresolved_definitions: { + rows: unresolved_definitions.rows.filter( + ({ kind }) => kind === "TypeDef", + ), + method_names_examined: false, + }, + }), metadata: { ...inventory.metadata, status: "partial" }, signature_resolution: null, assembly: null, @@ -61,9 +73,12 @@ export const prepareManagedMemberRecovery = ( admitManagedProjection(report, budget); // A successful full report serializes these same immutable facts once. // Transfer their existing charge, rather than charging the type list twice. - for (const value of Object.values(inventory)) { + for (const value of Object.values(retained)) { if (value !== null && typeof value === "object") budget.prepay(value); } + // The complete projection combines these same type rows with method rows. + for (const row of report.unresolved_definitions?.rows ?? []) + budget.prepay(row); return (offset) => managedMemberInspectionSchema.parse({ ...report, diff --git a/src/dotnet/ManagedMemberRows.ts b/src/dotnet/ManagedMemberRows.ts index 7c599907fe..a6f1a98618 100644 --- a/src/dotnet/ManagedMemberRows.ts +++ b/src/dotnet/ManagedMemberRows.ts @@ -54,6 +54,10 @@ import { import { methodBody } from "./ManagedMethodBodyReader.js"; import { memberDeclaringTypeRowLookup } from "../domain/managed/managedMemberOwnership.js"; import type { TypeMemberListFacts } from "../domain/managed/managedTypeMemberLists.js"; +import { + readDefinitionField, + type UnresolvedDefinition, +} from "../domain/managed/managedUnresolvedDefinitions.js"; /** * Declaring-type tokens whose members are decoded in full; null selects every @@ -350,8 +354,10 @@ export const parseMethods = ({ * scanned: rows that produced no method, or bodies whose decoding stopped. */ readonly unscannedMethods: number; + readonly unresolvedDefinitions: UnresolvedDefinition[]; } => { const methods: DecodedMethod[] = []; + const unresolvedDefinitions: UnresolvedDefinition[] = []; const core = new Map(); const issues: ManagedParseIssue[] = []; let unscannedMethods = 0; @@ -369,6 +375,7 @@ export const parseMethods = ({ : readManagedValue(() => ownerRow(row), issues); const declared = owner === undefined ? undefined : ranges[owner - 1]; const inPage = row > methodOffset && row - methodOffset <= methodLimit; + const selectedForEvidence = inPage && isSelected(selected, declared); const mayBeSelected = inPage && (selected === null || @@ -401,7 +408,30 @@ export const parseMethods = ({ signatureIndex, implementation, } = definition; - const name = readMethodDefinitionName(bytes, layout, definition); + const name = readDefinitionField( + () => readMethodDefinitionName(bytes, layout, definition), + issues, + "Name", + definition.nameOffset, + definition.nameIndex, + ); + if (typeof name !== "string") { + if (selectedForEvidence) + unresolvedDefinitions.push( + admitManagedProjection( + { + kind: "MethodDef", + token, + row_offset: rowOffset, + declaring_type_token: declared?.token ?? null, + rva, + failed_fields: [name], + }, + managedDecodeBudget(layout), + ), + ); + return; + } const member = { token, name, @@ -409,8 +439,7 @@ export const parseMethods = ({ kind: "method", } as const; core.set(token, member); - if (!inPage) return; - if (!isSelected(selected, declared)) return; + if (!selectedForEvidence) return; const sig = readMetadataBlob(bytes, layout, signatureIndex); const decoded = budgetedSignature( sig, @@ -465,7 +494,7 @@ export const parseMethods = ({ }, issues); if (mayBeSelected && methods.length === produced) unscannedMethods += 1; } - return { methods, core, issues, unscannedMethods }; + return { methods, core, issues, unscannedMethods, unresolvedDefinitions }; }; /** diff --git a/src/dotnet/ManagedMemberTypeInventory.test.ts b/src/dotnet/ManagedMemberTypeInventory.test.ts index 6853ce3834..c494bb5960 100644 --- a/src/dotnet/ManagedMemberTypeInventory.test.ts +++ b/src/dotnet/ManagedMemberTypeInventory.test.ts @@ -192,8 +192,19 @@ it("explains capacity exhaustion after a single-type selection", () => { it("retains types when a field signature exceeds the decoding bound", () => { const bytes = buildManagedPeFixture({ + additionalEmptyTypes: 1, fieldSignature: Buffer.alloc(270_001, 0x06), }); + const pe = readManagedPeLayout(bytes); + if (pe.cli === null) throw new Error("Fixture omitted CLI metadata"); + const { rva, size } = pe.cli.metadata; + const layout = readManagedMetadataLayout( + bytes, + pe.rvaToOffset(rva, size, "fixture"), + size, + ); + const rowOffset = metadataRowOffset(layout, 2, 1); + bytes.writeUInt16LE(0, rowOffset + 4); const result = inspectManagedMembersBytes( bytes, managedPeFixtureTarget(bytes), @@ -204,6 +215,24 @@ it("retains types when a field signature exceeds the decoding bound", () => { expect.objectContaining({ code: "resource-limit" }), ); expect(result.fields).toEqual([]); + expect(result.unresolved_definitions).toEqual({ + rows: [ + { + kind: "TypeDef", + token: "0x02000001", + row_offset: rowOffset, + failed_fields: [ + { + field: "Name", + field_offset: rowOffset + 4, + heap_index: 0, + reason: "empty-required-name", + }, + ], + }, + ], + method_names_examined: false, + }); }); it("keeps metadata admission failures unavailable rather than inventing an inventory", () => { diff --git a/tests/acceptance/managedUnresolvedModuleName.test.ts b/tests/acceptance/managedUnresolvedModuleName.test.ts index 6e3fb36e96..3702943353 100644 --- a/tests/acceptance/managedUnresolvedModuleName.test.ts +++ b/tests/acceptance/managedUnresolvedModuleName.test.ts @@ -3,7 +3,15 @@ import { join } from "node:path"; import { expect } from "vitest"; import { parseEvidence } from "../../src/domain/evidence.js"; +import { managedMemberSummaryViewResultSchema } from "../../src/domain/analysisView/analysisViewResult.js"; +import { MANAGED_MEMBER_SCOPE_GUIDANCE } from "../../src/domain/analysisView/managedMemberView.js"; import { managedMemberInspectionSchema } from "../../src/domain/managed/managedArtifact.js"; +import { + metadataRowOffset, + readManagedMetadataLayout, +} from "../../src/domain/managed/managedMetadataLayout.js"; +import { readManagedPeLayout } from "../../src/domain/managed/managedPeReader.js"; +import { buildManagedPeFixture } from "../../src/dotnet/ManagedPe.fixture.js"; import { managedStringsAmbiguity, STRING_AMBIGUITY_MVID, @@ -11,8 +19,22 @@ import { import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; +const buildSelectedCoordinateFixture = (): Buffer => { + const bytes = buildManagedPeFixture({ additionalEmptyTypes: 1 }); + const pe = readManagedPeLayout(bytes); + if (pe.cli === null) throw new Error("Fixture omitted CLI metadata"); + const { rva, size } = pe.cli.metadata; + const layout = readManagedMetadataLayout( + bytes, + pe.rvaToOffset(rva, size, "fixture"), + size, + ); + bytes.writeUInt16LE(0, metadataRowOffset(layout, 2, 1) + 4); + return bytes; +}; + cliTest( - "retains unnamed Module identity through CLI, MCP and a retained member page", + "retains unresolved Module and definition facts through CLI, MCP and retained pages", async ({ cli }) => { const root = await createTestTempDirectory("rea-managed-module-name-"); const path = join(root, "fixture.dll"); @@ -37,15 +59,78 @@ cliTest( }, identity_scope: { requires_mvid: STRING_AMBIGUITY_MVID }, }); + const type = { + kind: "TypeDef", + token: "0x02000001", + row_offset: 964, + failed_fields: [ + { + field: "Name", + field_offset: 968, + heap_index: bytes.readUInt16LE(968), + reason: "ambiguous-string-heap", + }, + { + field: "Namespace", + field_offset: 970, + heap_index: bytes.readUInt16LE(970), + reason: "ambiguous-string-heap", + }, + ], + }; + const method = { + kind: "MethodDef", + token: "0x06000001", + row_offset: 984, + declaring_type_token: "0x02000001", + rva: 10240, + failed_fields: [ + { + field: "Name", + field_offset: 992, + heap_index: bytes.readUInt16LE(992), + reason: "ambiguous-string-heap", + }, + ], + }; + expect(report.unresolved_definitions).toEqual({ + rows: [type, method], + method_names_examined: true, + }); const call = await cli.sharedMcpCall!(); const mcp = await call("inspect_managed_members", { path }); expect(mcp.isError, JSON.stringify(mcp)).not.toBe(true); const parent = parseEvidence(mcp.structuredContent); expect(parent.normalized_result).toEqual(report); + const source = { + kind: "retained-evidence", + evidence_id: parent.evidence_id, + }; + + for (const [offset, item] of [type, method].entries()) { + const coordinates = await call("inspect_analysis_view", { + source, + view: { + kind: "managed-members", + collection: "unresolved_definitions", + offset, + limit: 1, + }, + }); + expect(coordinates.isError, JSON.stringify(coordinates)).not.toBe(true); + expect( + parseEvidence(coordinates.structuredContent).normalized_result, + ).toMatchObject({ + parent_evidence_id: parent.evidence_id, + source_metadata_status: "partial", + unresolved_method_names_examined: true, + page: { collection: "unresolved_definitions", rows: [item] }, + }); + } const page = await call("inspect_analysis_view", { - source: { kind: "retained-evidence", evidence_id: parent.evidence_id }, + source, view: { kind: "managed-members", collection: "methods", limit: 1 }, }); expect(page.isError, JSON.stringify(page)).not.toBe(true); @@ -56,5 +141,50 @@ cliTest( unresolved_module_name: report.metadata.unresolved_module_name, identity_scope: report.identity_scope, }); + + const selectedPath = join(root, "selected.dll"); + await writeFile(selectedPath, buildSelectedCoordinateFixture()); + const selected = await call("inspect_managed_members", { + path: selectedPath, + type_names: ["Fixture.Program"], + detail: "summary", + }); + expect(selected.isError, JSON.stringify(selected)).not.toBe(true); + const scope = [ + MANAGED_MEMBER_SCOPE_GUIDANCE.selectedNominalRows, + MANAGED_MEMBER_SCOPE_GUIDANCE.unresolvedTypeRows, + MANAGED_MEMBER_SCOPE_GUIDANCE.unresolvedMethodRows, + ]; + const result = managedMemberSummaryViewResultSchema.parse( + parseEvidence(selected.structuredContent).normalized_result, + ); + expect(result).toMatchObject({ + summary: { + selection: { + type_names: ["Fixture.Program"], + unmatched_type_names: [], + }, + reported_counts: { types: 1, unresolved_definitions: 1 }, + }, + unknowns: expect.arrayContaining(scope), + }); + const selectedPage = await call("inspect_analysis_view", { + source: { + kind: "retained-evidence", + evidence_id: result.parent_evidence_id, + }, + view: { + kind: "managed-members", + collection: "unresolved_definitions", + limit: 1, + }, + }); + expect(selectedPage.isError, JSON.stringify(selectedPage)).not.toBe(true); + expect( + parseEvidence(selectedPage.structuredContent).normalized_result, + ).toMatchObject({ + page: { rows: [{ kind: "TypeDef", token: "0x02000001" }] }, + unknowns: result.unknowns, + }); }, ); diff --git a/tests/boundary/mcp/managedMemberSummaryMcp.test.ts b/tests/boundary/mcp/managedMemberSummaryMcp.test.ts index 36d128c831..64b7aa83a0 100644 --- a/tests/boundary/mcp/managedMemberSummaryMcp.test.ts +++ b/tests/boundary/mcp/managedMemberSummaryMcp.test.ts @@ -327,8 +327,10 @@ it("keeps collections that member Evidence never examined unknown", async () => }) ).structuredContent, ); + const { unresolved_definitions: _projection, ...historical } = + managedMemberInspectionSchema.parse(parent.normalized_result); const recorded = { - ...managedMemberInspectionSchema.parse(parent.normalized_result), + ...historical, exported_types: null, user_strings: null, selection: null, @@ -361,10 +363,17 @@ it("keeps collections that member Evidence never examined unknown", async () => expect(view.summary.reported_counts.exported_types).toBeNull(); expect(view.summary.signature_resolution).toBeNull(); expect(view.summary.reported_counts.user_strings).toBeNull(); + expect(view.summary.reported_counts).not.toHaveProperty( + "unresolved_definitions", + ); expect(view.summary.user_strings).toBeNull(); expect(view.summary.selection).toBeNull(); expect(view.unknowns.join(" ")).toContain("no recorded subject"); - for (const collection of ["exported_types", "user_strings"] as const) + for (const collection of [ + "exported_types", + "user_strings", + "unresolved_definitions", + ] as const) expect( await inspectAnalysisView({ source: { kind: "inline", evidence: unexamined }, diff --git a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts index 54a0a48e5b..87a58e3e25 100644 --- a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts +++ b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts @@ -537,10 +537,11 @@ describe("managed comparison method row coverage", () => { }), }; expect(compareManagedMembers(full, selected).summary.removed).toBe(0); + const { unresolved_definitions: _projection, ...historical } = full.result; const unscoped = { ...full, result: managedMemberInspectionSchema.parse({ - ...full.result, + ...historical, method_rows: null, }), }; diff --git a/tests/composition/analysis-sessions/managedApplicationGraph.test.ts b/tests/composition/analysis-sessions/managedApplicationGraph.test.ts index 5208cf3238..db0af8800f 100644 --- a/tests/composition/analysis-sessions/managedApplicationGraph.test.ts +++ b/tests/composition/analysis-sessions/managedApplicationGraph.test.ts @@ -141,16 +141,17 @@ describe("managed application graph MethodDef scope", () => { } }); - it("keeps an unexamined MethodDef scope unknown", () => { + it("keeps an unrecorded MethodDef scope unknown in historical member Evidence", () => { const bytes = buildManagedPeFixture({ ilBody: tinyIl([0x2a]) }); const binary = managedPeFixtureTarget(bytes); - const members = inspectManagedMembersBytes(bytes, binary); + const { unresolved_definitions: _projection, ...historical } = + inspectManagedMembersBytes(bytes, binary); const evidence = createEvidence(binary, MANAGED_STATIC_PROVIDER, { operation: "inspect_managed_members", parameters: {}, - result: { ...members, method_rows: null }, + result: { ...historical, method_rows: null }, rawResult: null, - limitations: members.limitations, + limitations: historical.limitations, }); const projection = projectManagedApplicationGraphEvidence({ managed_members: evidence,