Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(artifacts): compare PyInstaller declaration facts
morluto142cf188a7c0
diff --git a/docs/python-packaged-applications.md b/docs/python-packaged-applications.mdindex fd561be39..ab0b7680e 100644--- a/docs/python-packaged-applications.md+++ b/docs/python-packaged-applications.md@@ -50,6 +50,15 @@ table index; original names remain available in the supplied artifact.Path failures use bounded escaped previews and report the original length;accepted paths and retained source names are not shortened.+`compare_artifacts` compares these node-less records as declarations using the+container, container name, source name and type code. Equal option or dependency+declarations can therefore compare unchanged without implying that an external+dependency's bytes were found. For materialized PyInstaller members, the same+fields participate in the metadata delta independently of content identity;+archive offsets and table positions remain location facts, not declaration+identity. Missing declaration facts and unavailable non-metadata content remain+unknown.+Request `detail: "summary"` for a compact inspection, then query retainedEvidence with `inspect_analysis_view`. An inventory view can select`collection: "occurrences"`, `entry_kinds: ["metadata"]`, exact logical paths ordiff --git a/src/domain/artifactComparison.ts b/src/domain/artifactComparison.tsindex 73084df6e..a9f69be47 100644--- a/src/domain/artifactComparison.ts+++ b/src/domain/artifactComparison.ts@@ -14,6 +14,7 @@ import {parseArtifactInventoryEvidence,type InventorySet,} from "./artifactInventoryEvidence.js";+import { pyInstallerEntryDeclaration } from "./artifactFormatMetadata.js";import { prefixedDigestSchema } from "./../domain/digests.js";import { canonicalJson } from "./comparisonSemantics.js";@@ -363,14 +364,84 @@ const classifyPath = (input: ClassifyPathInput): ArtifactChange | null => {const base = buildArtifactChangeBase(input);const integrity = classifyIntegrity(input, base);if (integrity !== null) return integrity;+ const declaration = classifyPyInstallerDeclaration(input, base);+ if (declaration.handled) return declaration.change;const availability = classifyAvailability(input, base);if (availability !== null) return availability;const dimensions = changedDimensions(input);+ if (pyInstallerMetadataUnknown(input)) {+ if (dimensions.length === 0)+ return {+ ...base,+ classification: "unknown",+ dimensions: ["availability"],+ };+ dimensions.push("availability");+ }return dimensions.length === 0? null: { ...base, classification: "changed", dimensions };};+const pyInstallerMetadataUnknown = (input: ClassifyPathInput): boolean =>+ (isPyInstallerEntry(input.leftOccurrence) &&+ !isPyInstallerEntry(input.rightOccurrence)) ||+ (isPyInstallerEntry(input.rightOccurrence) &&+ !isPyInstallerEntry(input.leftOccurrence));++const isPyInstallerEntry = (+ occurrence: ArtifactOccurrence | undefined,+): occurrence is ArtifactOccurrence & {+ readonly format_metadata: Extract<+ NonNullable<ArtifactOccurrence["format_metadata"]>,+ { readonly kind: "pyinstaller-entry" }+ >;+} => occurrence?.format_metadata?.kind === "pyinstaller-entry";++const classifyPyInstallerDeclaration = (+ input: ClassifyPathInput,+ base: ReturnType<typeof buildArtifactChangeBase>,+): { readonly handled: boolean; readonly change: ArtifactChange | null } => {+ const leftIsDeclaration = input.leftOccurrence?.entry_kind === "metadata";+ const rightIsDeclaration = input.rightOccurrence?.entry_kind === "metadata";+ if (!leftIsDeclaration && !rightIsDeclaration)+ return { handled: false, change: null };+ // Metadata is not inherently a PyInstaller declaration. Only apply this+ // format-specific comparison when a producer explicitly identified one.+ if (+ !isPyInstallerEntry(input.leftOccurrence) &&+ !isPyInstallerEntry(input.rightOccurrence)+ )+ return { handled: false, change: null };+ if (!leftIsDeclaration || !rightIsDeclaration)+ return { handled: false, change: null };+ if (+ !isPyInstallerEntry(input.leftOccurrence) ||+ !isPyInstallerEntry(input.rightOccurrence)+ )+ return {+ handled: true,+ change: {+ ...base,+ classification: "unknown",+ dimensions: ["availability"],+ },+ };+ const changed =+ canonicalJson(+ pyInstallerEntryDeclaration(input.leftOccurrence.format_metadata),+ ) !==+ canonicalJson(+ pyInstallerEntryDeclaration(input.rightOccurrence.format_metadata),+ );+ return {+ handled: true,+ change: changed+ ? { ...base, classification: "changed", dimensions: ["metadata"] }+ : null,+ };+};+const changedDimensions = (input: {readonly leftNode: ArtifactNode | undefined;readonly rightNode: ArtifactNode | undefined;@@ -430,7 +501,15 @@ const metadataChanged = (input.leftOccurrence?.encrypted !== input.rightOccurrence?.encrypted ||JSON.stringify(left.limitations) !== JSON.stringify(right.limitations) ||JSON.stringify(input.leftOccurrence?.limitations) !==- JSON.stringify(input.rightOccurrence?.limitations);+ JSON.stringify(input.rightOccurrence?.limitations) ||+ (isPyInstallerEntry(input.leftOccurrence) &&+ isPyInstallerEntry(input.rightOccurrence) &&+ canonicalJson(+ pyInstallerEntryDeclaration(input.leftOccurrence.format_metadata),+ ) !==+ canonicalJson(+ pyInstallerEntryDeclaration(input.rightOccurrence.format_metadata),+ ));const nodeFor = (occurrence: ArtifactOccurrence | undefined,diff --git a/src/domain/artifactFormatMetadata.ts b/src/domain/artifactFormatMetadata.tsindex 4ba7f6475..8e4aca78b 100644--- a/src/domain/artifactFormatMetadata.ts+++ b/src/domain/artifactFormatMetadata.ts@@ -88,6 +88,17 @@ export const pyInstallerEntryMetadataSchema = z.strictObject({export type PyInstallerEntryMetadata = z.infer<typeof pyInstallerEntryMetadataSchema>;++/** Declaration identity that is stable across archive layout changes. */+export const pyInstallerEntryDeclaration = (+ metadata: PyInstallerEntryMetadata,+) => ({+ container: metadata.container,+ container_name: metadata.container_name,+ source_name: metadata.source_name,+ type_code: metadata.type_code,+});+export const artifactFormatMetadataSchema = z.discriminatedUnion("kind", [godotPckMetadataSchema,godotPckEntryMetadataSchema,diff --git a/tests/boundary/mcp/artifactMcp.test.ts b/tests/boundary/mcp/artifactMcp.test.tsindex 94f7e5150..c6b27cc79 100644--- a/tests/boundary/mcp/artifactMcp.test.ts+++ b/tests/boundary/mcp/artifactMcp.test.ts@@ -3,6 +3,13 @@ import { parseMcpToolError } from "../../fixtures/mcpToolError.js";import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";import { jsonValueSchema } from "../../../src/domain/jsonValue.js";import { artifactInventoryResultSchema } from "../../../src/domain/artifactGraph.js";+import {+ artifactEdgeId,+ artifactGraphDigest,+ artifactManifestId,+ occurrenceIdForLocation,+} from "../../../src/domain/artifactIdentity.js";+import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js";import { ok as resultOk } from "../../../src/domain/result.js";import { mkdir, readFile, rm, writeFile } from "node:fs/promises";import { join } from "node:path";@@ -24,6 +31,8 @@ import { ArtifactProvider } from "../../../src/artifacts/ArtifactProvider.js";import { ARTIFACT_COMPARISON_EXAMPLE } from "../../../src/contracts/artifactComparisonExample.js";import { createServer } from "../../../src/server/createServer.js";import { observed } from "../../fixtures/analysisExecution.js";+import { cArchiveExecutable } from "../../../src/artifacts/pyinstaller/CArchive.fixture.js";+import { compareUnicodeCodePoints } from "../../../src/domain/unicodeCodePointOrder.js";const integrityMessage = (unpacked: boolean): string =>`${@@ -660,6 +669,354 @@ it("compares summary Evidence through retained complete inspection parents", asyconst toolEvidence = (value: unknown) => parseEvidence(value);+const pyInstallerComparisonArchive = (+ typeCode: "m" | "s",+ includeSymlink: boolean,+ includePrefix = false,+) =>+ cArchiveExecutable({+ layout: "2.1",+ pythonVersion: 309,+ members: [+ ...(includePrefix+ ? [+ {+ name: "prefix.bin",+ typeCode: "x" as const,+ payload: Buffer.from("prefix bytes"),+ compress: false,+ },+ ]+ : []),+ {+ name: "helper",+ typeCode,+ payload: Buffer.from("same helper bytes"),+ compress: false,+ },+ {+ name: "pyi-contents-directory _internal",+ typeCode: "o",+ payload: Buffer.alloc(0),+ compress: false,+ },+ {+ name: "shared-app:assets/data.bin",+ typeCode: "d",+ payload: Buffer.alloc(0),+ compress: false,+ },+ ...(includeSymlink+ ? [+ {+ name: "unavailable-link",+ typeCode: "n" as const,+ payload: Buffer.from("target"),+ compress: false,+ },+ ]+ : []),+ ],+ });++const inspectArtifactInventoryThroughMcp = async (+ client: Client,+ path: string,+) => {+ const opened = await client.callTool({+ name: "open_binary",+ arguments: { path },+ });+ expect(opened.isError).not.toBe(true);+ const reply = await client.callTool({+ name: "inspect_artifact",+ arguments: {},+ });+ expect(reply.isError).not.toBe(true);+ const inspection = artifactInspectionResultSchema.parse(+ toolEvidence(reply.structuredContent).normalized_result,+ );+ const inventory = inspection.substeps.find(+ ({ operation }) => operation === "inventory_artifact",+ )?.evidence;+ if (inventory === undefined) throw new Error("missing inventory Evidence");+ return parseEvidence(inventory);+};++const compareArtifactEvidenceThroughMcp = (+ client: Client,+ left: Record<string, unknown>,+ right: Record<string, unknown>,+) => client.callTool({ name: "compare_artifacts", arguments: { left, right } });++const withForeignMetadataAndNestedZipMember = (+ evidence: ReturnType<typeof parseEvidence>,+) => {+ const inventory = artifactInventoryResultSchema.parse(+ evidence.normalized_result,+ );+ const helper = inventory.occurrences.find(+ ({ logical_path }) => logical_path === "helper",+ );+ if (helper === undefined) throw new Error("missing helper occurrence");+ const { format_metadata: _formatMetadata, ...helperWithoutMetadata } = helper;+ const foreignMetadataId = occurrenceIdForLocation({+ rootArtifactId: inventory.manifest.root_artifact_id,+ logicalPath: "foreign-meta",+ entryKind: "metadata",+ });+ const foreignMetadata = {+ ...helperWithoutMetadata,+ occurrence_id: foreignMetadataId,+ logical_path: "foreign-meta",+ entry_kind: "metadata" as const,+ artifact_format: "zip" as const,+ };+ const nestedZipMember = {+ ...helperWithoutMetadata,+ occurrence_id: occurrenceIdForLocation({+ rootArtifactId: inventory.manifest.root_artifact_id,+ logicalPath: "helper/member.txt",+ entryKind: "file",+ }),+ parent_occurrence_id: helper.occurrence_id,+ logical_path: "helper/member.txt",+ artifact_format: "zip" as const,+ };+ const occurrences = inventory.occurrences+ .concat(foreignMetadata, nestedZipMember)+ .sort((left, right) =>+ compareUnicodeCodePoints(left.logical_path, right.logical_path),+ );+ const edges = inventory.edges+ .map((edge) => {+ const occurrence = occurrences.find(+ ({ occurrence_id }) => occurrence_id === edge.occurrence_id,+ );+ return occurrence === undefined+ ? edge+ : { ...edge, edge_id: artifactEdgeId(edge, occurrence) };+ })+ .sort((left, right) =>+ compareUnicodeCodePoints(left.edge_id, right.edge_id),+ );+ const graphSha256 = artifactGraphDigest({+ nodes: inventory.nodes,+ occurrences,+ edges,+ contradictions: inventory.integrity_contradictions,+ });+ const manifestId = artifactManifestId(+ inventory.manifest.root_artifact_id,+ graphSha256,+ );+ const subject = evidence.subject;+ if (subject === null) throw new Error("missing inventory subject");+ return createEvidence(+ {+ path: subject.local_path,+ sha256: subject.digest.sha256,+ format: subject.format,+ },+ evidence.provider,+ {+ operation: "inventory_artifact",+ parameters: evidence.parameters,+ confidence: evidence.confidence,+ authority: evidence.authority,+ result: jsonValueSchema.parse({+ ...inventory,+ occurrences,+ edges,+ manifest: {+ ...inventory.manifest,+ occurrence_count: occurrences.length,+ edge_count: edges.length,+ graph_sha256: graphSha256,+ manifest_id: manifestId,+ },+ }),+ },+ );+};++it("does not apply PyInstaller declaration unknowns to foreign metadata or nested ZIP members", async () => {+ const root = await createTestTempDirectory("rea-pyinstaller-scope-mcp-");+ const archive = join(root, "sample");+ await writeFile(archive, pyInstallerComparisonArchive("m", false));+ const session = createTestBinarySession(new ArtifactProvider(process.env));+ const server = createServer({ kind: "session", session });+ const client = new Client({ name: "pyinstaller-scope-test", version: "1" });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ try {+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ const observed = await inspectArtifactInventoryThroughMcp(client, archive);+ const foreign = withForeignMetadataAndNestedZipMember(observed);+ const response = await compareArtifactEvidenceThroughMcp(+ client,+ foreign,+ foreign,+ );+ expect(response.isError).not.toBe(true);+ expect(+ toolEvidence(response.structuredContent).normalized_result,+ ).toMatchObject({+ status: "unchanged",+ summary: { unknown: 0 },+ changes: [],+ });+ } finally {+ await Promise.allSettled([client.close(), server.close(), session.close()]);+ }+});++it("compares PyInstaller declaration facts without inventing payload identity", async () => {+ const root = await createTestTempDirectory("rea-pyinstaller-compare-mcp-");+ const leftPath = join(root, "module");+ const rightPath = join(root, "script");+ const declarationsPath = join(root, "declarations");+ const modulePath = join(root, "module-clean");+ const shiftedPath = join(root, "module-shifted");+ await Promise.all([+ writeFile(leftPath, pyInstallerComparisonArchive("m", true)),+ writeFile(rightPath, pyInstallerComparisonArchive("s", true)),+ writeFile(declarationsPath, pyInstallerComparisonArchive("s", false)),+ writeFile(modulePath, pyInstallerComparisonArchive("m", false)),+ writeFile(shiftedPath, pyInstallerComparisonArchive("m", false, true)),+ ]);+ const session = createTestBinarySession(new ArtifactProvider(process.env));+ const server = createServer({ kind: "session", session });+ const client = new Client({ name: "pyinstaller-compare-test", version: "1" });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ try {+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ const left = await inspectArtifactInventoryThroughMcp(client, leftPath);+ const right = await inspectArtifactInventoryThroughMcp(client, rightPath);+ const clean = await inspectArtifactInventoryThroughMcp(+ client,+ declarationsPath,+ );+ const module = await inspectArtifactInventoryThroughMcp(client, modulePath);+ const shifted = await inspectArtifactInventoryThroughMcp(+ client,+ shiftedPath,+ );+ const leftInventory = artifactInventoryResultSchema.parse(+ left.normalized_result,+ );+ const rightInventory = artifactInventoryResultSchema.parse(+ right.normalized_result,+ );+ const leftHelper = leftInventory.occurrences.find(+ ({ logical_path }) => logical_path === "helper",+ );+ const rightHelper = rightInventory.occurrences.find(+ ({ logical_path }) => logical_path === "helper",+ );+ expect(leftHelper?.artifact_id).toBe(rightHelper?.artifact_id);+ expect(leftHelper?.format_metadata).toMatchObject({ type_code: "m" });+ expect(rightHelper?.format_metadata).toMatchObject({ type_code: "s" });+ expect(+ leftInventory.occurrences.filter(+ ({ entry_kind }) => entry_kind === "metadata",+ ),+ ).toHaveLength(2);++ const changed = await compareArtifactEvidenceThroughMcp(+ client,+ left,+ right,+ );+ expect(changed.isError).not.toBe(true);+ const changedResult = toolEvidence(+ changed.structuredContent,+ ).normalized_result;+ expect(changedResult).toMatchObject({+ status: "unknown",+ summary: { changed: 2, unchanged: 2, unknown: 1 },+ changes: expect.arrayContaining([+ expect.objectContaining({+ logical_path: ".",+ classification: "changed",+ dimensions: expect.arrayContaining(["content"]),+ }),+ expect.objectContaining({+ logical_path: "helper",+ classification: "changed",+ dimensions: ["metadata"],+ left_occurrence_id: leftHelper?.occurrence_id,+ right_occurrence_id: rightHelper?.occurrence_id,+ }),+ expect.objectContaining({+ logical_path: "unavailable-link",+ classification: "unknown",+ dimensions: ["availability"],+ }),+ ]),+ });+ expect(+ z+ .object({ changes: z.array(z.object({ logical_path: z.string() })) })+ .parse(changedResult)+ .changes.map(({ logical_path }) => logical_path),+ ).not.toContain("__pyinstaller__/runtime-options/1");+ expect(+ z+ .object({ changes: z.array(z.object({ logical_path: z.string() })) })+ .parse(changedResult)+ .changes.map(({ logical_path }) => logical_path),+ ).not.toContain("__pyinstaller__/dependencies/2");++ const declarationsOnly = await client.callTool({+ name: "compare_artifacts",+ arguments: { left: clean, right: clean },+ });+ expect(declarationsOnly.isError).not.toBe(true);+ expect(+ toolEvidence(declarationsOnly.structuredContent).normalized_result,+ ).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 4, unknown: 0 },+ changes: [],+ });++ const layoutOnly = await client.callTool({+ name: "compare_artifacts",+ arguments: { left: module, right: shifted },+ });+ expect(layoutOnly.isError).not.toBe(true);+ const layoutChanges = z+ .object({ changes: z.array(z.object({ logical_path: z.string() })) })+ .parse(toolEvidence(layoutOnly.structuredContent).normalized_result)+ .changes.map(({ logical_path }) => logical_path);+ expect(layoutChanges).toContain("prefix.bin");+ expect(layoutChanges).not.toContain("helper");++ const unavailableControl = await client.callTool({+ name: "compare_artifacts",+ arguments: { left, right: left },+ });+ expect(unavailableControl.isError).not.toBe(true);+ expect(+ toolEvidence(unavailableControl.structuredContent).normalized_result,+ ).toMatchObject({+ status: "unknown",+ changes: [+ expect.objectContaining({+ logical_path: "unavailable-link",+ classification: "unknown",+ }),+ ],+ });+ } finally {+ await Promise.allSettled([client.close(), server.close(), session.close()]);+ }+});+it("discovers artifact target prerequisites and preserves typed MCP refusals", async () => {const root = await createTestTempDirectory("rea-artifact-availability-mcp-");const zip = new ZipWriter(new Uint8ArrayWriter());