fix(analysis): preserve relationship coverage across evidence and replay

Separate observed relationship coverage from general provider caveats. Authenticate and replay coverage without changing legacy Evidence IDs; expose unknown and capped relationship sets through CLI/MCP graphs and traces.

Validated focused domain, snapshot, IDA/Ghidra boundary, MCP, schema, package and static checks. Provider fixtures establish contract behavior; licensed engine behavior was not reverified.
This commit is contained in:
morluto
2026-10-12 05:57:35 +08:00
parent f1924cf9c1
commit 9c8511409c
24 changed files with 469 additions and 55 deletions
@@ -441,7 +441,7 @@ describe("analysis snapshot cache partitioning", () => {
ANALYSIS_SNAPSHOT_PROFILE,
createEvidenceBundle([evidence]),
);
if (!exported.ok) throw new Error("snapshot export failed");
if (!exported.ok) throw exported.error;
const tampered = structuredClone(exported.value);
const tamperedEntry = tampered.entries[0];
if (tamperedEntry === undefined)
@@ -499,3 +499,105 @@ describe("analysis snapshot cache partitioning", () => {
).toBeUndefined();
});
});
describe("relationship coverage snapshot replay", () => {
it("authenticates relationship coverage and replays legacy reads as unknown", () => {
const cache = new AnalysisSnapshotCache();
const operation = "procedure_callees" as const;
const parameters = { procedure: "0x1000", document: "fixture" };
const coverage = { status: "complete" as const };
const execution = createAnalysisExecution(
["0x2000"],
ANALYSIS_SNAPSHOT_PROVIDER,
{
analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
rawResult: ["0x2000"],
relationshipCoverage: coverage,
subject: {
path: ANALYSIS_SNAPSHOT_TARGET.path,
sha256: ANALYSIS_SNAPSHOT_TARGET.sha256,
format: ANALYSIS_SNAPSHOT_TARGET.format,
...(ANALYSIS_SNAPSHOT_TARGET.architecture === undefined
? {}
: { architecture: ANALYSIS_SNAPSHOT_TARGET.architecture }),
},
},
);
cache.record({
target: ANALYSIS_SNAPSHOT_TARGET,
profile: ANALYSIS_SNAPSHOT_PROFILE,
operation,
parameters,
execution,
});
const evidence = createEvidence(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROVIDER,
{
operation,
parameters,
result: ["0x2000"],
rawResult: ["0x2000"],
analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
relationshipCoverage: coverage,
},
);
const exported = cache.export(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROFILE,
createEvidenceBundle([evidence]),
);
if (!exported.ok) throw exported.error;
expect(
cache.lookup(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROFILE,
operation,
parameters,
)?.relationshipCoverage,
).toEqual(coverage);
const tampered = structuredClone(exported.value);
const tamperedEntry = tampered.entries[0];
if (tamperedEntry === undefined) throw new Error("snapshot entry missing");
tamperedEntry.execution.relationship_coverage = {
status: "partial",
limitations: ["forged coverage"],
};
expect(
new AnalysisSnapshotCache().import(tampered, undefined, () => ok(0)).ok,
).toBe(false);
const legacy = structuredClone(exported.value);
const legacyEntry = legacy.entries[0];
if (legacyEntry === undefined) throw new Error("snapshot entry missing");
Reflect.deleteProperty(legacyEntry.execution, "relationship_coverage");
const legacyEvidence = createEvidence(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROVIDER,
{
operation,
parameters,
result: ["0x2000"],
rawResult: ["0x2000"],
analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
},
);
Reflect.deleteProperty(legacyEvidence, "relationship_coverage");
legacy.evidence_bundle = createEvidenceBundle([legacyEvidence]);
parseAnalysisSnapshot(legacy);
const replayCache = new AnalysisSnapshotCache();
expect(replayCache.import(legacy, undefined, () => ok(0)).ok).toBe(true);
expect(
replayCache.lookup(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROFILE,
operation,
parameters,
)?.relationshipCoverage,
).toEqual({
status: "unknown",
reason: "Snapshot entry does not report relationship coverage.",
});
});
});
@@ -34,6 +34,11 @@ import type {
import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
const RELATIONSHIP_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
"procedure_callers",
"procedure_callees",
]);
const STATEFUL_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
"health",
"current_address",
@@ -241,6 +246,7 @@ export class AnalysisSnapshotCache {
readonly provider: AnalysisExecution["provider"];
readonly analysisProfile: AnalysisProfileCommitment;
readonly limitations: readonly string[];
readonly relationshipCoverage?: AnalysisExecution["relationshipCoverage"];
readonly locations: AnalysisExecution["locations"];
readonly subject: AnalysisExecution["subject"];
};
@@ -302,6 +308,19 @@ export class AnalysisSnapshotCache {
...cached.execution.limitations,
"Loaded from a local REA analysis snapshot; this call did not re-run the provider.",
],
...(cached.execution.relationship_coverage === null &&
RELATIONSHIP_OPERATIONS.has(operation)
? {
relationshipCoverage: {
status: "unknown",
reason: "Snapshot entry does not report relationship coverage.",
},
}
: cached.execution.relationship_coverage === null
? {}
: {
relationshipCoverage: cached.execution.relationship_coverage,
}),
locations: cached.execution.locations,
subject,
});
+28 -10
View File
@@ -594,9 +594,22 @@ export class BinarySession
name,
active.target,
);
this.#observeRuntimeAvailability(name, profiled);
if (
const execution =
profiled.ok &&
(name === "procedure_callers" || name === "procedure_callees") &&
profiled.value.relationshipCoverage === undefined
? ok({
...profiled.value,
relationshipCoverage: {
status: "unknown" as const,
reason:
"Provider did not report relationship coverage for this observation.",
},
})
: profiled;
this.#observeRuntimeAvailability(name, execution);
if (
execution.ok &&
cacheable &&
profile !== undefined &&
name !== "decode_interface_builder" &&
@@ -605,16 +618,21 @@ export class BinarySession
name !== "trace_dylib_resolution"
) {
const evidence = createEvidence(
profiled.value.subject ?? active.target,
profiled.value.provider,
execution.value.subject ?? active.target,
execution.value.provider,
{
operation: name,
parameters: arguments_,
result: profiled.value.result,
result: execution.value.result,
analysisProfile: profile,
rawResult: profiled.value.rawResult,
limitations: profiled.value.limitations,
locations: profiled.value.locations,
rawResult: execution.value.rawResult,
limitations: execution.value.limitations,
...(execution.value.relationshipCoverage === undefined
? {}
: {
relationshipCoverage: execution.value.relationshipCoverage,
}),
locations: execution.value.locations,
},
);
const recorded = this.recordEvidence(evidence);
@@ -624,12 +642,12 @@ export class BinarySession
profile,
operation: name,
parameters: arguments_,
execution: profiled.value,
execution: execution.value,
});
} else if (profiled.ok && capability.effects.mutatesArtifact) {
this.invalidateSnapshot();
}
return profiled;
return execution;
}
#observeRuntimeAvailability(