feat(managed)!: state member comparison item limitations as tagged reason objects (#11177)

* feat(managed): give each member comparison limitation a structured reason

* feat(managed)!: state member comparison item limitations as tagged objects

Each method and field comparison item limitation is now {code, side?, message}
instead of a prefixed sentence beside a parallel limitation_reasons list.

BREAKING CHANGE: compare_managed_members item limitations are objects, not
strings, and limitation_reasons is removed. Read limitations[].code (and side)
instead of matching message prefixes such as "signature-not-resolved:".
Comparison Evidence written by earlier builds is refused; recreate it.

* test(managed): assert limitation codes instead of banning a message prefix
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 05:53:44 +08:00
1 parent f270a5cac1
commit 21adb649ac
7 files changed
+227 -71

No files matched your search

@@ -677,6 +677,11 @@ signature has the other member kind is malformed and cannot establish an
unchanged signature. Comparison retains exact byte-based pairs for malformed
signatures, including empty, truncated, or invalid headers, but reports them as
unknown with a `signature-malformed` limitation when no change is observed.
Each method and field comparison item states its limitations as
`{code, side?, message}` objects: `code` names the reason, `side` names the
other inventory when the reason concerns it (for example
`unknown-within-incomplete-metadata` with `side: "right"`), and `message`
explains it. Read the code rather than the message text.
Runtime-provided methods have the Runtime code type or the InternalCall
implementation flag, as core library FCalls do. They are counted separately in
`native_implementations.runtime_provided`; they have no file-backed native body
+34 -1
View File
@@ -132,9 +132,42 @@ const comparisonItemSchema = <
}),
]);
/** Stable codes for why one comparison item's facts stayed limited. */
export const MANAGED_MEMBER_COMPARISON_LIMITATION_CODES = [
"declaring-type-name-not-resolved",
"counterpart-declaring-type-name-not-resolved",
"unknown-within-incomplete-metadata",
"signature-not-decoded",
"counterpart-signature-not-decoded",
"signature-not-resolved",
"counterpart-signature-not-resolved",
"signature-malformed",
"ambiguous-signature",
"ambiguous-il-signature",
"ambiguous-method-shape",
"local-signature-unknown",
"local-signature-bytes-changed",
"body-unavailable",
"call-target-unavailable",
"field-target-unavailable",
"catch-type-unavailable",
] as const;
/** One reason a comparison item's facts stayed limited, with its explanation. */
const comparisonItemLimitationSchema = z.strictObject({
code: z.enum(MANAGED_MEMBER_COMPARISON_LIMITATION_CODES),
side: z
.enum(["left", "right"])
.optional()
.describe(
"The inventory this limitation concerns when it is the other side's, such as an incomplete or ambiguous counterpart inventory.",
),
message: nonEmptyTextSchema,
});
const comparisonItemContextShape = {
evidence_links: z.array(evidenceIdSchema).length(2),
limitations: z.array(nonEmptyTextSchema),
limitations: z.array(comparisonItemLimitationSchema),
};
const methodComparisonItemSchema = comparisonItemSchema(
@@ -28,6 +28,15 @@ type UnmatchedComparison = Extract<
{ readonly status: "unmatched" }
>;
type Limitation = MethodItem["limitations"][number];
const limitation = (
code: Limitation["code"],
message: string,
side?: "left" | "right",
): Limitation =>
side === undefined ? { code, message } : { code, side, message };
type OneSided<Item> =
| { readonly left: Item; readonly right?: never }
| { readonly left?: never; readonly right: Item };
@@ -533,43 +542,68 @@ const absenceLimitations = (
readonly opposite: "left" | "right";
readonly inventory: "method" | "field";
},
): string[] => [
): Limitation[] => [
...(opposite.ownIdentityUnavailable
? [
"declaring-type-name-not-resolved: Declared type identity could not be resolved; a bare display name cannot establish a counterpart or absence.",
limitation(
"declaring-type-name-not-resolved",
"Declared type identity could not be resolved; a bare display name cannot establish a counterpart or absence.",
),
]
: []),
...(opposite.unpaired.unknownOwners[opposite.opposite].has(member.name)
? [
`counterpart-declaring-type-name-not-resolved: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired same-named member with unresolved enclosing-name identity, so absence was not established.`,
limitation(
"counterpart-declaring-type-name-not-resolved",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired same-named member with unresolved enclosing-name identity, so absence was not established.`,
opposite.opposite,
),
]
: []),
...(opposite.oppositeComplete
? []
: [
`unknown-within-incomplete-metadata: The ${opposite.opposite} ${opposite.inventory} inventory is incomplete, so absence was not observed.`,
limitation(
"unknown-within-incomplete-metadata",
`The ${opposite.opposite} ${opposite.inventory} inventory is incomplete, so absence was not observed.`,
opposite.opposite,
),
]),
...(member.signature.parse_status === "decoded"
? []
: [
`signature-not-decoded: The member's ${member.signature.parse_status} signature was compared only by exact declared type, name, and signature bytes, so a changed or renamed counterpart could not be sought.`,
limitation(
"signature-not-decoded",
`The member's ${member.signature.parse_status} signature was compared only by exact declared type, name, and signature bytes, so a changed or renamed counterpart could not be sought.`,
),
]),
...(member.signature.parse_status === "decoded" &&
opposite.unpaired.undecoded[opposite.opposite].has(identity)
? [
`counterpart-signature-not-decoded: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature was not decoded, so it may be this member with a changed signature.`,
limitation(
"counterpart-signature-not-decoded",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature was not decoded, so it may be this member with a changed signature.`,
opposite.opposite,
),
]
: []),
...(unresolved(member)
? [
`signature-not-resolved: The member's signature names a type REA could not name, so it was compared by raw bytes, which name types by build-local metadata row; a counterpart whose referenced type moved rows could not be found.`,
limitation(
"signature-not-resolved",
`The member's signature names a type REA could not name, so it was compared by raw bytes, which name types by build-local metadata row; a counterpart whose referenced type moved rows could not be found.`,
),
]
: []),
...(member.signature.parse_status === "decoded" &&
!unresolved(member) &&
opposite.unpaired.unresolved[opposite.opposite].has(identity)
? [
`counterpart-signature-not-resolved: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature names a type REA could not name, so it may be this member.`,
limitation(
"counterpart-signature-not-resolved",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature names a type REA could not name, so it may be this member.`,
opposite.opposite,
),
]
: []),
];
@@ -583,17 +617,23 @@ const unresolved = (member: Method | Field): boolean =>
const pairedSignatureLimitations = (
left: Method | Field,
right: Method | Field,
): string[] => {
): Limitation[] => {
if (
left.signature.parse_status === "malformed" ||
right.signature.parse_status === "malformed"
)
return [
"signature-malformed: At least one signature is malformed; equal signature bytes do not establish an unchanged member signature.",
limitation(
"signature-malformed",
"At least one signature is malformed; equal signature bytes do not establish an unchanged member signature.",
),
];
return unresolved(left) || unresolved(right)
? [
"signature-not-resolved: At least one signature names a type REA could not resolve; equal build-local row bytes do not establish equivalent signature types.",
limitation(
"signature-not-resolved",
"At least one signature names a type REA could not resolve; equal build-local row bytes do not establish equivalent signature types.",
),
]
: [];
};
@@ -717,16 +757,31 @@ const ambiguityLimitation = (
members: "methods" | "fields",
basis: MethodItem["match"]["basis"],
identityUnavailable: boolean,
): string =>
): Limitation =>
identityUnavailable
? "declaring-type-name-not-resolved: Declared type identity remains unresolved; REA did not guess a counterpart from display names, signatures or CIL."
? limitation(
"declaring-type-name-not-resolved",
"Declared type identity remains unresolved; REA did not guess a counterpart from display names, signatures or CIL.",
)
: basis === "exact-signature"
? `Multiple managed ${members} share the same signature; REA did not guess declared ownership or a token remap.`
? limitation(
"ambiguous-signature",
`Multiple managed ${members} share the same signature; REA did not guess declared ownership or a token remap.`,
)
: basis === "exact-il-signature"
? "Multiple managed methods share the same CIL and signature; REA did not guess a token remap."
? limitation(
"ambiguous-il-signature",
"Multiple managed methods share the same CIL and signature; REA did not guess a token remap.",
)
: members === "methods"
? "Multiple managed methods share the same structural shape; REA did not guess a token remap."
: "Multiple managed fields share the same signature; REA did not guess a token remap.";
? limitation(
"ambiguous-method-shape",
"Multiple managed methods share the same structural shape; REA did not guess a token remap.",
)
: limitation(
"ambiguous-signature",
"Multiple managed fields share the same signature; REA did not guess a token remap.",
);
/** Local signature bytes prove identity only without metadata or declaring-context dependencies. */
const compareLocalSignatures = (
@@ -831,32 +886,50 @@ export const buildMethodItems = (
...signatureLimitations,
...(locals.unknown
? [
"Local variable signature identity is unknown because validated context-free signature facts are unavailable or the signature requires metadata or declaring context; build-local tokens and raw bytes do not establish equivalent local types across artifacts.",
limitation(
"local-signature-unknown",
"Local variable signature identity is unknown because validated context-free signature facts are unavailable or the signature requires metadata or declaring context; build-local tokens and raw bytes do not establish equivalent local types across artifacts.",
),
]
: []),
...(locals.changed
? [
"The validated context-free LocalVarSig bytes changed; this records an encoding difference without asserting a semantic type change.",
limitation(
"local-signature-bytes-changed",
"The validated context-free LocalVarSig bytes changed; this records an encoding difference without asserting a semantic type change.",
),
]
: []),
...(bodyUnknown
? [
"Method body facets are unknown because at least one side has unavailable or partial body data.",
limitation(
"body-unavailable",
"Method body facets are unknown because at least one side has unavailable or partial body data.",
),
]
: []),
...(callTargetUnknown
? [
"One or more call targets are unavailable because the observed method edges do not cover aligned call instructions or lack a resolved nominal target identity or instruction site.",
limitation(
"call-target-unavailable",
"One or more call targets are unavailable because the observed method edges do not cover aligned call instructions or lack a resolved nominal target identity or instruction site.",
),
]
: []),
...(fieldTargetUnknown
? [
"One or more field targets are unavailable because observed field accesses do not cover aligned field instructions or lack a resolved nominal target identity or instruction site.",
limitation(
"field-target-unavailable",
"One or more field targets are unavailable because observed field accesses do not cover aligned field instructions or lack a resolved nominal target identity or instruction site.",
),
]
: []),
...(exceptionTargetUnknown
? [
"One or more catch type identities are unavailable because local tokens or TypeRef resolution scopes do not establish cross-build identity.",
limitation(
"catch-type-unavailable",
"One or more catch type identities are unavailable because local tokens or TypeRef resolution scopes do not establish cross-build identity.",
),
]
: []),
],
@@ -264,7 +264,7 @@ cliTest(
confidence: "exact",
}),
limitations: malformed
? [expect.stringMatching(/^signature-malformed:/)]
? [expect.objectContaining({ code: "signature-malformed" })]
: [],
}),
]);
@@ -449,8 +449,8 @@ describe("managed nested type names", () => {
const warned = comparison.methods.map(({ left, right, limitations }) => [
left?.token ?? null,
right?.token ?? null,
limitations.some((limitation) =>
limitation.startsWith("counterpart-signature-not-decoded"),
limitations.some(
({ code }) => code === "counterpart-signature-not-decoded",
),
]);
@@ -600,7 +600,9 @@ describe("managed call-target comparison", () => {
expect(report.methods[0]).toMatchObject({
status: "changed",
dimensions: expect.arrayContaining(["call-target", "availability"]),
limitations: [expect.stringContaining("call targets are unavailable")],
limitations: [
expect.objectContaining({ code: "call-target-unavailable" }),
],
});
const unavailableEdges = observe(
@@ -1104,7 +1104,9 @@ describe("managed LocalVarSig comparison", () => {
status: "changed",
dimensions: ["metadata"],
match: { basis: "exact-il-signature" },
limitations: [expect.stringContaining("encoding difference")],
limitations: [
expect.objectContaining({ code: "local-signature-bytes-changed" }),
],
});
});
@@ -1127,9 +1129,7 @@ describe("managed LocalVarSig comparison", () => {
status: "changed",
dimensions: ["metadata", "availability"],
limitations: [
expect.stringContaining(
"Local variable signature identity is unknown",
),
expect.objectContaining({ code: "local-signature-unknown" }),
],
});
const sameHeader = observe(
@@ -1289,6 +1289,10 @@ describe("managed member comparison", () => {
status: "changed",
match: { status: "matched", basis: "exact-signature" },
dimensions: ["cil", "availability"],
limitations: [
expect.objectContaining({ code: "call-target-unavailable" }),
expect.objectContaining({ code: "field-target-unavailable" }),
],
});
});
@@ -1327,6 +1331,40 @@ describe("managed member comparison", () => {
});
});
describe("managed member comparison limitation reasons", () => {
it("states each limitation as a code with its explanation and refuses bare text", () => {
const left = inspect(buildManagedPeFixture(), "/tmp/left.dll");
const right = inspect(
buildManagedPeFixture({
ilBody: Buffer.from([
0x32, 0x02, 0x7b, 0x02, 0x00, 0x00, 0x04, 0x28, 0x02, 0x00, 0x00,
0x0a, 0x2a,
]),
}),
"/tmp/right.dll",
);
const result = compareManagedMembers(
{ evidenceId: left.evidenceId, result: left.result },
{ evidenceId: right.evidenceId, result: right.result },
);
expect(managedMemberComparisonResultSchema.parse(result)).toEqual(result);
expect(result.methods[0]?.limitations).toEqual([
{ code: "call-target-unavailable", message: expect.any(String) },
{ code: "field-target-unavailable", message: expect.any(String) },
]);
// A limitation recorded as bare text has no reason and is refused.
expect(
managedMemberComparisonResultSchema.safeParse({
...result,
methods: result.methods.map((item) => ({
...item,
limitations: item.limitations.map(({ message }) => message),
})),
}).success,
).toBe(false);
});
});
describe("managed member comparison with equal decoded fingerprints", () => {
it.each([
{ name: "Main", basis: "exact-signature" },
@@ -1519,7 +1557,10 @@ describe("managed member comparison uncertainty", () => {
left: { token: "0x06000001" },
right: null,
limitations: [
expect.stringContaining("unknown-within-incomplete-metadata"),
expect.objectContaining({
code: "unknown-within-incomplete-metadata",
side: "right",
}),
],
});
expect(result.fields[0]).toMatchObject({
@@ -1527,7 +1568,10 @@ describe("managed member comparison uncertainty", () => {
left: null,
right: { token: "0x04000001" },
limitations: [
expect.stringContaining("unknown-within-incomplete-metadata"),
expect.objectContaining({
code: "unknown-within-incomplete-metadata",
side: "left",
}),
],
});
expect(result.coverage).toEqual({
@@ -1585,9 +1629,7 @@ describe("managed member comparison uncertainty", () => {
candidate_left_tokens: ["0x04000001", "0x04000002"],
candidate_right_tokens: ["0x04000001", "0x04000002"],
}),
limitations: [
"Multiple managed fields share the same signature; REA did not guess a token remap.",
],
limitations: [expect.objectContaining({ code: "ambiguous-signature" })],
}),
]);
});
@@ -1650,7 +1692,7 @@ it.each([
expect(item).toMatchObject({
status: "unknown",
match: { status: "matched", confidence: "exact" },
limitations: [expect.stringMatching(/^signature-malformed:/)],
limitations: [expect.objectContaining({ code: "signature-malformed" })],
});
},
);
@@ -1767,7 +1809,9 @@ describe("managed member comparison of undecoded signatures", () => {
expect(item).toMatchObject({
status: "unknown",
match: { status: "unmatched" },
limitations: [expect.stringContaining("signature-not-decoded")],
limitations: [
expect.objectContaining({ code: "signature-not-decoded" }),
],
});
});
@@ -1791,10 +1835,10 @@ describe("managed member comparison of undecoded signatures", () => {
status: "unknown",
match: { status: "unmatched" },
limitations: [
expect.stringMatching(
expect.objectContaining(
item.left === null
? /^signature-not-decoded:/
: /^counterpart-signature-not-decoded: The right (method|field) inventory/,
? { code: "signature-not-decoded" }
: { code: "counterpart-signature-not-decoded", side: "right" },
),
],
});
@@ -1843,16 +1887,17 @@ describe("managed member comparison of ambiguous undecoded signatures", () => {
basis: "exact-il-signature",
}),
limitations: [
"Multiple managed methods share the same CIL and signature; REA did not guess a token remap.",
expect.objectContaining({ code: "ambiguous-il-signature" }),
],
}),
expect.objectContaining({
status: "unknown",
left: expect.objectContaining({ token: "0x06000002" }),
limitations: [
expect.stringMatching(
/^counterpart-signature-not-decoded: The right method inventory has an unpaired member/u,
),
expect.objectContaining({
code: "counterpart-signature-not-decoded",
side: "right",
}),
],
}),
]),
@@ -2155,7 +2200,7 @@ describe("managed member comparison remaps around kept identities", () => {
basis: "structural-method-shape",
}),
limitations: [
"Multiple managed methods share the same structural shape; REA did not guess a token remap.",
expect.objectContaining({ code: "ambiguous-method-shape" }),
],
}),
]);
@@ -2562,7 +2607,7 @@ it("keeps a lone ownerless member unknown despite an identical payload", () => {
candidate_right_tokens: [ownerless.token],
},
limitations: [
expect.stringContaining("Declared type identity remains unresolved"),
expect.objectContaining({ code: "declaring-type-name-not-resolved" }),
],
});
expect(result.summary).toMatchObject({
@@ -3176,16 +3221,18 @@ describe("managed member comparison of unresolved signatures", () => {
methodSignature: Buffer.from([0x00, 0x00, 0x12, leftTypes.program]),
};
const methodLimitations = (result: ReturnType<typeof compareBuilds>) =>
result.methods.map(({ status, limitations }) => [status, limitations]);
result.methods.map(({ status, limitations }) => [
status,
limitations.map(({ code, side }) => ({ code, side })),
]);
const notResolved = [{ code: "signature-not-resolved" }];
it("does not establish unchanged signatures from identical unresolved row bytes", () => {
const result = compareBuilds(unresolvedAt(1), {
...unresolvedAt(1),
typeSpecSignatures: [...typeSpecs].reverse(),
});
expect(methodLimitations(result)).toEqual([
["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]],
]);
expect(methodLimitations(result)).toEqual([["unknown", notResolved]]);
});
it("retains a known CIL change beside an unresolved signature", () => {
@@ -3193,9 +3240,7 @@ describe("managed member comparison of unresolved signatures", () => {
...unresolvedAt(1),
ilBody: Buffer.from([0x0a, 0x17, 0x2a]),
});
expect(methodLimitations(result)).toEqual([
["changed", [expect.stringMatching(/^signature-not-resolved:/u)]],
]);
expect(methodLimitations(result)).toEqual([["changed", notResolved]]);
expect(result.methods[0]?.dimensions).toContain("cil");
});
@@ -3208,7 +3253,9 @@ describe("managed member comparison of unresolved signatures", () => {
expect(result.fields).toEqual([
expect.objectContaining({
status: "unknown",
limitations: [expect.stringMatching(/^signature-not-resolved:/u)],
limitations: [
expect.objectContaining({ code: "signature-not-resolved" }),
],
}),
]);
});
@@ -3230,8 +3277,8 @@ describe("managed member comparison of unresolved signatures", () => {
compareBuilds(unresolvedAt(2), unresolvedAt(1)),
])
expect(methodLimitations(result)).toEqual([
["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]],
["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]],
["unknown", notResolved],
["unknown", notResolved],
]);
});
@@ -3248,25 +3295,19 @@ describe("managed member comparison of unresolved signatures", () => {
(leftItem === null) === (unresolvedSide === "left")
? "resolved"
: "unresolved",
limitations,
limitations.map(({ code, side }) => ({ code, side })),
]),
).toEqual(
expect.arrayContaining([
[
"unknown",
"unresolved",
[expect.stringMatching(/^signature-not-resolved:/u)],
],
["unknown", "unresolved", notResolved],
[
"unknown",
"resolved",
[
expect.stringMatching(
new RegExp(
`^counterpart-signature-not-resolved: The ${unresolvedSide} method inventory`,
"u",
),
),
{
code: "counterpart-signature-not-resolved",
side: unresolvedSide,
},
],
],
]),
@@ -55,7 +55,9 @@ describe("managed member partial body comparison", () => {
expect(compareManagedMembers(left, right).methods[0]).toMatchObject({
status: "changed",
dimensions: ["metadata", "body-coverage"],
limitations: expect.arrayContaining([expect.stringContaining("unknown")]),
limitations: expect.arrayContaining([
expect.objectContaining({ code: "body-unavailable" }),
]),
});
});