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(reconstruction): retain semantic unknowns in obligation ledgers (#3826)
Liu Jie5d3762456fd9
diff --git a/src/application/ReconstructionObligationCandidates.semantic.test.ts b/src/application/ReconstructionObligationCandidates.semantic.test.tsnew file mode 100644index 000000000..81362c87b--- /dev/null+++ b/src/application/ReconstructionObligationCandidates.semantic.test.ts@@ -0,0 +1,205 @@+import { describe, expect, it } from "vitest";++import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../contracts/javascript/javascriptRuntimeReconciliationExample.js";+import { createEvidence } from "../domain/evidence.js";+import { createEvidenceBundle } from "../domain/evidenceBundle.js";+import { jsonValueSchema } from "../domain/jsonValue.js";+import { javascriptApplicationAnalysisResultSchema } from "../domain/javascript/javascriptApplicationAnalysis.js";+import { artifactEvidence } from "../domain/javascript/javascriptApplicationGraph.fixture.js";+import {+ createJavaScriptSemanticGraph,+ createJavaScriptSemanticGraphNode,+ createJavaScriptSemanticGraphUnknown,+ JavaScriptSemanticEvidenceContextRegistry,+} from "../domain/javascript/javascriptSemanticGraph.js";+import { deriveReconstructionObligationCandidates } from "./ReconstructionObligationCandidates.js";+import { build, request } from "./ReconstructionObligationLedger.fixture.js";++const semanticApplication = (+ frontiers: readonly {+ detail: string;+ binding: "event" | "module" | "candidate" | "family";+ }[] = [],+ incomplete = false,+) => {+ const example = JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE;+ const base = javascriptApplicationAnalysisResultSchema.parse(+ example.normalized_result,+ );+ const contexts = new JavaScriptSemanticEvidenceContextRegistry();+ for (const context of base.semantic_graph.evidence_contexts)+ contexts.adopt(context);+ const module = base.semantic_graph.nodes[0]!;+ const evidence = artifactEvidence(base.root_artifact_sha256, "renderer.js");+ const event = createJavaScriptSemanticGraphNode(+ {+ kind: "event",+ identity: { ...module.identity, role_key: "event" },+ function_node_id: null,+ application_node_ids: [],+ label: "Event boundary",+ properties: {},+ evidence,+ },+ contexts,+ );+ const unknowns = frontiers.map(({ detail, binding }) =>+ createJavaScriptSemanticGraphUnknown(+ {+ node_id:+ binding === "event"+ ? event.node_id+ : binding === "module"+ ? module.node_id+ : null,+ family: "event",+ relation_kinds: ["registers-listener"],+ reason: "ambiguous-target",+ detail,+ candidate_node_ids: binding === "candidate" ? [event.node_id] : [],+ evidence: {+ ...evidence,+ authority: "unknown",+ state: "unknown",+ confidence: "unknown",+ limitations: [detail],+ },+ },+ contexts,+ ),+ );+ const { graph_id: _graphId, ...semantic } = base.semantic_graph;+ const graph = createJavaScriptSemanticGraph({+ ...semantic,+ nodes: [module, event],+ evidence_contexts: contexts.contexts,+ unknowns,+ coverage: {+ ...semantic.coverage,+ status: unknowns.length > 0 || incomplete ? "unknown" : "complete",+ families: semantic.coverage.families.map((family) => ({+ ...family,+ status:+ family.family === "event" && (unknowns.length > 0 || incomplete)+ ? "unknown"+ : "complete",+ unknown_ids:+ family.family === "event"+ ? unknowns.map(({ unknown_id }) => unknown_id).sort()+ : [],+ })),+ },+ limitations:+ incomplete || unknowns.length > 0+ ? ["Event source was not fully examined."]+ : [],+ });+ const application = createEvidence(+ {+ path: base.input_path,+ sha256: base.root_artifact_sha256,+ format: base.format,+ },+ example.provider,+ {+ predicateType: example.predicate_type,+ operation: example.operation,+ parameters: example.parameters,+ result: jsonValueSchema.parse({ ...base, semantic_graph: graph }),+ confidence: "derived",+ authority: "shipped-artifact",+ },+ );+ return { application, graph, event, unknowns };+};++describe("semantic uncertainty at the obligation candidate boundary", () => {+ it("binds only definite node unknowns and retains every other frontier as a limitation", () => {+ const source = semanticApplication([+ { detail: "Dynamic event name.", binding: "event" },+ { detail: "Module has no obligation policy.", binding: "module" },+ { detail: "Possible event target only.", binding: "candidate" },+ { detail: "Unknown event family frontier.", binding: "family" },+ ]);+ const ledger = build(request([source.application]));+ expect(ledger.obligations).toHaveLength(1);+ const boundId = source.unknowns[0]!.unknown_id;+ expect(ledger.obligations[0]).toMatchObject({+ family: "event",+ residual_unknown_ids: [boundId],+ diagnostics: expect.arrayContaining([+ expect.objectContaining({ code: "residual-unknown" }),+ ]),+ });+ expect(ledger.reports.residual_unknown_ids).toEqual([boundId]);+ expect(ledger.coverage.status).toBe("partial");+ for (const unknown of source.unknowns)+ expect(ledger.limitations).toContain(+ `Semantic graph ${source.graph.graph_id} contains unresolved ${unknown.family} unknown ${unknown.unknown_id}: ${unknown.detail}`,+ );+ });++ it("unions repeated generated observations without losing or duplicating residual unknowns", () => {+ const first = semanticApplication([+ { detail: "First frontier.", binding: "event" },+ { detail: "Shared frontier.", binding: "event" },+ ]);+ const second = semanticApplication([+ { detail: "Second frontier.", binding: "event" },+ { detail: "Shared frontier.", binding: "event" },+ ]);+ const complete = semanticApplication();+ const records = [+ first.application,+ second.application,+ complete.application,+ ];+ const expected = [+ ...new Set(+ [...first.unknowns, ...second.unknowns].map(+ ({ unknown_id }) => unknown_id,+ ),+ ),+ ].sort();+ for (const order of [records, [...records].reverse()]) {+ const generated = deriveReconstructionObligationCandidates(+ createEvidenceBundle(order),+ [],+ );+ expect(generated.candidates).toHaveLength(1);+ expect(generated.candidates[0]).toMatchObject({+ definitionCount: 1,+ residual_unknown_ids: expected,+ });+ expect(generated.candidates[0]!.authority_references).toHaveLength(3);+ const ledger = build(request(order));+ expect(ledger.reports.residual_unknown_ids).toEqual(expected);+ expect(+ ledger.obligations[0]!.diagnostics.map(({ code }) => code),+ ).not.toContain("duplicate-definition");+ }+ });++ it("retains incomplete coverage and source limitations even without explicit unknown records", () => {+ const source = semanticApplication([], true);+ const ledger = build(request([source.application]));+ expect(ledger.obligations).toHaveLength(1);+ expect(ledger.reports.residual_unknown_ids).toEqual([]);+ expect(ledger.coverage.status).toBe("partial");+ expect(ledger.limitations).toEqual([+ `Semantic graph ${source.graph.graph_id} coverage is unknown; omitted candidates remain unknown.`,+ `Semantic graph ${source.graph.graph_id}: Event source was not fully examined.`,+ ]);+ });++ it("keeps a complete semantic source complete without fabricating uncertainty", () => {+ const { application } = semanticApplication();+ const ledger = build(request([application]));+ expect(ledger.obligations).toHaveLength(1);+ expect(ledger.obligations[0]!.residual_unknown_ids).toEqual([]);+ expect(ledger.reports.residual_unknown_ids).toEqual([]);+ expect(ledger.limitations).toEqual([]);+ expect(ledger.coverage.status).toBe("complete");+ expect(ledger.status).toBe("open");+ });+});diff --git a/src/application/ReconstructionObligationCandidates.test.ts b/src/application/ReconstructionObligationCandidates.test.tsindex 26aac22c3..89f9714da 100644--- a/src/application/ReconstructionObligationCandidates.test.ts+++ b/src/application/ReconstructionObligationCandidates.test.ts@@ -322,7 +322,10 @@ it("keeps each semantic candidate bound to its own file and authority context",createEvidenceBundle([...sourceRecords, application]),[],);- expect(generated.limitations).toEqual([]);+ expect(generated.limitations).toEqual([+ `Semantic graph ${semanticGraph.graph_id} coverage is unknown; omitted candidates remain unknown.`,+ `Semantic graph ${semanticGraph.graph_id}: Semantic relations are unavailable in this minimal example.`,+ ]);expect(generated.candidates).toHaveLength(requests.length);for (const [index, node] of requests.entries()) {const source = sourceRecords[Math.floor(index / 2)];diff --git a/src/application/ReconstructionObligationCandidates.ts b/src/application/ReconstructionObligationCandidates.tsindex 6b72ab2b2..e9ab00155 100644--- a/src/application/ReconstructionObligationCandidates.ts+++ b/src/application/ReconstructionObligationCandidates.ts@@ -124,13 +124,35 @@ const deriveApplicationCandidates = ();}if (source.semanticGraph !== null) {+ const semanticGraph = source.semanticGraph;+ const unknownIdsByNode = new Map<string, string[]>();+ for (const unknown of semanticGraph.unknowns) {+ // Candidate targets are possibilities, not established node bindings.+ if (unknown.node_id !== null) {+ const ids = unknownIdsByNode.get(unknown.node_id) ?? [];+ ids.push(unknown.unknown_id);+ unknownIdsByNode.set(unknown.node_id, ids);+ }+ // Keep every frontier visible, including families without a policy.+ limitations.add(+ `Semantic graph ${semanticGraph.graph_id} contains unresolved ${unknown.family} unknown ${unknown.unknown_id}: ${unknown.detail}`,+ );+ }+ if (semanticGraph.coverage.status !== "complete")+ limitations.add(+ `Semantic graph ${semanticGraph.graph_id} coverage is ${semanticGraph.coverage.status}; omitted candidates remain unknown.`,+ );+ for (const limitation of semanticGraph.limitations)+ limitations.add(+ `Semantic graph ${semanticGraph.graph_id}: ${limitation}`,+ );const evidenceContexts = new Map(- source.semanticGraph.evidence_contexts.map((context) => [+ semanticGraph.evidence_contexts.map((context) => [context.context_id,context,]),);- for (const node of source.semanticGraph.nodes) {+ for (const node of semanticGraph.nodes) {const candidatePolicy = semanticObligationPolicy(node.kind);if (candidatePolicy === undefined) continue;const evidenceContext = evidenceContexts.get(node.evidence.context_id);@@ -147,13 +169,14 @@ const deriveApplicationCandidates = (artifactSha256: node.identity.artifact_sha256,applicationNodeId: node.application_node_ids[0] ?? null,semanticNodeId: node.node_id,- location: `semantic-graph:${source.semanticGraph.graph_id}/nodes/${node.node_id}`,+ residualUnknownIds: unknownIdsByNode.get(node.node_id) ?? [],+ location: `semantic-graph:${semanticGraph.graph_id}/nodes/${node.node_id}`,authorityReferences: [graphReference(evidence,records,evidenceContext,- `${source.semanticGraph.graph_id}/node/${node.node_id}`,+ `${semanticGraph.graph_id}/node/${node.node_id}`,),],}),@@ -271,6 +294,7 @@ interface GeneratedCandidateInput {readonly applicationNodeId: string | null;readonly semanticNodeId: string | null;readonly location: string;+ readonly residualUnknownIds?: ReconstructionObligation["residual_unknown_ids"];readonly authorityReferences: ReconstructionObligation["authority_references"];}@@ -283,6 +307,7 @@ const generatedCandidate = ({semanticNodeId,location,authorityReferences,+ residualUnknownIds = [],}: GeneratedCandidateInput): ReconstructionObligationCandidate => ({obligation_id: obligationId(key),obligation_version: 1,@@ -306,7 +331,7 @@ const generatedCandidate = ({required_verifier_authority: candidatePolicy.verifierAuthority,requires_parser_type: candidatePolicy.requiresParserType,dependency_obligation_ids: [],- residual_unknown_ids: [],+ residual_unknown_ids: residualUnknownIds,unavailable_authority: [],required_next_evidence: [`Obtain ${candidatePolicy.originalAuthority} authority for this finite ${candidatePolicy.family} claim.`,@@ -419,6 +444,10 @@ const addCandidate = (...current.authority_references,...candidate.authority_references,]),+ residual_unknown_ids: uniqueBy(+ [...current.residual_unknown_ids, ...candidate.residual_unknown_ids],+ (item) => item,+ ),// Each observation keeps its own unresolved authority and next steps.unavailable_authority: uniqueSorted([...current.unavailable_authority,diff --git a/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts b/tests/boundary/cli/reconstructionObligationLedgerCli.test.tsindex 1392ecbf8..57516d335 100644--- a/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts+++ b/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts@@ -1,9 +1,16 @@import { execFile } from "node:child_process";import { promisify } from "node:util";+import { writeFile } from "node:fs/promises";+import { join } from "node:path";import { describe, expect, it } from "vitest";-import { createEvidence } from "../../../src/domain/evidence.js";+import { cliTest } from "../../support/cli/cliFixture.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js";+import { reconstructionObligationLedgerSchema } from "../../../src/domain/reconstructionObligationLedgerSchemas.js";++import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";import {MIXED_AUTHORITY_SUMMARY,@@ -223,3 +230,86 @@ describe("reconstruction obligation ledger CLI contradictions", () => {}}, 20_000);});++cliTest(+ "retains authentic dynamic-event uncertainty through analysis and ledger CLI",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-ledger-semantic-");+ await writeFile(+ join(root, "package.json"),+ JSON.stringify({ name: "sample-app", version: "1.0.0", main: "main.js" }),+ );+ await writeFile(+ join(root, "main.js"),+ [+ "const events = require('node:events');",+ "const bus = new events.EventEmitter();",+ "bus.on(process.argv[2], () => console.log('done'));",+ ].join("\n"),+ );+ const analyzed = await cli.run({+ arguments: ["analyze-javascript-application", root, "--json"],+ });+ expect(analyzed.exitCode).toBe(0);+ const application = parseEvidence(analyzed.json);+ const source = javascriptApplicationAnalysisResultSchema.parse(+ application.normalized_result,+ );+ expect(source.graph.coverage.status).toBe("complete");+ expect(source.semantic_graph.coverage.status).toBe("unknown");+ const eventUnknown = source.semantic_graph.unknowns.find(+ ({ family }) => family === "event",+ );+ expect(eventUnknown?.detail).toBe(+ "Dynamic on event name remains unresolved.",+ );+ if (eventUnknown === undefined)+ throw new Error("Missing analyzer event frontier");+ const requestPath = join(root, "ledger-request.json");+ await writeFile(+ requestPath,+ JSON.stringify({+ evidence_bundle: createEvidenceBundle([application]),+ reviewed_obligations: [],+ manifest: { bindings: [], contradictions: [] },+ }),+ );+ const built = await cli.run({+ arguments: [+ "build-reconstruction-obligation-ledger",+ requestPath,+ "--json",+ ],+ });+ expect(built.exitCode).toBe(0);+ const ledger = reconstructionObligationLedgerSchema.parse(+ parseEvidence(built.json).normalized_result,+ );+ const event = ledger.obligations.find(+ ({ target }) => target.semantic_node_id === eventUnknown.node_id,+ );+ expect(event).toMatchObject({+ family: "event",+ residual_unknown_ids: [eventUnknown.unknown_id],+ diagnostics: expect.arrayContaining([+ expect.objectContaining({ code: "residual-unknown" }),+ ]),+ });+ expect(+ ledger.obligations.some(({ family }) => family === "package-lifecycle"),+ ).toBe(true);+ expect(ledger.reports.residual_unknown_ids).toContain(+ eventUnknown.unknown_id,+ );+ expect(ledger.coverage.status).toBe("partial");+ expect(ledger.status).not.toBe("ready");+ for (const unknown of source.semantic_graph.unknowns)+ expect(+ ledger.limitations.some(+ (limitation) =>+ limitation.includes(unknown.unknown_id) &&+ limitation.includes(unknown.detail),+ ),+ ).toBe(true);+ },+);