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
+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);
}
}