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 <cursoragent@cursor.com>
This commit is contained in:
morlutoandCursor Agent authored and GitHub committed 2026-11-19 19:03:27 +00:00
1 parent 18c8b957f8
commit 7df462cbfa
21 files changed
+656 -39

No files matched your search

@@ -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,
@@ -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,
@@ -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,
@@ -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,
@@ -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,
+64 -10
View File
@@ -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<C extends MemberCollection, T extends Row, K extends keyof T> = {
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 = <C extends MemberCollection, T extends Row>(
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<string>(view.fields);
"fields" in view && view.fields !== undefined
? new Set<string>(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<T> & Pick<T, K> & { 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
? {}
@@ -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<
+10
View File
@@ -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.
@@ -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 = (
+15 -7
View File
@@ -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 = <Value>(
operation: () => Value,
@@ -68,13 +82,7 @@ export const readManagedValue = <Value>(
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;
}
};
@@ -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,
@@ -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<typeof failedDefinitionFieldSchema>;
export type UnresolvedDefinition = z.infer<typeof unresolvedDefinitionSchema>;
/** 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<string>();
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;
}
}
};
+55
View File
@@ -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: [
+10
View File
@@ -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
+17 -2
View File
@@ -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,
+33 -4
View File
@@ -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<string, MemberCore>();
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 };
};
/**
@@ -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", () => {
@@ -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,
});
},
);
@@ -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 },
@@ -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,
}),
};
@@ -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,