Files
reverse-engineering-anything/src/domain/managed/managedMemberComparison.ts
T
morluto 21adb649ac 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
2026-11-16 05:53:44 +08:00

381 lines
12 KiB
TypeScript

import { z } from "zod";
import { digestCanonicalValue } from "../canonicalDigest.js";
import { emptyArraySchema } from "../emptyArraySchema.js";
import { evidenceInputSchema } from "../evidenceReference.js";
import {
managedInspectionStateSchema,
cliMetadataGuidSchema,
managedMetadataStatusSchema,
managedMetadataTokenSchema,
managedMemberInspectionSchema,
type ManagedMemberInspection,
} from "./managedArtifact.js";
import {
buildComparisonCoverage,
hasCompleteMethodRows,
managedComparisonScope,
buildComparisonMatching,
buildComparisonSummary,
comparisonLimitations,
sideManifest,
} from "./managedMemberComparisonCoverage.js";
import {
buildFieldItems,
buildMethodItems,
} from "./managedMemberComparisonItems.js";
import { keyMembers } from "./managedMemberComparisonMatch.js";
import { digestSchema, prefixedDigestSchema } from "../digests.js";
import { nonEmptyTextSchema } from "../textSchemas.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const memberComparisonShape = <Source extends z.ZodType>(source: Source) => ({
left: source,
right: source,
});
const distinctMemberSources = (
input: {
readonly left: { readonly evidence_id: string };
readonly right: { readonly evidence_id: string };
},
context: z.RefinementCtx,
): void => {
if (
typeof input.left?.evidence_id === "string" &&
input.left.evidence_id === input.right?.evidence_id
)
context.addIssue({
code: "custom",
path: ["right"],
message: "Managed member Evidence must be distinct",
});
};
/** Public member comparison selects records inline or by exact retained identity. */
export const compareManagedMembersRequestSchema = z
.strictObject(memberComparisonShape(evidenceInputSchema))
.superRefine(distinctMemberSources);
const concreteMatchBasisSchema = z.enum([
"exact-il-signature",
"exact-signature",
"structural-method-shape",
"field-signature",
]);
const candidateTokensSchema = z.array(managedMetadataTokenSchema).min(1);
const matchedComparisonSchema = z.strictObject({
status: z.literal("matched"),
basis: concreteMatchBasisSchema,
confidence: z.enum(["exact", "high"]),
candidate_left_tokens: emptyArraySchema,
candidate_right_tokens: emptyArraySchema,
});
const unmatchedComparisonSchema = z.strictObject({
status: z.literal("unmatched"),
basis: z.literal("none"),
confidence: z.literal("unknown"),
candidate_left_tokens: emptyArraySchema,
candidate_right_tokens: emptyArraySchema,
});
const ambiguousComparisonSchema = z.strictObject({
status: z.literal("ambiguous"),
basis: concreteMatchBasisSchema,
confidence: z.literal("unknown"),
candidate_left_tokens: candidateTokensSchema,
candidate_right_tokens: candidateTokensSchema,
});
const memberIdentitySchema = z.strictObject({
token: managedMetadataTokenSchema,
declaring_type: z.string().nullable(),
name: z.string(),
signature_sha256: digestSchema,
normalized_il_sha256: digestSchema.nullable(),
});
const comparisonItemSchema = <
Identity extends z.ZodType,
Base extends Record<string, z.ZodType>,
>(
base: Base,
identity: Identity,
) =>
z.union([
z.strictObject({
...base,
status: z.enum(["unchanged", "changed", "unknown"]),
left: identity,
right: identity,
match: matchedComparisonSchema,
}),
z.strictObject({
...base,
status: z.enum(["removed", "unknown"]),
left: identity,
right: z.null(),
match: unmatchedComparisonSchema,
}),
z.strictObject({
...base,
status: z.enum(["added", "unknown"]),
left: z.null(),
right: identity,
match: unmatchedComparisonSchema,
}),
z.strictObject({
...base,
status: z.literal("unknown"),
left: z.null(),
right: z.null(),
match: ambiguousComparisonSchema,
}),
]);
/** 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(comparisonItemLimitationSchema),
};
const methodComparisonItemSchema = comparisonItemSchema(
{
...comparisonItemContextShape,
item_id: prefixedDigestSchema("mmc_method"),
dimensions: z.array(
z.enum([
"metadata",
"signature",
"cil",
"opcode-shape",
"call-shape",
"call-target",
"field-shape",
"field-target",
"exception-shape",
"exception-target",
"availability",
"body-coverage",
]),
),
},
memberIdentitySchema,
);
const fieldComparisonItemSchema = comparisonItemSchema(
{
...comparisonItemContextShape,
item_id: prefixedDigestSchema("mmc_field"),
},
memberIdentitySchema.omit({ normalized_il_sha256: true }),
);
const comparisonSideSchema = z.strictObject({
evidence_id: evidenceIdSchema,
artifact_sha256: digestSchema,
mvid: cliMetadataGuidSchema.nullable(),
module_name: z.string().nullable(),
metadata_status: managedMetadataStatusSchema,
methods_total: z.int().min(0),
fields_total: z.int().min(0),
resource_limits: z
.array(
managedMemberInspectionSchema.shape.coverage.shape.issues.element.extend({
code: z.literal("resource-limit"),
}),
)
.describe(
"Resource-limit diagnostics reported by this source; an empty array means none were reported.",
),
});
/** Obfuscation-resistant, execution-free managed member comparison. */
export const managedMemberComparisonResultSchema = z.strictObject({
comparison_id: prefixedDigestSchema("mmc"),
algorithm: z.strictObject({
name: z.literal("rea-managed-member-comparison"),
token_identity: z.literal("build-local"),
name_matching: z.literal("exact-signature-fallback"),
}),
left: comparisonSideSchema,
right: comparisonSideSchema,
summary: z.strictObject({
unchanged: z.int().min(0),
changed: z.int().min(0),
added: z.int().min(0),
removed: z.int().min(0),
unknown: z.int().min(0),
}),
matching: z.strictObject({
exact_il_signature: z.int().min(0),
exact_signature: z.int().min(0),
structural_method_shape: z.int().min(0),
field_signature: z.int().min(0),
ambiguous: z.int().min(0),
unmatched: z.int().min(0),
}),
methods: z.array(methodComparisonItemSchema),
fields: z.array(fieldComparisonItemSchema),
coverage: z.strictObject({
status: z
.enum(["complete-within-inputs", "partial", "unknown"])
.describe(
"complete-within-inputs only when both observations are complete over the same selected scope and method rows; unknown when a side is unavailable or the selected scope agreement cannot be established.",
),
left_status: managedInspectionStateSchema,
right_status: managedInspectionStateSchema,
}),
evidence_links: z.array(evidenceIdSchema).length(2),
limitations: z.array(nonEmptyTextSchema),
});
export type ManagedMemberComparisonResult = z.infer<
typeof managedMemberComparisonResultSchema
>;
/** One authenticated side of a managed member comparison. */
export interface ManagedMemberComparisonSide {
readonly evidenceId: string;
readonly result: ManagedMemberInspection;
}
const callEdgesByCaller = (
result: ManagedMemberInspection,
): ReadonlyMap<
string,
readonly ManagedMemberInspection["call_edges"][number][]
> => {
const edges = new Map<
string,
ManagedMemberInspection["call_edges"][number][]
>();
for (const edge of result.call_edges) {
const callerEdges = edges.get(edge.caller_token);
if (callerEdges === undefined) edges.set(edge.caller_token, [edge]);
else callerEdges.push(edge);
}
return edges;
};
const fieldAccessesByCaller = (
result: ManagedMemberInspection,
): ReadonlyMap<
string,
readonly ManagedMemberInspection["field_accesses"][number][]
> => {
const accesses = new Map<
string,
ManagedMemberInspection["field_accesses"][number][]
>();
for (const access of result.field_accesses) {
const callerAccesses = accesses.get(access.method_token);
if (callerAccesses === undefined)
accesses.set(access.method_token, [access]);
else callerAccesses.push(access);
}
return accesses;
};
/** Compare managed members with constrained exact and structural identities. */
export const compareManagedMembers = (
left: ManagedMemberComparisonSide,
right: ManagedMemberComparisonSide,
): ManagedMemberComparisonResult => {
const scope = managedComparisonScope(left.result, right.result);
const { methodMatches, fieldMatches } = keyMembers(left, right, scope);
const itemContext = {
leftEvidenceId: left.evidenceId,
rightEvidenceId: right.evidenceId,
leftComplete: left.result.metadata.status === "complete",
rightComplete: right.result.metadata.status === "complete",
leftMethodsComplete:
left.result.metadata.status === "complete" &&
hasCompleteMethodRows(left.result),
rightMethodsComplete:
right.result.metadata.status === "complete" &&
hasCompleteMethodRows(right.result),
scope,
sameArtifact: left.result.artifact.sha256 === right.result.artifact.sha256,
leftAssembly: left.result.assembly,
rightAssembly: right.result.assembly,
leftCallEdgesByCaller: callEdgesByCaller(left.result),
rightCallEdgesByCaller: callEdgesByCaller(right.result),
leftFieldAccessesByCaller: fieldAccessesByCaller(left.result),
rightFieldAccessesByCaller: fieldAccessesByCaller(right.result),
};
const methodItems = buildMethodItems(methodMatches, itemContext);
const fieldItems = buildFieldItems(fieldMatches, itemContext);
const allItems = [...methodItems, ...fieldItems];
const summary = buildComparisonSummary(allItems);
const matching = buildComparisonMatching(methodItems, fieldItems);
const selectionAgreement = scope.agreement;
const coverage = buildComparisonCoverage({
left: left.result,
right: right.result,
selectionAgreement,
});
const limitations = comparisonLimitations(
left.result,
right.result,
selectionAgreement,
);
const result = {
comparison_id: `mmc_${digestCanonicalValue(
{
left: left.evidenceId,
right: right.evidenceId,
methods: [...methodItems],
fields: [...fieldItems],
},
"Managed comparison",
)}`,
algorithm: {
name: "rea-managed-member-comparison" as const,
token_identity: "build-local" as const,
name_matching: "exact-signature-fallback" as const,
},
left: sideManifest(left),
right: sideManifest(right),
summary,
matching,
methods: methodItems,
fields: fieldItems,
coverage,
evidence_links: [left.evidenceId, right.evidenceId],
limitations,
} satisfies ManagedMemberComparisonResult;
return managedMemberComparisonResultSchema.parse(result);
};