refactor: compose investigation record ownership (#845)

This commit is contained in:
N0zoM1z0
2026-10-07 12:10:45 +08:00
committed by GitHub
parent bc2cd8b874
commit ce73c3fed2
27 changed files with 627 additions and 127 deletions
+7
View File
@@ -16,6 +16,8 @@ graph TD
APP["src/application/<br/>Shared CLI/MCP workflows<br/>enhanced analysis and investigations"]
SESSION["SessionProviderRouter + BinarySession<br/>one immutable deep binding per target<br/>disjoint auxiliary routing"]
REGISTRY["AnalysisProviderRegistry<br/>sorted deep candidates<br/>deterministic selection, no fallback"]
RECORDS["src/application/investigation/<br/>composed InvestigationRecords + narrow ports<br/>EvidenceLedger and Unknown ownership"]
SNAPSHOT["BinarySessionRecords + AnalysisSnapshotCache<br/>binary target/profile snapshots<br/>compatibility facade and post-commit notifications"]
JS_RECON["src/application/ + src/artifacts/<br/>JavaScript artifact reconstruction<br/>directory/ASAR reads<br/>AST-only bundle projection"]
end
@@ -75,6 +77,11 @@ graph TD
CLI --> ERRORS
APP --> SESSION
SESSION --> REGISTRY
SESSION --> SNAPSHOT
SNAPSHOT --> RECORDS
APP -->|record callbacks| RECORDS
SERVER -->|narrow record ports| RECORDS
RECORDS --> DOMAIN
REGISTRY --> HOPPER
REGISTRY --> GHIDRA
REGISTRY --> IDA
+29 -1
View File
@@ -13,7 +13,7 @@ there is no new universal provider interface or fixed module manifest.
| Producer parsing and external tool protocols | provider adapters | Keep behind the relevant typed port |
| Shared analyst workflows | application | Share between CLI and MCP |
| Concrete provider construction | binary runtime, composition, MCP startup | Consolidate one capability at a time in production composition |
| Investigation Evidence and Unknowns | BinarySessionRecords | Extract one composed record owner after caller migration |
| Investigation Evidence and Unknowns | InvestigationRecords/EvidenceLedger | Consume narrow read/write/atomic record ports |
| Target/profile snapshots and invalidation | BinarySessionRecords/BinarySession | Keep binary-owned |
| Subprocess ownership and host primitives | process/windows | Reuse; preserve cancellation and cleanup |
| Public translation | CLI/MCP adapters | Delegate to shared workflows and named contracts |
@@ -117,3 +117,31 @@ installs nothing. Core transport failures and shutdown still use their existing
lifecycle. Fault-injection coverage uses the production loading/startup path and
actual MCP SDK calls; recording ports establish composition behavior, while the
real Inspector lane separately establishes runtime behavior.
## Investigation record ownership pilot
`src/application/investigation/InvestigationRecords.ts` owns one existing
EvidenceLedger per runtime. The production session composition constructs that
owner explicitly; the direct BinarySession constructor retains a fresh default
for compatibility. There is no second ledger, global store, persistence or new
retention policy.
EvidenceReader, EvidenceWriter and EvidenceUnknownWriter describe existing
read/write/atomic callback needs. UnknownRegistryPort preserves optimistic
revisions and consistency verification. Non-binary MCP registrars use these
record types without depending on the binary execution/lifecycle surface.
BinarySessionPort retains its compatible record methods through composition.
BinarySessionRecords remains the snapshot owner and compatibility facade. It
passes the actual active target explicitly for recordUnknown/updateUnknown;
recordEvidenceWithUnknown keeps its target-free mutation subject. Snapshot import
merges records without notifying midway, then emits after the cache commits.
Bundle import retains the full change delta so Unknown-only changes notify even
when recordsAdded is zero. Clearing resets records, cache and invalidation before
notification; observer failures remain best effort after a committed mutation.
Close and failed-cleanup clearing, ordinary target-switch retention, detached
reads, Evidence identities and deterministic bundle transfer keep their existing
behavior. Snapshots still require an active target and concrete analysis profile;
extracting investigation ownership does not make them a target-free record store.
#721 remains responsible for any future lifetime-policy change.
+6 -2
View File
@@ -24,6 +24,7 @@ import {
SessionProviderRouter,
type SessionProviderRoute,
} from "./SessionProviderRouter.js";
import { InvestigationRecords } from "./investigation/InvestigationRecords.js";
import { BinarySessionRecords } from "./BinarySessionRecords.js";
import { binarySessionStatus } from "./BinarySessionStatus.js";
import {
@@ -78,8 +79,11 @@ export class BinarySession
>();
readonly #availabilityListeners = new Set<() => void | Promise<void>>();
constructor(providerRouter: SessionProviderRouter) {
super();
constructor(
providerRouter: SessionProviderRouter,
records: InvestigationRecords = new InvestigationRecords(),
) {
super(records);
this.#providerRouter = providerRouter;
}
@@ -1,3 +1,4 @@
import { InvestigationRecords } from "./investigation/InvestigationRecords.js";
import type { AnalysisProvider } from "./AnalysisProvider.js";
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
import { BinarySession } from "./BinarySession.js";
@@ -15,4 +16,5 @@ export const composeBinarySession = (
registry instanceof SessionProviderRouter
? registry
: SessionProviderRouter.selectable(registry, auxiliaryProviders),
new InvestigationRecords(),
);
+4 -41
View File
@@ -1,21 +1,13 @@
import type { InvestigationRecordPort } from "./investigation/InvestigationRecordPort.js";
import type { ExecutableFormatHint } from "../domain/dosCom.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Evidence } from "../domain/evidence.js";
import type { EvidenceBundle } from "../domain/evidenceBundle.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
import type { UnknownRegistryError } from "../domain/unknownRegistryError.js";
import type { Result } from "../domain/result.js";
import type {
RecordUnknownInput,
ResidualUnknown,
UnknownStatus,
UpdateUnknownInput,
} from "../domain/residualUnknown.js";
import type {
AnalysisOperation,
AnalysisOperationPort,
@@ -24,7 +16,8 @@ import type {
} from "./AnalysisProvider.js";
/** Target lifecycle used by CLI and MCP without exposing a concrete provider. */
export interface BinarySessionPort extends AnalysisOperationPort {
export interface BinarySessionPort
extends AnalysisOperationPort, InvestigationRecordPort {
open(
path: string,
options?: {
@@ -42,40 +35,10 @@ export interface BinarySessionPort extends AnalysisOperationPort {
): Promise<Result<null, AnalysisError>>;
status(): JsonValue;
activeTarget(): BinaryTarget | undefined;
recordEvidence(
evidence: Evidence,
): Result<"added" | "duplicate", EvidenceIntegrityError>;
hasEvidence(evidenceId: string): boolean;
evidenceById(evidenceId: string): Evidence | undefined;
exportEvidenceBundle(): EvidenceBundle;
importEvidenceBundle(bundle: unknown): Result<number, EvidenceIntegrityError>;
exportAnalysisSnapshot(): Result<AnalysisSnapshot, AnalysisError>;
importAnalysisSnapshot(
snapshot: AnalysisSnapshot,
): Result<number, AnalysisError>;
recordUnknown(
input: RecordUnknownInput,
): Result<ResidualUnknown, AnalysisError>;
recordEvidenceWithUnknown(
evidence: Evidence,
input: RecordUnknownInput,
): Result<ResidualUnknown | null, AnalysisError>;
updateUnknown(
input: UpdateUnknownInput,
): Result<ResidualUnknown, AnalysisError>;
listUnknowns(filters?: {
readonly status?: UnknownStatus;
readonly severity?: ResidualUnknown["severity"];
readonly domain?: string;
}): ResidualUnknown[];
verifyUnknownResolution(unknownId: string): Result<
{
readonly valid: boolean;
readonly truthVerified: boolean;
readonly unknown: ResidualUnknown;
},
UnknownRegistryError
>;
providerIdentity(operation?: AnalysisOperation): ProviderIdentity;
analysisProfile(
operation?: AnalysisOperation,
+25 -45
View File
@@ -1,7 +1,7 @@
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import type { Evidence } from "../domain/evidence.js";
import type { EvidenceBundle } from "../domain/evidenceBundle.js";
import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
@@ -19,25 +19,24 @@ import type {
AnalysisOperation,
} from "./AnalysisProvider.js";
import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
import { EvidenceLedger } from "./EvidenceLedger.js";
import {
UNKNOWN_REGISTRY_PROVIDER,
unknownEvidenceLinks,
unknownMutationEvidence,
} from "./UnknownEvidence.js";
import { InvestigationRecords } from "./investigation/InvestigationRecords.js";
export interface ActiveAnalysisBinding {
readonly target: BinaryTarget;
readonly profile: AnalysisProfileCommitment | null;
}
/** Owns session evidence, snapshots, and residual unknowns. */
/** Binary snapshot owner and compatibility facade for composed investigation records. */
export abstract class BinarySessionRecords {
readonly #evidence = new EvidenceLedger();
readonly #records: InvestigationRecords;
readonly #snapshot = new AnalysisSnapshotCache();
#snapshotInvalidated = false;
readonly #snapshotListeners = new Set<() => void | Promise<void>>();
constructor(records: InvestigationRecords = new InvestigationRecords()) {
this.#records = records;
}
/** Observe changes to the mutable current analysis snapshot resource. */
onAnalysisSnapshotChanged(listener: () => void | Promise<void>): () => void {
this.#snapshotListeners.add(listener);
@@ -47,27 +46,27 @@ export abstract class BinarySessionRecords {
recordEvidence(
evidence: Evidence,
): Result<"added" | "duplicate", EvidenceIntegrityError> {
const recorded = this.#evidence.record(evidence);
const recorded = this.#records.recordEvidence(evidence);
if (recorded.ok && recorded.value === "added") this.#emitSnapshotChanged();
return recorded;
}
hasEvidence(evidenceId: string): boolean {
return this.#evidence.has(evidenceId);
return this.#records.hasEvidence(evidenceId);
}
evidenceById(evidenceId: string): Evidence | undefined {
return this.#evidence.get(evidenceId);
return this.#records.evidenceById(evidenceId);
}
exportEvidenceBundle(): EvidenceBundle {
return this.#evidence.export();
return this.#records.exportEvidenceBundle();
}
importEvidenceBundle(
bundle: unknown,
): Result<number, EvidenceIntegrityError> {
const imported = this.#evidence.import(bundle);
const imported = this.#records.mergeEvidenceBundle(bundle);
if (!imported.ok) return imported;
if (imported.value.changed) this.#emitSnapshotChanged();
return ok(imported.value.recordsAdded);
@@ -95,8 +94,11 @@ export abstract class BinarySessionRecords {
target,
profile,
target === undefined
? this.#evidence.export()
: evidenceBundleForTarget(this.#evidence.export(), target.sha256),
? this.#records.exportEvidenceBundle()
: evidenceBundleForTarget(
this.#records.exportEvidenceBundle(),
target.sha256,
),
);
}
@@ -116,7 +118,7 @@ export abstract class BinarySessionRecords {
? undefined
: { target: active.target, profile: active.profile },
(bundle) => {
const imported = this.#evidence.import(bundle);
const imported = this.#records.mergeEvidenceBundle(bundle);
return imported.ok ? ok(imported.value.recordsAdded) : imported;
},
);
@@ -175,7 +177,7 @@ export abstract class BinarySessionRecords {
}
protected clearSessionRecords(): void {
this.#evidence.clear();
this.#records.clear();
this.#snapshot.clear();
this.#snapshotInvalidated = false;
this.#emitSnapshotChanged();
@@ -202,10 +204,7 @@ export abstract class BinarySessionRecords {
input: RecordUnknownInput,
): Result<ResidualUnknown, AnalysisError> {
const target = this.activeAnalysisBinding()?.target;
const recorded = this.#evidence.recordUnknown(
input,
unknownMutationEvidence(target, input),
);
const recorded = this.#records.recordUnknown(input, target);
if (recorded.ok) this.#emitSnapshotChanged();
return recorded;
}
@@ -214,11 +213,7 @@ export abstract class BinarySessionRecords {
evidence: Evidence,
input: RecordUnknownInput,
): Result<ResidualUnknown | null, AnalysisError> {
const recorded = this.#evidence.recordWithUnknown(
evidence,
input,
unknownMutationEvidence(undefined, input),
);
const recorded = this.#records.recordEvidenceWithUnknown(evidence, input);
if (recorded.ok) this.#emitSnapshotChanged();
return recorded;
}
@@ -227,22 +222,7 @@ export abstract class BinarySessionRecords {
input: UpdateUnknownInput,
): Result<ResidualUnknown, AnalysisError> {
const target = this.activeAnalysisBinding()?.target;
const evidence = createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
predicateType: "rea.residual-unknown-mutation",
operation: "update_unknown",
parameters: {
unknown_id: input.unknown_id,
expected_revision: input.expected_revision,
},
result: { action: "update", status: input.status },
confidence: "derived",
authority: "analyst-inference",
evidenceLinks: unknownEvidenceLinks(input),
limitations: [
"Registry mutation evidence records analyst intent, not proof of the answer.",
],
});
const updated = this.#evidence.updateUnknown(input, evidence);
const updated = this.#records.updateUnknown(input, target);
if (updated.ok) this.#emitSnapshotChanged();
return updated;
}
@@ -254,7 +234,7 @@ export abstract class BinarySessionRecords {
readonly domain?: string;
} = {},
): ResidualUnknown[] {
return this.#evidence.listUnknowns(filters);
return this.#records.listUnknowns(filters);
}
verifyUnknownResolution(unknownId: string): Result<
@@ -265,6 +245,6 @@ export abstract class BinarySessionRecords {
},
UnknownRegistryError
> {
return this.#evidence.verifyUnknownResolution(unknownId);
return this.#records.verifyUnknownResolution(unknownId);
}
}
@@ -0,0 +1,67 @@
import type { Evidence } from "../../domain/evidence.js";
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import type {
RecordUnknownInput,
ResidualUnknown,
UnknownStatus,
UpdateUnknownInput,
} from "../../domain/residualUnknown.js";
import type { Result } from "../../domain/result.js";
/** Detached investigation Evidence reads without target execution or lifecycle authority. */
export interface EvidenceReader {
hasEvidence(evidenceId: string): boolean;
evidenceById(evidenceId: string): Evidence | undefined;
exportEvidenceBundle(): EvidenceBundle;
}
/** Idempotent investigation Evidence writes without target execution. */
export interface EvidenceWriter {
recordEvidence(
evidence: Evidence,
): Result<"added" | "duplicate", EvidenceIntegrityError>;
}
/** Atomic derived Evidence and linked Unknown writes. */
export interface EvidenceUnknownWriter {
recordEvidenceWithUnknown(
evidence: Evidence,
input: RecordUnknownInput,
): Result<ResidualUnknown | null, AnalysisError>;
}
/** Optimistic Unknown revisions and consistency verification. */
export interface UnknownRegistryPort {
recordUnknown(
input: RecordUnknownInput,
): Result<ResidualUnknown, AnalysisError>;
updateUnknown(
input: UpdateUnknownInput,
): Result<ResidualUnknown, AnalysisError>;
listUnknowns(filters?: {
readonly status?: UnknownStatus;
readonly severity?: ResidualUnknown["severity"];
readonly domain?: string;
}): ResidualUnknown[];
verifyUnknownResolution(unknownId: string): Result<
{
readonly valid: boolean;
readonly truthVerified: boolean;
readonly unknown: ResidualUnknown;
},
UnknownRegistryError
>;
}
/** Compatibility record surface; binary execution and snapshots remain separate. */
export interface InvestigationRecordPort
extends
EvidenceReader,
EvidenceWriter,
EvidenceUnknownWriter,
UnknownRegistryPort {
importEvidenceBundle(bundle: unknown): Result<number, EvidenceIntegrityError>;
}
@@ -0,0 +1,145 @@
import { describe, expect, it } from "vitest";
import {
ANALYSIS_SNAPSHOT_TARGET as target,
ANALYSIS_SNAPSHOT_PROVIDER as provider,
} from "../../domain/analysisSnapshot.fixture.js";
import { createEvidence } from "../../domain/evidence.js";
import { createEvidenceBundle } from "../../domain/evidenceBundle.js";
import {
recordUnknownInputSchema,
updateUnknownInputSchema,
} from "../../domain/residualUnknown.js";
import { unknownMutationEvidence } from "../UnknownEvidence.js";
import { InvestigationRecords } from "./InvestigationRecords.js";
const unknownInput = (question: string) =>
recordUnknownInputSchema.parse({
question,
severity: "medium",
domain: "investigation",
required_authority: "analyst-inference",
required_confidence: "derived",
required_environment: null,
recommended_probes: [],
relationships: [],
});
const evidence = createEvidence(undefined, provider, {
operation: "inspect-fixture",
parameters: {},
result: true,
confidence: "derived",
authority: "analyst-inference",
});
describe("investigation record ownership", () => {
it("keeps identity, detached reads and independent stores without a binary target", () => {
const records = new InvestigationRecords();
expect(records.recordEvidence(evidence)).toEqual({
ok: true,
value: "added",
});
expect(records.recordEvidence(evidence)).toEqual({
ok: true,
value: "duplicate",
});
const read = records.evidenceById(evidence.evidence_id);
if (read === undefined) throw new Error("Missing recorded Evidence");
Reflect.set(read, "operation", "forged");
expect(records.evidenceById(evidence.evidence_id)).toEqual(evidence);
expect(new InvestigationRecords().hasEvidence(evidence.evidence_id)).toBe(
false,
);
});
it("preserves explicit Unknown subjects and target-free atomic mutation subjects", () => {
const records = new InvestigationRecords();
const input = unknownInput("Which target supplies this observation?");
const bound = records.recordUnknown(input, target);
expect(bound).toMatchObject({
ok: true,
value: {
scope_digest: target.sha256,
mutation_evidence_ids: [
unknownMutationEvidence(target, input).evidence_id,
],
},
});
const independent = records.recordEvidenceWithUnknown(evidence, input);
expect(independent).toMatchObject({
ok: true,
value: {
scope_digest: null,
mutation_evidence_ids: [
unknownMutationEvidence(undefined, input).evidence_id,
],
},
});
const mutation = records.evidenceById(
unknownMutationEvidence(undefined, input).evidence_id,
);
expect(mutation?.subject).toBeNull();
expect(records.listUnknowns()).toHaveLength(2);
});
it("rolls back Evidence when the linked Unknown fails validation", () => {
const records = new InvestigationRecords();
const invalid = {
...unknownInput("Is the missing Evidence present?"),
supporting_evidence_ids: [`ev_${"f".repeat(64)}`],
};
expect(records.recordEvidenceWithUnknown(evidence, invalid).ok).toBe(false);
expect(records.hasEvidence(evidence.evidence_id)).toBe(false);
expect(records.exportEvidenceBundle()).toEqual(createEvidenceBundle([]));
});
it("preserves optimistic revisions and the explicit update subject", () => {
const records = new InvestigationRecords();
const created = records.recordUnknown(
unknownInput("Can this revision be updated?"),
target,
);
if (!created.ok) throw created.error;
const input = updateUnknownInputSchema.parse({
...created.value,
expected_revision: created.value.revision,
status: "investigating",
});
const updated = records.updateUnknown(input, target);
expect(updated).toMatchObject({
ok: true,
value: { revision: 2, scope_digest: target.sha256 },
});
const bundle = records.exportEvidenceBundle();
expect(
bundle.records.find(({ operation }) => operation === "update_unknown")
?.subject?.digest.sha256,
).toBe(target.sha256);
expect(records.updateUnknown(input, target).ok).toBe(false);
expect(records.exportEvidenceBundle()).toEqual(bundle);
});
it("reports Unknown-only bundle changes and clears the single record owner", () => {
const source = new InvestigationRecords();
expect(
source.recordUnknown(
unknownInput("Can imported Unknowns notify observers?"),
).ok,
).toBe(true);
const bundle = source.exportEvidenceBundle();
const records = new InvestigationRecords();
expect(
records.mergeEvidenceBundle(createEvidenceBundle(bundle.records)).ok,
).toBe(true);
expect(records.mergeEvidenceBundle(bundle)).toEqual({
ok: true,
value: { recordsAdded: 0, unknownsAdded: 1, changed: true },
});
expect(records.mergeEvidenceBundle(bundle)).toEqual({
ok: true,
value: { recordsAdded: 0, unknownsAdded: 0, changed: false },
});
records.clear();
expect(records.exportEvidenceBundle()).toEqual(createEvidenceBundle([]));
});
});
@@ -0,0 +1,142 @@
import type { BinaryTarget } from "../../domain/binaryTarget.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import type {
RecordUnknownInput,
ResidualUnknown,
UnknownStatus,
UpdateUnknownInput,
} from "../../domain/residualUnknown.js";
import type { Result } from "../../domain/result.js";
import { EvidenceLedger, type EvidenceImportDelta } from "../EvidenceLedger.js";
import {
UNKNOWN_REGISTRY_PROVIDER,
unknownEvidenceLinks,
unknownMutationEvidence,
} from "../UnknownEvidence.js";
import type {
EvidenceReader,
EvidenceWriter,
EvidenceUnknownWriter,
UnknownRegistryPort,
} from "./InvestigationRecordPort.js";
/** One investigation's validated record owner, independent of binary execution. */
export class InvestigationRecords
implements
EvidenceReader,
EvidenceWriter,
EvidenceUnknownWriter,
UnknownRegistryPort
{
readonly #evidence = new EvidenceLedger();
/** Record immutable Evidence idempotently; reject conflicting content. */
recordEvidence(
evidence: Evidence,
): Result<"added" | "duplicate", EvidenceIntegrityError> {
return this.#evidence.record(evidence);
}
/** Check one semantic Evidence ID without exposing stored values. */
hasEvidence(evidenceId: string): boolean {
return this.#evidence.has(evidenceId);
}
/** Return a detached Evidence value for one semantic ID. */
evidenceById(evidenceId: string): Evidence | undefined {
return this.#evidence.get(evidenceId);
}
/** Export a detached deterministic bundle of Evidence and Unknown revisions. */
exportEvidenceBundle(): EvidenceBundle {
return this.#evidence.export();
}
/** Atomically merge a bundle and report changes for the owner's post-commit observers. */
mergeEvidenceBundle(
bundle: unknown,
): Result<EvidenceImportDelta, EvidenceIntegrityError> {
return this.#evidence.import(bundle);
}
/** Clear records when the owning runtime applies its existing lifecycle policy. */
clear(): void {
this.#evidence.clear();
}
/** Record an Unknown with an explicitly supplied Evidence subject, if any. */
recordUnknown(
input: RecordUnknownInput,
target?: BinaryTarget,
): Result<ResidualUnknown, AnalysisError> {
const recorded = this.#evidence.recordUnknown(
input,
unknownMutationEvidence(target, input),
);
return recorded;
}
/** Commit derived Evidence and its Unknown atomically without an implicit subject. */
recordEvidenceWithUnknown(
evidence: Evidence,
input: RecordUnknownInput,
): Result<ResidualUnknown | null, AnalysisError> {
const recorded = this.#evidence.recordWithUnknown(
evidence,
input,
unknownMutationEvidence(undefined, input),
);
return recorded;
}
/** Update an optimistic revision with an explicitly supplied Evidence subject. */
updateUnknown(
input: UpdateUnknownInput,
target?: BinaryTarget,
): Result<ResidualUnknown, AnalysisError> {
const evidence = createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
predicateType: "rea.residual-unknown-mutation",
operation: "update_unknown",
parameters: {
unknown_id: input.unknown_id,
expected_revision: input.expected_revision,
},
result: { action: "update", status: input.status },
confidence: "derived",
authority: "analyst-inference",
evidenceLinks: unknownEvidenceLinks(input),
limitations: [
"Registry mutation evidence records analyst intent, not proof of the answer.",
],
});
const updated = this.#evidence.updateUnknown(input, evidence);
return updated;
}
/** Return detached current Unknown revisions matching the selected filters. */
listUnknowns(
filters: {
readonly status?: UnknownStatus;
readonly severity?: ResidualUnknown["severity"];
readonly domain?: string;
} = {},
): ResidualUnknown[] {
return this.#evidence.listUnknowns(filters);
}
/** Verify registry consistency without asserting the answer is true. */
verifyUnknownResolution(unknownId: string): Result<
{
readonly valid: boolean;
readonly truthVerified: boolean;
readonly unknown: ResidualUnknown;
},
UnknownRegistryError
> {
return this.#evidence.verifyUnknownResolution(unknownId);
}
}
+2 -1
View File
@@ -1,3 +1,4 @@
import type { EvidenceReader } from "../application/investigation/InvestigationRecordPort.js";
import { z } from "zod";
import { uniqueSorted } from "../domain/canonicalOrdering.js";
@@ -138,7 +139,7 @@ const evidenceCandidates = (
};
type LedgerEvidence = ReturnType<
BinarySessionPort["exportEvidenceBundle"]
EvidenceReader["exportEvidenceBundle"]
>["records"][number];
const evidenceValues = (
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { ToolContract } from "../contracts/toolContractTypes.js";
import type { AndroidOperation } from "../domain/androidAnalysis.js";
@@ -14,7 +14,7 @@ export const registerAndroidTools = (
server: McpServer,
service: AndroidAnalysisService,
logger: Logger,
recordEvidence?: BinarySessionPort["recordEvidence"],
recordEvidence?: EvidenceWriter["recordEvidence"],
): void => {
const handler = (contract: ToolContract<AndroidOperation>) => {
const name = contract.name;
+8 -4
View File
@@ -1,12 +1,16 @@
import type { BinarySessionPort } from "../../application/BinarySession.js";
import type {
EvidenceWriter,
EvidenceReader,
EvidenceUnknownWriter,
} from "../../application/investigation/InvestigationRecordPort.js";
import type { Logger } from "../../logger.js";
/** Shared services for registering JavaScript application graph workflows. */
export interface ApplicationToolRegistration {
readonly logger: Logger;
readonly evidenceById: BinarySessionPort["evidenceById"] | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly evidenceById: EvidenceReader["evidenceById"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| EvidenceUnknownWriter["recordEvidenceWithUnknown"]
| undefined;
}
+2 -2
View File
@@ -1,7 +1,7 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
@@ -15,7 +15,7 @@ export const registerArtifactTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
import { captureBrowserScenario } from "../application/BrowserScenarioCaptureService.js";
import { BROWSER_SCENARIO_TOOL_CONTRACTS } from "../contracts/browserScenarioToolContracts.js";
@@ -19,7 +19,7 @@ interface BrowserScenarioToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly provider: BrowserScenarioCapturePort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register the browser scenario tool with execution-time provider diagnostics. */
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import {
analyzeWebBundle,
@@ -35,7 +35,7 @@ interface BrowserToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly browser: BrowserObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
interface BrowserToolContext {
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
import { captureElectronScenario } from "../application/ElectronActiveObservationService.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
@@ -34,7 +34,7 @@ interface ElectronToolRegistration {
readonly activeLoadFailure?: OptionalProviderLoadFailure | undefined;
readonly electron: ElectronObservationPort | undefined;
readonly electronActive: ElectronActiveObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
interface ElectronToolContext {
+8 -5
View File
@@ -1,3 +1,7 @@
import type {
EvidenceWriter,
UnknownRegistryPort,
} from "../application/investigation/InvestigationRecordPort.js";
import type {
CallToolResult,
McpServer,
@@ -5,7 +9,6 @@ import type {
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
EnhancedTools,
type ValidatedEnhancedCall,
@@ -34,8 +37,8 @@ export interface EnhancedToolRegistration {
readonly analysisProfile:
| (() => AnalysisProfileCommitment | undefined)
| undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
}
/** Register composed workflows against the same port as direct bridge tools. */
@@ -319,7 +322,7 @@ interface WorkflowUnknownInput {
readonly name: string;
readonly result: JsonValue;
readonly evidenceId: string;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
}
const recordWorkflowUnknowns = ({
@@ -328,7 +331,7 @@ const recordWorkflowUnknowns = ({
evidenceId,
recordUnknown,
}: WorkflowUnknownInput):
| ReturnType<BinarySessionPort["recordUnknown"]>
| ReturnType<UnknownRegistryPort["recordUnknown"]>
| { readonly ok: true; readonly value: null } => {
if (
!["trace_feature", "trace_call_path", "inspect_native_api"].includes(
+2 -2
View File
@@ -1,10 +1,10 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type {
AnalysisOperation,
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
@@ -19,7 +19,7 @@ import { createArtifactExtractionDestination } from "../application/ArtifactExtr
interface EvidenceToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly sourceEvidence?: (
operation: Exclude<AnalysisOperation, "health">,
result: import("../domain/jsonValue.js").JsonValue,
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { ToolContract } from "../contracts/toolContractTypes.js";
import type { FirmwareOperation } from "../domain/firmwareAnalysis.js";
@@ -14,7 +14,7 @@ export const registerFirmwareTools = (
server: McpServer,
service: FirmwareAnalysisService,
logger: Logger,
recordEvidence?: BinarySessionPort["recordEvidence"],
recordEvidence?: EvidenceWriter["recordEvidence"],
): void => {
const handler =
(contract: ToolContract<FirmwareOperation>) =>
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
import {
listJavaScriptRuntimeTargets,
@@ -26,7 +26,7 @@ interface RuntimeToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly runtime: JavaScriptRuntimeObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register passive Inspector tools even when policy keeps them unavailable. */
+2 -1
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
@@ -18,7 +19,7 @@ export const registerManagedTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly session: BinarySessionPort | undefined;
},
): void => {
@@ -1,12 +1,16 @@
import type {
EvidenceWriter,
EvidenceUnknownWriter,
} from "../../application/investigation/InvestigationRecordPort.js";
import type { BinarySessionPort } from "../../application/BinarySession.js";
import type { Logger } from "../../logger.js";
/** Shared services for registering managed-code workflow tools. */
export interface ManagedWorkflowToolRegistration {
readonly logger: Logger;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| EvidenceUnknownWriter["recordEvidenceWithUnknown"]
| undefined;
readonly session: BinarySessionPort;
}
+2 -2
View File
@@ -1,7 +1,7 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { NATIVE_TOOL_CONTRACTS } from "../contracts/nativeToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
@@ -14,7 +14,7 @@ export const registerNativeTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
registerEvidenceTools(server, analysis, NATIVE_TOOL_CONTRACTS, options);
+3 -3
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import { z } from "zod";
@@ -5,7 +6,6 @@ import type {
AnalysisExecution,
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/officialToolContracts.js";
@@ -28,7 +28,7 @@ import { toCallToolResult } from "./toolResult.js";
export interface OfficialToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
@@ -53,7 +53,7 @@ const registerOfficialTool = (
registration: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
server.registerTool(
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { exportWebScriptsValidated } from "../application/WebScriptExportService.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { Logger } from "../logger.js";
@@ -13,7 +13,7 @@ export const registerWebScriptTool = (
server: McpServer,
options: {
readonly logger: Logger;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
const contract = toolContract("export_web_scripts");
+2 -2
View File
@@ -1,11 +1,11 @@
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
import type { Evidence } from "../domain/evidence.js";
import { ok, type Result } from "../domain/result.js";
/** Record source evidence in order, stopping at the first session rejection. */
export const recordSessionEvidenceSources = (
recordEvidence: BinarySessionPort["recordEvidence"] | undefined,
recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
sources: readonly Evidence[],
): Result<null, EvidenceIntegrityError> => {
for (const source of sources) {
@@ -0,0 +1,149 @@
import { expect, it, onTestFinished } from "vitest";
import { BinarySession } from "../../../src/application/BinarySession.js";
import { SessionProviderRouter } from "../../../src/application/SessionProviderRouter.js";
import { InvestigationRecords } from "../../../src/application/investigation/InvestigationRecords.js";
import { createEvidence } from "../../../src/domain/evidence.js";
import { recordUnknownInputSchema } from "../../../src/domain/residualUnknown.js";
import {
createBinarySessionTargets,
createCacheProvider,
createTestBinarySession,
} from "../../fixtures/binarySession.js";
const createSession = (
records: InvestigationRecords = new InvestigationRecords(),
) => {
const session = new BinarySession(
SessionProviderRouter.single(createCacheProvider([])),
records,
);
onTestFinished(async () => {
await session.close();
});
return session;
};
it("uses the composed record owner and preserves best-effort post-commit notifications", async () => {
const records = new InvestigationRecords();
const session = createSession(records);
const observed: number[] = [];
const unsubscribe = session.onAnalysisSnapshotChanged(() => {
observed.push(records.exportEvidenceBundle().records.length);
});
session.onAnalysisSnapshotChanged(() => {
throw new Error("Synthetic observer failure");
});
session.onAnalysisSnapshotChanged(async () => {
throw new Error("Synthetic async observer failure");
});
const evidence = createEvidence(
undefined,
{ id: "fixture", name: "Fixture", version: "1" },
{ operation: "independent-app", parameters: {}, result: true },
);
expect(session.recordEvidence(evidence)).toEqual({
ok: true,
value: "added",
});
expect(records.evidenceById(evidence.evidence_id)).toEqual(evidence);
expect(session.recordEvidence(evidence)).toEqual({
ok: true,
value: "duplicate",
});
expect(observed).toEqual([1]);
expect((await session.close()).ok).toBe(true);
expect(records.exportEvidenceBundle().records).toEqual([]);
expect(session.exportAnalysisSnapshot()).toMatchObject({
ok: false,
error: { _tag: "NoBinaryOpenError" },
});
expect(observed).toEqual([1, 0]);
unsubscribe();
await new Promise<void>((resolve) => setImmediate(resolve));
});
it("notifies after snapshot and Evidence import both commit, and rejects mismatched targets atomically", async () => {
const [first, second] = await createBinarySessionTargets();
const source = createTestBinarySession(createCacheProvider([]));
onTestFinished(async () => {
await source.close();
});
expect((await source.open(first)).ok).toBe(true);
expect(
(
await source.execute("address_name", {
address: "0x1000",
document: "fixture",
})
).ok,
).toBe(true);
const exported = source.exportAnalysisSnapshot();
if (!exported.ok) throw exported.error;
expect(exported.value.entries.length).toBeGreaterThan(0);
const recipient = createSession();
expect((await recipient.open(first)).ok).toBe(true);
const notifications: Array<{ entries: number; evidence: number }> = [];
recipient.onAnalysisSnapshotChanged(() => {
const snapshot = recipient.exportAnalysisSnapshot();
if (!snapshot.ok) throw snapshot.error;
notifications.push({
entries: snapshot.value.entries.length,
evidence: snapshot.value.evidence_bundle.records.length,
});
});
expect(recipient.importAnalysisSnapshot(exported.value).ok).toBe(true);
expect(notifications).toEqual([
{
entries: exported.value.entries.length,
evidence: exported.value.evidence_bundle.records.length,
},
]);
const incompatible = createSession();
expect((await incompatible.open(second)).ok).toBe(true);
let mismatchNotifications = 0;
incompatible.onAnalysisSnapshotChanged(() => {
mismatchNotifications += 1;
});
const before = incompatible.exportEvidenceBundle();
expect(incompatible.importAnalysisSnapshot(exported.value).ok).toBe(false);
expect(incompatible.exportEvidenceBundle()).toEqual(before);
expect(mismatchNotifications).toBe(0);
});
it("notifies an Unknown-only bundle change even when no new Evidence is added", () => {
const source = createSession();
expect(
source.recordUnknown(
recordUnknownInputSchema.parse({
question: "Is this import complete?",
severity: "medium",
domain: "investigation",
required_authority: "analyst-inference",
required_confidence: "derived",
required_environment: null,
recommended_probes: [],
relationships: [],
}),
).ok,
).toBe(true);
const bundle = source.exportEvidenceBundle();
const recipient = createSession();
expect(recipient.importEvidenceBundle({ ...bundle, unknowns: [] }).ok).toBe(
true,
);
const revisions: number[] = [];
recipient.onAnalysisSnapshotChanged(() => {
revisions.push(recipient.listUnknowns().length);
});
expect(recipient.importEvidenceBundle(bundle)).toEqual({
ok: true,
value: 0,
});
expect(revisions).toEqual([1]);
expect(recipient.importEvidenceBundle(bundle)).toEqual({
ok: true,
value: 0,
});
expect(revisions).toEqual([1]);
});