rea-agents 2.0.0 → 2.2.0

package/dist/application/BinarySession.js

@@ -1,18 +1,13 @@
-import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { analysisProfilesEqual, } from "../domain/analysisProfile.js";
-import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, ProviderAdapterError, } from "../domain/errors.js";
+import { AnalysisCancelledError, ProviderAdapterError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
-import { createEvidence } from "../domain/evidence.js";
-import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
-import { EvidenceLedger } from "./EvidenceLedger.js";
-import { UnknownRegistryError } from "../domain/errors.js";
 import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
-import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
-import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
-import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 import { SessionProviderRouter, } from "./SessionProviderRouter.js";
+import { BinarySessionRecords } from "./BinarySessionRecords.js";
+import { binarySessionStatus } from "./BinarySessionStatus.js";
+import { resolveSessionOpen, } from "./BinarySessionOpen.js";
+import { prepareSessionExecution } from "./BinarySessionExecution.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
@@ -21,22 +16,16 @@ const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => na
  * active provider client. A failed switch recreates the previous target instead
  * of retaining a client whose resources were already shut down.
  */
-export class BinarySession {
+export class BinarySession extends BinarySessionRecords {
     provider;
     #active;
     #transition = Promise.resolve();
     #calls = new Set();
     #providerRouter;
-    #evidence = new EvidenceLedger({
-        maxRecords: 10_000,
-        maxBytes: 64 * 1024 * 1024,
-    });
-    #snapshot = new AnalysisSnapshotCache();
-    #investigationWorkspaces = new Map();
     #runtimeAvailability = new Map();
     #availabilityListeners = new Set();
-    #snapshotInvalidated = false;
     constructor(provider, options = {}) {
+        super();
         this.provider = provider;
         this.#providerRouter =
             provider instanceof SessionProviderRouter
@@ -90,104 +79,6 @@ export class BinarySession {
         this.#availabilityListeners.add(listener);
         return () => this.#availabilityListeners.delete(listener);
     }
-    /** Add one successful public observation to the session ledger. */
-    recordEvidence(evidence) {
-        return this.#evidence.record(evidence);
-    }
-    /** Check that comparison input Evidence is already session-owned. */
-    hasEvidence(evidenceId) {
-        return this.#evidence.has(evidenceId);
-    }
-    /** Read one detached session-owned Evidence record by semantic ID. */
-    evidenceById(evidenceId) {
-        return this.#evidence.get(evidenceId);
-    }
-    /** Return a deterministic snapshot without clearing session evidence. */
-    exportEvidenceBundle() {
-        return this.#evidence.export();
-    }
-    /** Atomically merge a validated evidence bundle into this session. */
-    importEvidenceBundle(bundle) {
-        return this.#evidence.import(bundle);
-    }
-    /** Export immutable cached calls and session evidence for the active target. */
-    exportAnalysisSnapshot() {
-        if (this.#snapshotInvalidated)
-            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations"));
-        const target = this.#active?.target;
-        const profile = this.#active?.profile ?? undefined;
-        if (target !== undefined && profile === undefined)
-            return err(new EvidenceIntegrityError("Analysis snapshots require a concrete provider analysis profile"));
-        return this.#snapshot.export(target, profile, target === undefined
-            ? this.#evidence.export()
-            : evidenceBundleForTarget(this.#evidence.export(), target.sha256));
-    }
-    /** Stage validated cached calls for an identical binary and merge its evidence. */
-    importAnalysisSnapshot(snapshot) {
-        const active = this.#active;
-        if (active?.profile === null)
-            return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
-        return this.#snapshot.import(snapshot, active === undefined
-            ? undefined
-            : { target: active.target, profile: active.profile }, (bundle) => this.#evidence.import(bundle));
-    }
-    /** Retain one validated immutable workspace revision for session resources. */
-    retainInvestigationWorkspace(workspace) {
-        const parsed = parseInvestigationWorkspace(workspace);
-        const key = `${parsed.workspace_id}:${String(parsed.revision)}`;
-        if (this.#investigationWorkspaces.has(key))
-            return "duplicate";
-        this.#investigationWorkspaces.set(key, parsed);
-        return "added";
-    }
-    /** Read one session-retained immutable workspace revision. */
-    investigationWorkspace(workspaceId, revision) {
-        const workspace = this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
-        return workspace === undefined ? undefined : structuredClone(workspace);
-    }
-    /** List retained workspace revisions in canonical identity order. */
-    investigationWorkspaces() {
-        return [...this.#investigationWorkspaces.values()]
-            .sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
-            left.revision - right.revision)
-            .map((workspace) => structuredClone(workspace));
-    }
-    /** Create an approved residual unknown and immutable mutation evidence. */
-    recordUnknown(input) {
-        const evidence = unknownMutationEvidence(this.#active?.target, input);
-        return this.#evidence.recordUnknown(input, evidence);
-    }
-    /** Atomically record derived Evidence and its approved residual unknown. */
-    recordEvidenceWithUnknown(evidence, input) {
-        return this.#evidence.recordWithUnknown(evidence, input, unknownMutationEvidence(undefined, input));
-    }
-    /** Update one unknown using compare-and-swap revision semantics. */
-    updateUnknown(input) {
-        const evidence = createEvidence(this.#active?.target, UNKNOWN_REGISTRY_PROVIDER, {
-            predicateType: "rea.residual-unknown-mutation/v1",
-            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.",
-            ],
-        });
-        return this.#evidence.updateUnknown(input, evidence);
-    }
-    /** Query stable current residual-unknown heads. */
-    listUnknowns(filters = {}) {
-        return this.#evidence.listUnknowns(filters);
-    }
-    /** Check whether current head is a bundle-valid resolved state. */
-    verifyUnknownResolution(unknownId) {
-        return this.#evidence.verifyUnknownResolution(unknownId);
-    }
     /**
      * Open or switch targets after draining calls against the current target.
      * Returns the switch failure even if best-effort restoration also fails.
@@ -196,27 +87,17 @@ export class BinarySession {
         return this.#serialize(async () => {
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
-            if (!parsed.ok)
-                return parsed;
-            const sameTarget = this.#active?.target.path === parsed.value.path &&
-                snapshotMatchesTarget(snapshotTarget(this.#active.target), parsed.value);
-            const resolvedRoute = sameTarget &&
-                options.providerId === undefined &&
-                this.#active !== undefined
-                ? ok(this.#active.route)
-                : await this.#providerRouter.resolve(parsed.value, options.providerId, options.signal);
-            if (!resolvedRoute.ok)
-                return resolvedRoute;
-            const route = resolvedRoute.value;
+            const resolved = await resolveSessionOpen({
+                router: this.#providerRouter,
+                current: this.#active,
+                path,
+                options,
+                stagedSnapshotMatches: (target, profile) => this.matchesSnapshot(target, profile),
+            });
+            if (!resolved.ok)
+                return resolved;
+            const { target, route, sameTarget } = resolved.value;
             const { profile, compatibility } = route;
-            if (options.snapshot !== undefined &&
-                (profile === null ||
-                    !snapshotMatchesBinding(options.snapshot, parsed.value, profile)))
-                return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the requested binary"));
-            if (this.#active === undefined &&
-                !this.#snapshot.matches(parsed.value, profile ?? undefined))
-                return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: staged target, provider, or analysis profile does not match"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
             const activeProfile = this.#active?.profile;
@@ -229,13 +110,13 @@ export class BinarySession {
                     if (!imported.ok)
                         return imported;
                 }
-                return ok(parsed.value);
+                return ok(target);
             }
             await this.#drainCalls();
             const previous = this.#active;
             this.#active = undefined;
             await previous?.client.close();
-            const client = route.createClient(parsed.value);
+            const client = route.createClient(target);
             const started = await client.execute("health", {}, options);
             if (!started.ok) {
                 await client.close();
@@ -248,7 +129,7 @@ export class BinarySession {
                 return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = {
-                target: parsed.value,
+                target,
                 client,
                 profile,
                 compatibility: structuredClone(compatibility),
@@ -256,9 +137,9 @@ export class BinarySession {
             };
             this.#clearRuntimeAvailability();
             if (profile === null)
-                this.#snapshot.clear();
+                this.clearSnapshot();
             else
-                this.#snapshot.select(parsed.value, profile);
+                this.selectSnapshot(target, profile);
             if (options.snapshot !== undefined) {
                 const imported = this.importAnalysisSnapshot(options.snapshot);
                 if (!imported.ok) {
@@ -268,8 +149,8 @@ export class BinarySession {
                     return imported;
                 }
             }
-            this.#snapshotInvalidated = false;
-            return ok(parsed.value);
+            this.resetSnapshotInvalidation();
+            return ok(target);
         });
     }
     /** Close the active target, if any. */
@@ -279,90 +160,19 @@ export class BinarySession {
             this.#active = undefined;
             await this.#drainCalls();
             await previous?.client.close();
-            this.#evidence.clear();
-            this.#snapshot.clear();
-            this.#snapshotInvalidated = false;
+            this.clearSessionRecords();
             this.#clearRuntimeAvailability();
             return ok(null);
         });
     }
     /** Describe the active binary session. */
     status() {
-        const target = this.#active?.target;
-        const route = this.#currentRoute();
-        const configuredProvider = this.#providerRouter.configuredIdentity();
-        const provider = {
-            id: configuredProvider.id,
-            name: configuredProvider.name,
-            version: configuredProvider.version,
-        };
-        const providerList = this.#providerRouter
-            .providerIdentities(route)
-            .map(({ id, name, version }) => ({ id, name, version }));
-        const capabilities = route.capabilities === undefined
-            ? []
-            : [...route.capabilities.values()]
-                .sort((left, right) => left.operation.localeCompare(right.operation))
-                .map((descriptor) => ({
-                ...descriptor,
-                ...this.#runtimeAvailability.get(descriptor.operation),
-            }))
-                .map((descriptor) => capabilityStatus(descriptor));
-        const analysisProviderBinding = route.binding === null
-            ? null
-            : {
-                provider: {
-                    id: route.binding.identity.id,
-                    name: route.binding.identity.name,
-                    version: route.binding.identity.version,
-                },
-                selection_source: route.binding.selectionSource,
-                analysis_profile: structuredClone(route.binding.profile),
-            };
-        const analysisProviderCandidates = this.#providerRouter
-            .candidateStatuses(route)
-            .map((candidate) => ({
-            provider: {
-                id: candidate.provider.id,
-                name: candidate.provider.name,
-                version: candidate.provider.version,
-            },
-            availability: {
-                status: candidate.availability.status,
-                code: candidate.availability.code,
-                reason: candidate.availability.reason,
-                diagnostics: structuredClone(candidate.availability.diagnostics),
-            },
-            target_support: {
-                status: candidate.targetSupport.status,
-                code: candidate.targetSupport.code,
-                reason: candidate.targetSupport.reason,
-                diagnostics: structuredClone(candidate.targetSupport.diagnostics),
-            },
-            selected: candidate.selected,
-            capabilities: candidate.capabilities
-                .slice()
-                .sort((left, right) => left.operation.localeCompare(right.operation))
-                .map((descriptor) => capabilityStatus(descriptor)),
-        }));
-        const common = {
-            provider,
-            providers: providerList,
-            capabilities,
-            analysis_provider_binding: analysisProviderBinding,
-            analysis_provider_candidates: analysisProviderCandidates,
-        };
-        return target === undefined
-            ? { open: false, ...common }
-            : {
-                open: true,
-                ...common,
-                path: target.path,
-                sha256: target.sha256,
-                format: target.format,
-                kind: target.kind,
-                architecture: target.architecture ?? null,
-            };
+        return binarySessionStatus({
+            target: this.#active?.target,
+            route: this.#currentRoute(),
+            router: this.#providerRouter,
+            runtimeAvailability: this.#runtimeAvailability,
+        });
     }
     /** Return the immutable artifact identity captured before its provider started. */
     activeTarget() {
@@ -370,6 +180,9 @@ export class BinarySession {
             ? undefined
             : structuredClone(this.#active.target);
     }
+    activeAnalysisBinding() {
+        return this.#active;
+    }
     /**
      * Invoke a provider operation against the active target.
      * Calls may overlap, but a pending target transition prevents new calls from
@@ -379,27 +192,16 @@ export class BinarySession {
         const transitioned = await this.#waitForTransition(name, options?.signal);
         if (!transitioned.ok)
             return transitioned;
-        const active = this.#active;
-        if (active === undefined)
-            return err(new NoBinaryOpenError());
-        const capability = active.route.capabilities?.get(name);
-        if (active.route.capabilities !== undefined &&
-            capability?.available !== true) {
-            const selectionError = this.#providerRouter.unboundOperationError(name, active.route);
-            if (selectionError !== undefined)
-                return err(selectionError);
-            return err(new AnalysisCapabilityUnavailableError(active.route.binding?.identity.id ?? active.route.identity.id, name, capability?.reason ?? "operation is not declared by this provider"));
-        }
-        const profile = active.profile !== null &&
-            (capability === undefined ||
-                capability.provider.id === active.profile.provider.id)
-            ? active.profile
-            : undefined;
-        const cacheable = profile !== undefined &&
-            isSnapshotCacheable(name, capability, arguments_);
-        const cached = cacheable
-            ? this.#snapshot.lookup(active.target, profile, name, arguments_)
-            : undefined;
+        const prepared = prepareSessionExecution({
+            active: this.#active,
+            operation: name,
+            parameters: arguments_,
+            unboundOperationError: (operation, route) => this.#providerRouter.unboundOperationError(operation, route),
+            lookupSnapshot: (target, profile, operation, parameters) => this.lookupSnapshot(target, profile, operation, parameters),
+        });
+        if (!prepared.ok)
+            return prepared;
+        const { active, capability, profile, cacheable, cached } = prepared.value;
         if (cached !== undefined)
             return ok(cached);
         const call = active.client.execute(name, arguments_, options);
@@ -408,8 +210,8 @@ export class BinarySession {
             const result = await call;
             const profiled = commitExecutionProfile(name, result, profile);
             this.#observeRuntimeAvailability(name, profiled);
-            if (profiled.ok && cacheable)
-                this.#snapshot.record({
+            if (profiled.ok && cacheable && profile !== undefined)
+                this.recordSnapshot({
                     target: active.target,
                     profile,
                     operation: name,
@@ -417,8 +219,7 @@ export class BinarySession {
                     execution: profiled.value,
                 });
             else if (profiled.ok && capability?.effects.mutatesArtifact === true) {
-                this.#snapshot.clear();
-                this.#snapshotInvalidated = true;
+                this.invalidateSnapshot();
             }
             return profiled;
         }
@@ -552,27 +353,3 @@ const commitExecutionProfile = (operation, result, profile) => {
         analysisProfile: structuredClone(profile),
     });
 };
-const capabilityStatus = (descriptor) => ({
-    operation: descriptor.operation,
-    available: descriptor.available,
-    reason: descriptor.reason,
-    input_contract_version: descriptor.inputContractVersion,
-    output_contract_version: descriptor.outputContractVersion,
-    pagination: descriptor.pagination,
-    exhaustive: descriptor.exhaustive,
-    effects: {
-        mutates_artifact: descriptor.effects.mutatesArtifact,
-        launches_process: descriptor.effects.launchesProcess,
-        may_show_ui: descriptor.effects.mayShowUi,
-        may_access_network: descriptor.effects.mayAccessNetwork,
-        may_write_filesystem: descriptor.effects.mayWriteFilesystem,
-        changes_permissions: descriptor.effects.changesPermissions,
-        requires_root: descriptor.effects.requiresRoot,
-    },
-    limits: {
-        max_results: descriptor.limits.maxResults,
-        max_payload_bytes: descriptor.limits.maxPayloadBytes,
-        timeout_ms: descriptor.limits.timeoutMs,
-    },
-    limitations: [...descriptor.limitations],
-});

package/dist/application/BinarySessionExecution.js

@@ -0,0 +1,28 @@
+import { AnalysisCapabilityUnavailableError, NoBinaryOpenError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { isSnapshotCacheable } from "./AnalysisSnapshotCache.js";
+/** Resolve capability, profile, and snapshot state before invoking a provider. */
+export const prepareSessionExecution = (input) => {
+    const { active, operation, parameters, unboundOperationError, lookupSnapshot, } = input;
+    if (active === undefined)
+        return err(new NoBinaryOpenError());
+    const capability = active.route.capabilities?.get(operation);
+    if (active.route.capabilities !== undefined &&
+        capability?.available !== true) {
+        const selectionError = unboundOperationError(operation, active.route);
+        if (selectionError !== undefined)
+            return err(selectionError);
+        return err(new AnalysisCapabilityUnavailableError(active.route.binding?.identity.id ?? active.route.identity.id, operation, capability?.reason ?? "operation is not declared by this provider"));
+    }
+    const profile = active.profile !== null &&
+        (capability === undefined ||
+            capability.provider.id === active.profile.provider.id)
+        ? active.profile
+        : undefined;
+    const cacheable = profile !== undefined &&
+        isSnapshotCacheable(operation, capability, parameters);
+    const cached = cacheable
+        ? lookupSnapshot(active.target, profile, operation, parameters)
+        : undefined;
+    return ok({ active, capability, profile, cacheable, cached });
+};

package/dist/application/BinarySessionOpen.js

@@ -0,0 +1,39 @@
+import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { parseBinaryTarget, } from "../domain/binaryTarget.js";
+import { EvidenceIntegrityError, } from "../domain/errors.js";
+import { err } from "../domain/result.js";
+import { SessionProviderRouter } from "./SessionProviderRouter.js";
+/** Parse a target, resolve its provider route, and validate snapshot binding. */
+export const resolveSessionOpen = async (input) => {
+    const { router, current, path, options, stagedSnapshotMatches } = input;
+    const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
+    if (!parsed.ok)
+        return parsed;
+    const target = parsed.value;
+    const sameTarget = current?.target.path === target.path &&
+        snapshotMatchesTarget(snapshotTarget(current.target), target);
+    const resolvedRoute = sameTarget && options.providerId === undefined && current !== undefined
+        ? { ok: true, value: current.route }
+        : await router.resolve(target, options.providerId, options.signal);
+    if (!resolvedRoute.ok)
+        return resolvedRoute;
+    const route = resolvedRoute.value;
+    const snapshotError = validateSnapshot({
+        snapshot: options.snapshot,
+        target,
+        profile: route.profile,
+        current,
+        stagedSnapshotMatches,
+    });
+    if (snapshotError !== undefined)
+        return err(snapshotError);
+    return { ok: true, value: { target, route, sameTarget } };
+};
+const validateSnapshot = ({ snapshot, target, profile, current, stagedSnapshotMatches, }) => {
+    if (snapshot !== undefined &&
+        (profile === null || !snapshotMatchesBinding(snapshot, target, profile)))
+        return new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the requested binary");
+    if (current === undefined && !stagedSnapshotMatches(target, profile))
+        return new EvidenceIntegrityError("Analysis snapshot profile_mismatch: staged target, provider, or analysis profile does not match");
+    return undefined;
+};

package/dist/application/BinarySessionRecords.js

@@ -0,0 +1,149 @@
+import { createEvidence } from "../domain/evidence.js";
+import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
+import { EvidenceIntegrityError, } from "../domain/errors.js";
+import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
+import { parseReconstructionCoverageWorkspace, } from "../domain/reconstructionCoverage.js";
+import { err } from "../domain/result.js";
+import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
+import { EvidenceLedger } from "./EvidenceLedger.js";
+import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
+/** Owns session evidence, snapshots, workspaces, and residual unknowns. */
+export class BinarySessionRecords {
+    #evidence = new EvidenceLedger({
+        maxRecords: 10_000,
+        maxBytes: 64 * 1024 * 1024,
+    });
+    #snapshot = new AnalysisSnapshotCache();
+    #investigationWorkspaces = new Map();
+    #coverageWorkspaces = new Map();
+    #snapshotInvalidated = false;
+    recordEvidence(evidence) {
+        return this.#evidence.record(evidence);
+    }
+    hasEvidence(evidenceId) {
+        return this.#evidence.has(evidenceId);
+    }
+    evidenceById(evidenceId) {
+        return this.#evidence.get(evidenceId);
+    }
+    exportEvidenceBundle() {
+        return this.#evidence.export();
+    }
+    importEvidenceBundle(bundle) {
+        return this.#evidence.import(bundle);
+    }
+    exportAnalysisSnapshot() {
+        const active = this.activeAnalysisBinding();
+        if (this.#snapshotInvalidated)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations"));
+        const target = active?.target;
+        const profile = active?.profile ?? undefined;
+        if (target !== undefined && profile === undefined)
+            return err(new EvidenceIntegrityError("Analysis snapshots require a concrete provider analysis profile"));
+        return this.#snapshot.export(target, profile, target === undefined
+            ? this.#evidence.export()
+            : evidenceBundleForTarget(this.#evidence.export(), target.sha256));
+    }
+    importAnalysisSnapshot(snapshot) {
+        const active = this.activeAnalysisBinding();
+        if (active?.profile === null)
+            return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
+        return this.#snapshot.import(snapshot, active === undefined
+            ? undefined
+            : { target: active.target, profile: active.profile }, (bundle) => this.#evidence.import(bundle));
+    }
+    matchesSnapshot(target, profile) {
+        return this.#snapshot.matches(target, profile ?? undefined);
+    }
+    selectSnapshot(target, profile) {
+        this.#snapshot.select(target, profile);
+    }
+    lookupSnapshot(target, profile, operation, parameters) {
+        return this.#snapshot.lookup(target, profile, operation, parameters);
+    }
+    recordSnapshot(input) {
+        this.#snapshot.record(input);
+    }
+    invalidateSnapshot() {
+        this.#snapshot.clear();
+        this.#snapshotInvalidated = true;
+    }
+    resetSnapshotInvalidation() {
+        this.#snapshotInvalidated = false;
+    }
+    clearSnapshot() {
+        this.#snapshot.clear();
+    }
+    clearSessionRecords() {
+        this.#evidence.clear();
+        this.#snapshot.clear();
+        this.#snapshotInvalidated = false;
+    }
+    retainInvestigationWorkspace(workspace) {
+        const parsed = parseInvestigationWorkspace(workspace);
+        const key = workspaceKey(parsed.workspace_id, parsed.revision);
+        if (this.#investigationWorkspaces.has(key))
+            return "duplicate";
+        this.#investigationWorkspaces.set(key, parsed);
+        return "added";
+    }
+    investigationWorkspace(workspaceId, revision) {
+        const workspace = this.#investigationWorkspaces.get(workspaceKey(workspaceId, revision));
+        return workspace === undefined ? undefined : structuredClone(workspace);
+    }
+    investigationWorkspaces() {
+        return sortedWorkspaces(this.#investigationWorkspaces.values());
+    }
+    retainReconstructionCoverageWorkspace(workspace) {
+        const parsed = parseReconstructionCoverageWorkspace(workspace);
+        const key = workspaceKey(parsed.workspace_id, parsed.revision);
+        if (this.#coverageWorkspaces.has(key))
+            return "duplicate";
+        this.#coverageWorkspaces.set(key, parsed);
+        return "added";
+    }
+    reconstructionCoverageWorkspace(workspaceId, revision) {
+        const workspace = this.#coverageWorkspaces.get(workspaceKey(workspaceId, revision));
+        return workspace === undefined ? undefined : structuredClone(workspace);
+    }
+    reconstructionCoverageWorkspaces() {
+        return sortedWorkspaces(this.#coverageWorkspaces.values());
+    }
+    recordUnknown(input) {
+        const target = this.activeAnalysisBinding()?.target;
+        return this.#evidence.recordUnknown(input, unknownMutationEvidence(target, input));
+    }
+    recordEvidenceWithUnknown(evidence, input) {
+        return this.#evidence.recordWithUnknown(evidence, input, unknownMutationEvidence(undefined, input));
+    }
+    updateUnknown(input) {
+        const target = this.activeAnalysisBinding()?.target;
+        const evidence = createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
+            predicateType: "rea.residual-unknown-mutation/v1",
+            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.",
+            ],
+        });
+        return this.#evidence.updateUnknown(input, evidence);
+    }
+    listUnknowns(filters = {}) {
+        return this.#evidence.listUnknowns(filters);
+    }
+    verifyUnknownResolution(unknownId) {
+        return this.#evidence.verifyUnknownResolution(unknownId);
+    }
+}
+const workspaceKey = (workspaceId, revision) => `${workspaceId}:${String(revision)}`;
+const sortedWorkspaces = (workspaces) => [...workspaces]
+    .sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
+    left.revision - right.revision)
+    .map((workspace) => structuredClone(workspace));