Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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);
+ },
+);