rea-agents 6.3.0 → 6.5.0

package/dist/application/binary/BinarySession.js

@@ -1,19 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { analysisProfilesEqual, } from "../../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
-import {} from "../../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
 import { err, ok } from "../../domain/result.js";
 import { createEvidence } from "../../domain/evidence.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 import { ENHANCED_TOOL_CONTRACTS } from "../../contracts/enhancedToolContracts.js";
-import { writeAnalysisSnapshot } from "./AnalysisSnapshotFiles.js";
 import { SessionProviderRouter, } from "./SessionProviderRouter.js";
 import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
 import { BinarySessionRecords } from "./BinarySessionRecords.js";
 import { binarySessionStatus } from "./BinarySessionStatus.js";
 import { resolveSessionOpen, resolveSessionTarget, validateResolvedSessionTarget, } from "./BinarySessionOpen.js";
 import { bindExecutionTarget, commitExecutionProfile, prepareSessionExecution, } from "./BinarySessionExecution.js";
-import { analysisErrorWithCleanupFailure, closeAnalysisClient, } from "./AnalysisClientCleanup.js";
+import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 const ENHANCED_OPERATIONS = new Set(ENHANCED_TOOL_CONTRACTS.map(({ name }) => name));
 /**
@@ -25,10 +24,13 @@ const ENHANCED_OPERATIONS = new Set(ENHANCED_TOOL_CONTRACTS.map(({ name }) => na
  */
 export class BinarySession extends BinarySessionRecords {
     #active;
+    #externalMutationCleanupFailure;
     #pendingCleanup;
     #transition = Promise.resolve();
     #transitionGeneration = 0;
+    #transitionPending = 0;
     #calls = new Map();
+    #promptCompletionControllers = new Set();
     #providerRouter;
     #runtimeUnavailability = new Map();
     #availabilityListeners = new Set();
@@ -36,6 +38,27 @@ export class BinarySession extends BinarySessionRecords {
         super(records);
         this.#providerRouter = providerRouter;
     }
+    /**
+     * Fast-path liveness gate (#1719): short-circuit only when the retained
+     * client is genuinely alive. The probe reads the child's operation health
+     * rather than the composite's unconditionally-ok `health`, so a dead child
+     * falls through and a real client is started; an aborted caller leaves the
+     * session untouched. Returns the fast-path result, or undefined to fall
+     * through to the slow path.
+     */
+    async #tryRetainedFastPath(retained, target, options) {
+        const live = await this.#retainedClientLive(retained.client, options);
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        if (!live)
+            return undefined;
+        if (options.snapshot !== undefined) {
+            const imported = this.importAnalysisSnapshot(options.snapshot);
+            if (!imported.ok)
+                return imported;
+        }
+        return ok(target);
+    }
     /** Identify the provider producing evidence for this session. */
     providerIdentity(operation) {
         const route = this.#currentRoute();
@@ -57,12 +80,7 @@ export class BinarySession extends BinarySessionRecords {
                 }
             }
         }
-        const profile = this.#active?.profile;
-        return structuredClone(profile !== null &&
-            profile !== undefined &&
-            profile.provider.id === selected.id
-            ? profile.provider
-            : selected);
+        return structuredClone(selected);
     }
     /** External live state cannot be replayed by a direct or composed CLI workflow. */
     allowsSnapshotReplay(operation) {
@@ -72,6 +90,9 @@ export class BinarySession extends BinarySessionRecords {
             return descriptor.cachePolicy !== "live";
         return ![...(capabilities?.values() ?? [])].some(({ cachePolicy }) => cachePolicy === "live");
     }
+    invalidateSnapshotForExternalMutation() {
+        this.invalidateSnapshot();
+    }
     /** Return the selected immutable profile, optionally scoped to an operation. */
     analysisProfile(operation) {
         const profile = this.#active?.profile;
@@ -124,80 +145,124 @@ export class BinarySession extends BinarySessionRecords {
         })), options);
     }
     #open(resolve, options) {
-        return this.#serialize(async (admittedThrough) => {
-            if (isAborted(options.signal))
-                return err(new AnalysisCancelledError("open_binary"));
-            const resolved = await resolve();
-            if (!resolved.ok)
-                return resolved;
-            const { target, route, sameTarget } = resolved.value;
-            const { profile } = route;
-            if (isAborted(options.signal))
-                return err(new AnalysisCancelledError("open_binary"));
-            const activeProfile = this.#active?.profile;
-            const sameProfile = activeProfile === null || activeProfile === undefined
-                ? profile === null
-                : profile !== null && analysisProfilesEqual(activeProfile, profile);
-            await this.#drainCalls(admittedThrough);
-            if (isAborted(options.signal))
-                return err(new AnalysisCancelledError("open_binary"));
-            const pendingClosed = await this.#retryPendingCleanup();
-            if (!pendingClosed.ok)
-                return pendingClosed;
-            if (isAborted(options.signal))
-                return err(new AnalysisCancelledError("open_binary"));
-            if (sameTarget && sameProfile) {
-                if (options.snapshot !== undefined) {
-                    const imported = this.importAnalysisSnapshot(options.snapshot);
-                    if (!imported.ok)
-                        return imported;
-                }
-                return ok(target);
-            }
-            const previous = this.#active;
-            this.#active = undefined;
-            if (previous !== undefined) {
-                const closed = await this.#retireClient(previous.client, previous.route.identity.id);
-                if (!closed.ok) {
-                    this.clearSessionRecords();
-                    this.#clearRuntimeAvailability();
-                    return closed;
-                }
-            }
-            if (isAborted(options.signal))
-                return err(await this.#restoreAfterFailedOpen(previous, new AnalysisCancelledError("open_binary")));
-            const runId = randomUUID();
-            const client = route.createClient(target, { runId });
-            const started = await client.execute("health", {}, options);
-            if (!started.ok) {
-                return err(await this.#failedOpen(client, route.identity.id, previous, started.error));
-            }
-            if (isAborted(options.signal)) {
-                return err(await this.#failedOpen(client, route.identity.id, previous, new AnalysisCancelledError("open_binary")));
+        return this.#serialize((admittedThrough) => this.#openWithinTransition(admittedThrough, resolve, options));
+    }
+    async #openWithinTransition(admittedThrough, resolve, options) {
+        if (this.#externalMutationCleanupFailure?.cleanupIncomplete === true)
+            return err(this.#externalMutationCleanupFailure);
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const resolved = await resolve();
+        if (!resolved.ok)
+            return resolved;
+        const { target, route, sameTarget } = resolved.value;
+        const { profile } = route;
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const activeProfile = this.#active?.profile;
+        const sameProfile = activeProfile === null || activeProfile === undefined
+            ? profile === null
+            : profile !== null && analysisProfilesEqual(activeProfile, profile);
+        await this.#drainCalls(admittedThrough);
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const pendingClosed = await this.#retryPendingCleanup();
+        if (!pendingClosed.ok)
+            return pendingClosed;
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const retained = sameTarget && sameProfile ? this.#active : undefined;
+        if (retained !== undefined) {
+            const fastPath = await this.#tryRetainedFastPath(retained, target, options);
+            if (fastPath !== undefined)
+                return fastPath;
+        }
+        const previous = this.#active;
+        this.#active = undefined;
+        if (previous !== undefined) {
+            const closed = await this.#retireClient(previous.client, previous.route.identity.id);
+            if (!closed.ok) {
+                // A failed open retires the provider cache, not the investigation.
+                // Preserve Evidence and Unknown history for export and recovery.
+                this.clearSnapshot();
+                this.#clearRuntimeAvailability();
+                return closed;
             }
-            this.#active = {
-                target,
-                client,
-                profile,
-                route,
-                runId,
-            };
-            this.#clearRuntimeAvailability();
-            this.resetSnapshotInvalidation();
-            if (options.snapshot === undefined) {
-                if (profile === null)
-                    this.clearSnapshot();
-                else
-                    this.selectSnapshot(target, profile);
+        }
+        if (isAborted(options.signal))
+            return err(await this.#restoreAfterFailedOpen(previous, new AnalysisCancelledError("open_binary")));
+        const runId = randomUUID();
+        const client = route.createClient(target, { runId });
+        const started = await client.execute("health", {}, options);
+        if (!started.ok) {
+            return err(await this.#failedOpen(client, route.identity.id, previous, started.error));
+        }
+        if (isAborted(options.signal)) {
+            return err(await this.#failedOpen(client, route.identity.id, previous, new AnalysisCancelledError("open_binary")));
+        }
+        this.#active = {
+            target,
+            client,
+            profile,
+            route,
+            runId,
+            nativeSourceAdmitted: false,
+        };
+        this.#clearRuntimeAvailability();
+        this.resetSnapshotInvalidation();
+        if (options.snapshot === undefined) {
+            if (profile === null)
+                this.clearSnapshot();
+            else
+                this.selectSnapshot(target, profile);
+        }
+        if (options.snapshot !== undefined) {
+            const imported = this.importAnalysisSnapshot(options.snapshot);
+            if (!imported.ok) {
+                this.#active = undefined;
+                return err(await this.#failedOpen(client, route.identity.id, previous, imported.error));
             }
-            if (options.snapshot !== undefined) {
-                const imported = this.importAnalysisSnapshot(options.snapshot);
-                if (!imported.ok) {
-                    this.#active = undefined;
-                    return err(await this.#failedOpen(client, route.identity.id, previous, imported.error));
-                }
+        }
+        return ok(target);
+    }
+    /** Serialize an external mutation and retire the potentially stale analysis. */
+    withAdmittedExternalMutation(_path, signal, operation, retirementFailure, operationName = "execute_rizin_command", cleanupRecovery) {
+        return this.#serialize(async (admittedThrough) => {
+            if (isAborted(signal))
+                return err(new AnalysisCancelledError(operationName));
+            await this.#drainCalls(admittedThrough);
+            if (isAborted(signal))
+                return err(new AnalysisCancelledError(operationName));
+            if (this.#externalMutationCleanupFailure?.cleanupIncomplete === true) {
+                if (cleanupRecovery === undefined)
+                    return err(this.#externalMutationCleanupFailure);
+                const recovered = await cleanupRecovery(this.#externalMutationCleanupFailure);
+                if (!recovered.ok)
+                    return recovered;
+                if (this.#externalMutationCleanupFailure.cleanupIncomplete)
+                    return err(this.#externalMutationCleanupFailure);
+                this.#externalMutationCleanupFailure = undefined;
             }
-            return ok(target);
+            const pendingCleanup = await this.#retryPendingCleanup();
+            if (!pendingCleanup.ok)
+                return pendingCleanup;
+            const activeAtDispatch = this.#active;
+            if (activeAtDispatch?.route.binding?.identity.id === "ghidra")
+                return err(new AnalysisOutputError(operationName, "Close the active Ghidra session explicitly before an external mutation; rebinding would discard its ephemeral analysis edits."));
+            // A protocol reply does not prove that background writers have stopped.
+            // Retire the old analysis and require an explicit fresh open rather than
+            // silently binding a snapshot while an unrestricted command can still write.
+            const retireTarget = activeAtDispatch !== undefined;
+            this.invalidateSnapshot();
+            const value = await operation();
+            this.#externalMutationCleanupFailure =
+                !value.ok && value.error.cleanupIncomplete ? value.error : undefined;
+            if (!retireTarget)
+                return ok(value);
+            const retired = await this.#closeActive({}, false);
+            if (!retired.ok)
+                return err(retirementFailure(value, retired.error));
+            return ok(value);
         });
     }
     /** Close the active target, if any. */
@@ -214,7 +279,7 @@ export class BinarySession extends BinarySessionRecords {
             const snapshot = this.exportAnalysisSnapshot();
             if (!snapshot.ok)
                 return snapshot;
-            const written = await writeAnalysisSnapshot(snapshot.value, path, overwrite);
+            const written = await this.writeAnalysisSnapshot(snapshot.value, path, overwrite);
             if (!written.ok)
                 return written;
             const closed = await this.#closeActive(options);
@@ -228,7 +293,7 @@ export class BinarySession extends BinarySessionRecords {
                 : closed;
         });
     }
-    async #closeActive(options) {
+    async #closeActive(options, clearRecords = true) {
         const previous = this.#active;
         this.#active = undefined;
         const closed = previous === undefined
@@ -241,9 +306,13 @@ export class BinarySession extends BinarySessionRecords {
                     ? { retainDocument: true }
                     : {}),
             });
-        this.clearSessionRecords();
+        if (clearRecords)
+            this.clearSessionRecords();
         this.#clearRuntimeAvailability();
-        return closed;
+        const fileResources = await this.closeWriteResources();
+        if (!closed.ok && !fileResources.ok)
+            return err(analysisErrorWithCleanupFailure(closed.error, fileResources.error, "close_binary"));
+        return closed.ok ? fileResources : closed;
     }
     async #retireClient(client, providerId, options = {}) {
         this.#pendingCleanup = {
@@ -314,6 +383,29 @@ export class BinarySession extends BinarySessionRecords {
         this.#calls.set(call, generation);
         return call.finally(() => this.#calls.delete(call));
     }
+    /** Run a prompt lookup only against an already connected provider child. */
+    executeIfProviderReady(name, arguments_, options) {
+        const active = this.#active;
+        if (this.#transitionPending > 0 ||
+            active === undefined ||
+            active.client.executeIfReady === undefined)
+            return Promise.resolve(undefined);
+        const controller = new AbortController();
+        this.#promptCompletionControllers.add(controller);
+        const signal = options?.signal === undefined
+            ? controller.signal
+            : AbortSignal.any([controller.signal, options.signal]);
+        const generation = this.#transitionGeneration;
+        const call = active.client.executeIfReady(name, arguments_, {
+            ...options,
+            signal,
+        });
+        this.#calls.set(call, generation);
+        return call.finally(() => {
+            this.#calls.delete(call);
+            this.#promptCompletionControllers.delete(controller);
+        });
+    }
     /** Admit one composed request until its result and session bookkeeping settle. */
     withAdmittedAnalysis(operationName, signal, operation) {
         const generation = this.#transitionGeneration;
@@ -338,6 +430,7 @@ export class BinarySession extends BinarySessionRecords {
             active: this.#active,
             operation: name,
             parameters: arguments_,
+            nativeSourceAdmitted: this.#active?.nativeSourceAdmitted === true,
             unboundOperationError: (operation, route) => this.#providerRouter.unboundOperationError(operation, route),
             lookupSnapshot: (target, profile, operation, parameters) => operation === "decode_interface_builder" ||
                 operation === "inspect_asset_catalog" ||
@@ -351,25 +444,51 @@ export class BinarySession extends BinarySessionRecords {
         const { active, capability, profile, cacheable, cached } = prepared.value;
         if (cached !== undefined)
             return ok(cached);
+        // A failed reply cannot prove that a dispatched metadata write rolled back.
+        // Stop replay before dispatch, including reads overlapping the write.
+        if (capability.effects.mutatesArtifact)
+            this.invalidateSnapshot();
         const call = active.client.execute(name, arguments_, options);
         const result = await call;
         const profiled = bindExecutionTarget(commitExecutionProfile(name, result, profile), name, active.target);
-        this.#observeRuntimeAvailability(name, profiled);
-        if (profiled.ok &&
+        const execution = profiled.ok &&
+            (name === "procedure_callers" || name === "procedure_callees") &&
+            profiled.value.relationshipCoverage === undefined
+            ? ok({
+                ...profiled.value,
+                relationshipCoverage: {
+                    status: "unknown",
+                    reason: "Provider did not report relationship coverage for this observation.",
+                },
+            })
+            : profiled;
+        // A successful Ghidra operation proves this client's native source snapshot
+        // was admitted; a composite health response and parsed path do not.
+        if (execution.ok &&
+            capability.provider.id === "ghidra" &&
+            this.#active === active)
+            this.#active.nativeSourceAdmitted = true;
+        this.#observeRuntimeAvailability(name, execution);
+        if (execution.ok &&
             cacheable &&
             profile !== undefined &&
             name !== "decode_interface_builder" &&
             name !== "inspect_asset_catalog" &&
             name !== "inspect_keyed_archive" &&
             name !== "trace_dylib_resolution") {
-            const evidence = createEvidence(profiled.value.subject ?? active.target, profiled.value.provider, {
+            const evidence = createEvidence(execution.value.subject ?? active.target, execution.value.provider, {
                 operation: name,
                 parameters: arguments_,
-                result: profiled.value.result,
+                result: execution.value.result,
                 analysisProfile: profile,
-                rawResult: profiled.value.rawResult,
-                limitations: profiled.value.limitations,
-                locations: profiled.value.locations,
+                rawResult: execution.value.rawResult,
+                limitations: execution.value.limitations,
+                ...(execution.value.relationshipCoverage === undefined
+                    ? {}
+                    : {
+                        relationshipCoverage: execution.value.relationshipCoverage,
+                    }),
+                locations: execution.value.locations,
             });
             const recorded = this.recordEvidence(evidence);
             if (!recorded.ok)
@@ -379,13 +498,10 @@ export class BinarySession extends BinarySessionRecords {
                 profile,
                 operation: name,
                 parameters: arguments_,
-                execution: profiled.value,
+                execution: execution.value,
             });
         }
-        else if (profiled.ok && capability.effects.mutatesArtifact) {
-            this.invalidateSnapshot();
-        }
-        return profiled;
+        return execution;
     }
     #observeRuntimeAvailability(operation, result) {
         if (result.ok) {
@@ -451,10 +567,18 @@ export class BinarySession extends BinarySessionRecords {
         return this.#active?.route ?? this.#providerRouter.initialRoute();
     }
     #serialize(operation) {
+        for (const controller of this.#promptCompletionControllers)
+            controller.abort();
+        this.#transitionPending += 1;
         // Later calls wait for this transition and must not be included in its drain.
         const admittedThrough = this.#transitionGeneration++;
         const result = this.#transition.then(() => operation(admittedThrough), () => operation(admittedThrough));
         this.#transition = result.then(() => undefined, () => undefined);
+        void result.then(() => {
+            this.#transitionPending -= 1;
+        }, () => {
+            this.#transitionPending -= 1;
+        });
         return result;
     }
     async #drainCalls(admittedThrough) {
@@ -462,6 +586,33 @@ export class BinarySession extends BinarySessionRecords {
             .filter(([, generation]) => generation <= admittedThrough)
             .map(([call]) => call));
     }
+    /**
+     * Probe whether a retained provider client is still live.
+     *
+     * On production routes the client is a CompositeProvider whose `health`
+     * answers unconditionally ok without touching a child, so `health` alone
+     * cannot see a dead child. `operationHealthSnapshot` reaches the
+     * instantiated children instead. Only the known-live states allow the
+     * fast path: `exited`/`unreachable` are dead, `unknown` is never
+     * evidence of health (it is what a recorded but uncharacterized failure
+     * reports), and `not_started` is a startup that never completed — in the
+     * Hopper timeout case the client holds retained resources that block the
+     * next `start()` until `close()` retries cleanup, so treating it as live
+     * would skip the retire path and hand the wedged client to subsequent
+     * analysis. The gate fails closed: without a snapshot signal, fall back
+     * to the `health` admission probe.
+     */
+    async #retainedClientLive(client, options) {
+        const snapshot = client.operationHealthSnapshot?.();
+        if (snapshot !== undefined)
+            return snapshot.state === "idle" || snapshot.state === "busy";
+        try {
+            return (await client.execute("health", {}, options)).ok;
+        }
+        catch {
+            return false;
+        }
+    }
     async #restore(previous) {
         if (previous === undefined)
             return ok(null);
@@ -475,7 +626,9 @@ export class BinarySession extends BinarySessionRecords {
                 profile: previous.profile,
                 route: previous.route,
                 runId,
+                nativeSourceAdmitted: false,
             };
+            this.#clearRuntimeAvailability();
             return ok(null);
         }
         const closed = await this.#retireClient(client, previous.route.identity.id);

package/dist/application/binary/BinarySessionExecution.js

@@ -1,12 +1,11 @@
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
 import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
-import {} from "../../domain/analysisErrorBase.js";
 import { err, ok } from "../../domain/result.js";
-import { isSnapshotCacheable } from "./AnalysisSnapshotCache.js";
+import { isSnapshotCacheable, requiresNativeSourceAdmissionBeforeReplay, } from "./AnalysisSnapshotCache.js";
 /** Resolve capability, profile, and snapshot state before invoking a provider. */
 export const prepareSessionExecution = (input) => {
-    const { active, operation, parameters, unboundOperationError, lookupSnapshot, } = input;
+    const { active, operation, parameters, nativeSourceAdmitted, unboundOperationError, lookupSnapshot, } = input;
     if (active === undefined)
         return err(new NoBinaryOpenError());
     const capability = active.route.capabilities.get(operation);
@@ -22,7 +21,9 @@ export const prepareSessionExecution = (input) => {
         : undefined;
     const cacheable = profile !== undefined &&
         isSnapshotCacheable(operation, capability, parameters);
-    const cached = cacheable
+    const cached = cacheable &&
+        (!requiresNativeSourceAdmissionBeforeReplay(capability.provider.id) ||
+            nativeSourceAdmitted)
         ? lookupSnapshot(active.target, profile, operation, parameters)
         : undefined;
     return ok({ active, capability, profile, cacheable, cached });

package/dist/application/binary/BinarySessionOpen.js

@@ -1,8 +1,6 @@
 import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../../domain/analysisSnapshot.js";
 import { parseBinaryTarget } from "../BinaryTargetResolver.js";
-import {} from "../../domain/binaryTargetTypes.js";
 import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
-import {} from "../../domain/analysisErrorBase.js";
 import { err } from "../../domain/result.js";
 import { SessionProviderRouter } from "./SessionProviderRouter.js";
 /** Parse a target, resolve its provider route, and validate snapshot binding. */
@@ -15,6 +13,12 @@ export const resolveSessionOpen = async (input) => {
         ...(options.formatHint === undefined
             ? {}
             : { formatHint: options.formatHint }),
+        ...(options.architecture === undefined
+            ? {}
+            : { architecture: options.architecture }),
+        ...(options.entryPoint === undefined
+            ? {}
+            : { entryPoint: options.entryPoint }),
         ...(options.signal === undefined ? {} : { signal: options.signal }),
     });
     if (!parsed.ok)
@@ -24,8 +28,7 @@ export const resolveSessionOpen = async (input) => {
 /** Resolve a known target's provider route and validate snapshot binding. */
 export const resolveSessionTarget = async (input) => {
     const { router, current, target, options } = input;
-    const sameTarget = current?.target.path === target.path &&
-        snapshotMatchesTarget(snapshotTarget(current.target), target);
+    const sameTarget = sameSessionTarget(current?.target, target);
     const resolvedRoute = sameTarget && options.providerId === undefined && current !== undefined
         ? { ok: true, value: current.route }
         : await router.resolve(target, options.providerId, options.signal);
@@ -39,8 +42,7 @@ export const resolveSessionTarget = async (input) => {
 /** Revalidate a previewed route against the current session and snapshot binding. */
 export const validateResolvedSessionTarget = (input) => {
     const { current, target, route, options, stagedSnapshotMatches } = input;
-    const sameTarget = current?.target.path === target.path &&
-        snapshotMatchesTarget(snapshotTarget(current.target), target);
+    const sameTarget = sameSessionTarget(current?.target, target);
     const snapshotError = validateSnapshot({
         snapshot: options.snapshot,
         target,
@@ -52,6 +54,11 @@ export const validateResolvedSessionTarget = (input) => {
         return err(snapshotError);
     return { ok: true, value: { target, route, sameTarget } };
 };
+const sameSessionTarget = (current, target) => current !== undefined &&
+    current.path === target.path &&
+    // Native admission is bound to the requested path, not just its realpath.
+    (current.sourcePath ?? current.path) === (target.sourcePath ?? target.path) &&
+    snapshotMatchesTarget(snapshotTarget(current), target);
 const validateSnapshot = ({ snapshot, target, profile, current, stagedSnapshotMatches, }) => {
     if (snapshot !== undefined &&
         (profile === null || !snapshotMatchesBinding(snapshot, target, profile)))

package/dist/application/binary/BinarySessionRecords.js

@@ -1,14 +1,16 @@
 import { evidenceBundleForTarget } from "../../domain/evidenceBundle.js";
-import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
-import {} from "../../domain/analysisErrorBase.js";
-import {} from "../../domain/unknownRegistryError.js";
+import { EvidenceFileError, EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
 import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { writeAnalysisSnapshot as writeSnapshotFile } from "./AnalysisSnapshotFiles.js";
 const SNAPSHOT_MUTATION_RECOVERY = "Export session observations through export_evidence_bundle if needed. Close the active target without saving a snapshot, then reopen it before importing or saving a snapshot.";
 /** Own binary snapshots and coordinate the composed investigation records. */
 export class BinarySessionRecords {
     #records;
+    #writeResources = new ArtifactResourceScope();
     #snapshot = new AnalysisSnapshotCache();
     #snapshotInvalidated = false;
     #snapshotListeners = new Set();
@@ -43,6 +45,27 @@ export class BinarySessionRecords {
     evidenceBundleForSerialization() {
         return this.#records.evidenceBundleForSerialization();
     }
+    /** Persist one provider-neutral snapshot under this session's resource owner. */
+    writeAnalysisSnapshot(snapshot, path, overwrite) {
+        return writeSnapshotFile(snapshot, path, overwrite, this.#writeResources);
+    }
+    /** Retry and release staged snapshot files at the owning session shutdown. */
+    async closeWriteResources() {
+        try {
+            await this.#writeResources.retryCleanup();
+            return ok(null);
+        }
+        catch (cause) {
+            const observation = ArtifactReaderFailure.cleanupObservation(cause, "analysis snapshot staging");
+            return err(new EvidenceFileError("write", "io", {
+                cause,
+                cleanup: {
+                    reason: observation.reason,
+                    resources: observation.resources,
+                },
+            }));
+        }
+    }
     importEvidenceBundle(bundle) {
         const imported = this.#records.mergeEvidenceBundle(bundle);
         if (!imported.ok)
@@ -56,8 +79,8 @@ export class BinarySessionRecords {
     exportAnalysisSnapshot() {
         const active = this.activeAnalysisBinding();
         if (this.#snapshotInvalidated)
-            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations", {
-                userMessage: `Analysis snapshots are unavailable after analysis metadata mutations. ${SNAPSHOT_MUTATION_RECOVERY}`,
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable because analysis metadata may have changed", {
+                userMessage: `Analysis snapshots are unavailable because analysis metadata may have changed. ${SNAPSHOT_MUTATION_RECOVERY}`,
             }));
         const target = active?.target;
         const profile = active?.profile ?? undefined;
@@ -70,8 +93,8 @@ export class BinarySessionRecords {
     importAnalysisSnapshot(snapshot) {
         const active = this.activeAnalysisBinding();
         if (active !== undefined && this.#snapshotInvalidated)
-            return err(new EvidenceIntegrityError("Analysis snapshots cannot be imported after analysis metadata mutations", {
-                userMessage: `Analysis snapshots cannot be imported after analysis metadata mutations. ${SNAPSHOT_MUTATION_RECOVERY}`,
+            return err(new EvidenceIntegrityError("Analysis snapshots cannot be imported because analysis metadata may have changed", {
+                userMessage: `Analysis snapshots cannot be imported because analysis metadata may have changed. ${SNAPSHOT_MUTATION_RECOVERY}`,
             }));
         if (active?.profile === null)
             return err(new AnalysisSnapshotMismatchError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
@@ -187,6 +210,9 @@ export class BinarySessionRecords {
     listUnknowns(filters = {}) {
         return this.#records.listUnknowns(filters);
     }
+    listUnknownsPage(query = {}) {
+        return this.#records.listUnknownsPage(query);
+    }
     verifyUnknownResolution(unknownId) {
         return this.#records.verifyUnknownResolution(unknownId);
     }