rea-agents 6.4.0 → 6.7.0

package/dist/application/binary/AnalysisProviderRegistry.js

@@ -1,19 +1,45 @@
+import { ProviderInspectionScope } from "../../providers/ProviderInspectionScope.js";
+import { AnalysisCleanupLease } from "../../artifacts/AnalysisCleanupLease.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { bindArtifactFileCleanup } from "../../artifacts/ArtifactFileOperation.js";
+import { SharedStartupAttempt } from "../../process/SharedStartupAttempt.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
 import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../../contracts/providerSelection.js";
 import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { ProviderSelectionError, } from "../../domain/providerSelectionError.js";
-import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
 import { evaluateAnalysisProviderCandidate, } from "./AnalysisProviderEvaluation.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 /**
  * Discover and select overlapping deep providers without starting their clients.
  * Registration order never affects selection or caller-visible output.
  */
 export class AnalysisProviderRegistry {
+    canInspectWithoutDeepProvider;
     #providers;
     #byId;
     #declaredOperations;
     #defaultSelector;
-    constructor(providers, defaultSelector = "auto") {
+    #selections = new Set();
+    #discoveries = new Set();
+    #selectionCleanup = new Set();
+    #profileFiles = new ArtifactResourceScope();
+    #profileFileOwner = {
+        retain: (owner, resource) => this.#profileFiles.retain({
+            kind: "lease",
+            resource,
+            lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
+        }),
+        run: (operation) => this.#profileFiles.run(operation),
+    };
+    #closing;
+    constructor(providers, defaultSelector = "auto", canInspectWithoutDeepProvider) {
+        this.canInspectWithoutDeepProvider = canInspectWithoutDeepProvider;
         this.#defaultSelector =
             analysisProviderSelectorSchema.parse(defaultSelector);
         const byId = new Map();
@@ -37,9 +63,9 @@ export class AnalysisProviderRegistry {
             }
             byId.set(identity.id, provider);
         }
-        this.#providers = Object.freeze([...providers].sort((left, right) => left.identity().id.localeCompare(right.identity().id)));
+        this.#providers = Object.freeze([...providers].sort((left, right) => compareUnicodeCodePoints(left.identity().id, right.identity().id)));
         this.#byId = byId;
-        this.#declaredOperations = Object.freeze([...declaredOperations].sort((left, right) => left.localeCompare(right)));
+        this.#declaredOperations = Object.freeze([...declaredOperations].sort((left, right) => compareUnicodeCodePoints(left, right)));
     }
     /** Return the configured default without interpreting it as priority. */
     defaultSelector() {
@@ -49,46 +75,240 @@ export class AnalysisProviderRegistry {
     identities() {
         return this.#providers.map((provider) => structuredClone(provider.identity()));
     }
+    /** Report retained candidate resources without retrying cleanup. */
+    hasPendingOwnedResources() {
+        return (this.#selections.size > 0 ||
+            this.#discoveries.size > 0 ||
+            this.#profileFiles.hasPending ||
+            [...this.#selectionCleanup].some((error) => error.cleanupIncomplete) ||
+            this.#providers.some((provider) => provider.hasPendingOwnedResources?.() === true));
+    }
+    /** Close candidate-owned resources even when no target client was opened. */
+    closeOwnedResources() {
+        this.#closing ??= Promise.resolve()
+            .then(() => this.#closeOwnedResources())
+            .finally(() => {
+            this.#closing = undefined;
+        });
+        return this.#closing;
+    }
+    async #closeOwnedResources() {
+        const selections = [...this.#selections];
+        const discoveries = [...this.#discoveries];
+        for (const discovery of discoveries)
+            discovery.close();
+        for (const selection of selections)
+            selection.close();
+        await Promise.allSettled([
+            ...discoveries.map((discovery) => discovery.promise),
+            ...selections.map((selection) => selection.promise),
+        ]);
+        const failures = [];
+        try {
+            await this.#profileFiles.retryCleanup();
+        }
+        catch (cause) {
+            const cleanup = ArtifactReaderFailure.cleanupObservation(cause, "provider profile files");
+            const failure = new ProviderCleanupError("rea", cleanup.resources, { reason: cleanup.reason }, { cause });
+            bindArtifactFileCleanup(cause, failure);
+            failures.push(failure);
+        }
+        for (const provider of this.#providers) {
+            if (provider.closeOwnedResources === undefined)
+                continue;
+            const result = await provider.closeOwnedResources();
+            if (!result.ok)
+                failures.push(result.error);
+        }
+        for (const failure of this.#selectionCleanup) {
+            if (failure.cleanupIncomplete)
+                failures.push(failure);
+            else
+                this.#selectionCleanup.delete(failure);
+        }
+        const distinct = [...new Set(failures)];
+        if (distinct.length === 0)
+            return ok(null);
+        if (distinct.length === 1)
+            return err(distinct[0]);
+        return err(new ProviderCleanupError("rea", [...new Set(distinct.flatMap((failure) => failure.cleanupResources))], { reason: distinct.map((failure) => failure.message).join("; ") }, { cause: new AggregateError(distinct) }).bindCleanupDependencies(distinct.filter((failure) => failure.cleanupIncomplete)));
+    }
     /** List the unique deep-operation declarations without probing candidates. */
     declaredOperations() {
         return [...this.#declaredOperations];
     }
     /** Discover candidates for status without resolving profiles or starting clients. */
-    candidates(target) {
-        return this.#providers.map((provider) => candidateStatus(provider, target));
+    async candidates(target, options = {}) {
+        if (options.signal?.aborted)
+            throw new AnalysisCancelledError("binary_session", {
+                cause: options.signal.reason,
+            });
+        if (this.#closing !== undefined)
+            return this.#providers.map((provider) => projectCandidateStatus(provider, target, {
+                availability: {
+                    status: "unknown",
+                    code: null,
+                    reason: "Provider ownership finalization is in progress; readiness has not been re-observed.",
+                    diagnostics: { finalization: "in_progress" },
+                },
+                capabilities: provider.capabilities(),
+            }));
+        const scope = new ProviderInspectionScope();
+        const discovery = new SharedStartupAttempt((signal) => Promise.resolve().then(() => this.#discoverCandidates(target, {
+            signal,
+            scope,
+            operation: "binary_session",
+        })), options.signal);
+        this.#discoveries.add(discovery);
+        try {
+            const result = await discovery.promise;
+            if (!result.ok)
+                throw result.error;
+            if (discovery.signal.aborted)
+                throw new AnalysisCancelledError("binary_session", {
+                    cause: discovery.signal.reason,
+                    diagnostics: {
+                        readiness_candidates: jsonValueSchema.parse(result.value),
+                    },
+                });
+            return result.value;
+        }
+        finally {
+            scope.close();
+            this.#discoveries.delete(discovery);
+        }
+    }
+    async #discoverCandidates(target, context) {
+        const { signal, operation } = context;
+        if (signal.aborted)
+            return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+        const results = await Promise.allSettled(this.#providers.map((provider) => candidateStatus(provider, target, context)));
+        const statuses = [];
+        const failures = [];
+        for (const [index, result] of results.entries()) {
+            if (result.status === "fulfilled")
+                statuses.push(result.value);
+            else
+                failures.push({
+                    providerId: this.#providers[index].identity().id,
+                    error: result.reason instanceof AnalysisError
+                        ? result.reason
+                        : new ProviderAdapterError(this.#providers[index].identity().id, operation, { cause: result.reason }),
+                });
+        }
+        for (const { error } of failures)
+            if (error.cleanupIncomplete)
+                this.#selectionCleanup.add(error);
+        if (failures.length > 0)
+            return err(providerInspectionFailure(failures, { operation, candidates: statuses }, signal));
+        return ok(statuses);
     }
     /** Select one whole deep-operation family for a parsed target. */
     async select(target, requestedSelector, options = {}) {
         if (signalIsAborted(options.signal))
-            return err(new AnalysisCancelledError("open_binary"));
-        const parsedRequest = requestedSelector === undefined
-            ? undefined
-            : analysisProviderSelectorSchema.safeParse(requestedSelector);
-        if (parsedRequest !== undefined && !parsedRequest.success)
-            return err(selectionError("invalid_options", typeof requestedSelector === "string"
-                ? requestedSelector
-                : "<invalid>", this.candidates(target)));
-        const request = parsedRequest?.data;
-        const selector = request ?? this.#defaultSelector;
-        const baseline = this.candidates(target);
+            return err(new AnalysisCancelledError("open_binary", {
+                cause: options.signal?.reason,
+            }));
+        if (this.#closing !== undefined) {
+            const closed = await this.#closing;
+            if (!closed.ok)
+                return closed;
+        }
+        for (const failure of this.#selectionCleanup)
+            if (!failure.cleanupIncomplete)
+                this.#selectionCleanup.delete(failure);
+        if ([...this.#selectionCleanup].some((failure) => failure.cleanupIncomplete)) {
+            // A retry may release retained owners; never stop another live selection
+            // merely because a new caller wants admission.
+            if (this.#selections.size > 0 || this.#discoveries.size > 0)
+                return err([...this.#selectionCleanup].find((failure) => failure.cleanupIncomplete));
+            const closed = await this.closeOwnedResources();
+            if (!closed.ok)
+                return closed;
+        }
         if (signalIsAborted(options.signal))
-            return err(new AnalysisCancelledError("open_binary"));
-        if (request === undefined &&
-            selector !== "auto" &&
-            baseline.length > 0 &&
-            baseline.every(({ targetSupport }) => targetSupport.status === "unsupported"))
-            return ok({
-                requestedProviderId: selector,
-                binding: null,
-                candidates: baseline,
-            });
-        if (selector !== "auto")
-            return this.#selectConcrete({ target, baseline, signal: options.signal }, selector, request === undefined ? "environment" : "request");
-        return this.#selectAutomatically({
-            target,
-            baseline,
-            signal: options.signal,
+            return err(new AnalysisCancelledError("open_binary", {
+                cause: options.signal?.reason,
+            }));
+        const selection = new SharedStartupAttempt((signal) => Promise.resolve().then(() => this.#selectTarget(target, requestedSelector, signal)), options.signal);
+        this.#selections.add(selection);
+        void selection.promise.then((result) => {
+            this.#selections.delete(selection);
+            if (!result.ok && result.error.cleanupIncomplete)
+                this.#selectionCleanup.add(result.error);
+        }, () => {
+            this.#selections.delete(selection);
         });
+        const waited = await selection.wait(options.signal);
+        if (waited.status !== "cancelled") {
+            if (!waited.value.ok)
+                return waited.value;
+            if (!selection.signal.aborted)
+                return waited.value;
+            return err(new AnalysisCancelledError("open_binary", {
+                cause: selection.signal.reason,
+            }));
+        }
+        return err(new AnalysisCancelledError("open_binary", {
+            cause: options.signal?.reason,
+        }));
+    }
+    async #selectTarget(target, requestedSelector, signal) {
+        const scope = new ProviderInspectionScope();
+        try {
+            if (signalIsAborted(signal))
+                return err(new AnalysisCancelledError("open_binary", { cause: signal.reason }));
+            const discovery = await this.#discoverCandidates(target, {
+                signal,
+                scope,
+                operation: "open_binary",
+            });
+            if (!discovery.ok)
+                return discovery;
+            const baseline = discovery.value;
+            const parsedRequest = requestedSelector === undefined
+                ? undefined
+                : analysisProviderSelectorSchema.safeParse(requestedSelector);
+            if (parsedRequest !== undefined && !parsedRequest.success)
+                return err(selectionError("invalid_options", typeof requestedSelector === "string"
+                    ? requestedSelector
+                    : "<invalid>", baseline));
+            const request = parsedRequest?.data;
+            const selector = request ?? this.#defaultSelector;
+            if (signalIsAborted(signal))
+                return err(new AnalysisCancelledError("open_binary", { cause: signal.reason }));
+            if (selector === "auto" && this.canInspectWithoutDeepProvider?.(target))
+                return ok({
+                    requestedProviderId: selector,
+                    binding: null,
+                    candidates: baseline,
+                });
+            if (request === undefined &&
+                this.#byId.has(selector) &&
+                baseline.length > 0 &&
+                baseline.every(({ targetSupport }) => targetSupport.status === "unsupported"))
+                return ok({
+                    requestedProviderId: selector,
+                    binding: null,
+                    candidates: baseline,
+                });
+            if (selector !== "auto")
+                return await this.#selectConcrete({
+                    target,
+                    baseline,
+                    signal: signal,
+                    scope,
+                }, selector, request === undefined ? "environment" : "request");
+            return await this.#selectAutomatically({
+                target,
+                baseline,
+                signal: signal,
+                scope,
+            });
+        }
+        finally {
+            scope.close();
+        }
     }
     /** Explain why a deep operation is unavailable on an unbound target. */
     unboundOperationError(operation, selection) {
@@ -99,7 +319,7 @@ export class AnalysisProviderRegistry {
         return selectionError(reason, selection.requestedProviderId, selection.candidates, operation);
     }
     async #selectConcrete(context, providerId, source) {
-        const { baseline, signal, target } = context;
+        const { baseline, signal, target, scope } = context;
         const provider = this.#byId.get(providerId);
         if (provider === undefined)
             return err(selectionError("unknown_provider", providerId, baseline));
@@ -110,7 +330,7 @@ export class AnalysisProviderRegistry {
             return err(selectionError("target_unsupported", providerId, baseline));
         if (initial.availability.status === "unavailable")
             return err(selectionError("provider_unavailable", providerId, baseline));
-        const evaluation = await evaluateAnalysisProviderCandidate(provider, initial, target, signal);
+        const evaluation = await evaluateAnalysisProviderCandidate(provider, initial, target, { signal, fileCloseResources: this.#profileFileOwner, scope });
         if (!evaluation.ok)
             return evaluation;
         const evaluated = evaluation.value;
@@ -125,27 +345,34 @@ export class AnalysisProviderRegistry {
         }, statuses));
     }
     async #selectAutomatically(context) {
-        const { baseline, signal, target } = context;
+        const { baseline, signal, target, scope } = context;
         const results = await Promise.all(this.#providers.map(async (provider) => {
             const status = baseline.find(({ provider: identity }) => identity.id === provider.identity().id);
             if (status === undefined)
                 throw new TypeError("Registered provider is absent from discovery output");
             return status.availability.status === "available" &&
                 status.targetSupport.status === "supported"
-                ? evaluateAnalysisProviderCandidate(provider, status, target, signal)
+                ? evaluateAnalysisProviderCandidate(provider, status, target, {
+                    signal,
+                    fileCloseResources: this.#profileFileOwner,
+                    scope,
+                })
                 : ok({
                     candidate: provider,
                     status,
                 });
         }));
-        const cancelled = results.find((result) => !result.ok);
-        if (cancelled !== undefined && !cancelled.ok)
-            return cancelled;
-        const evaluations = results.map((result) => {
-            if (!result.ok)
-                throw new TypeError("Cancelled candidate evaluation disappeared");
-            return result.value;
+        const evaluations = results.flatMap((result) => result.ok ? [result.value] : []);
+        const failures = results.flatMap((result, index) => {
+            const error = result.ok ? result.value.profileError : result.error;
+            return error === undefined
+                ? []
+                : [{ providerId: this.#providers[index].identity().id, error }];
         });
+        if (results.some((result) => !result.ok) ||
+            failures.some(({ error }) => error.cleanupIncomplete) ||
+            signalIsAborted(signal))
+            return err(providerInspectionFailure(failures, { operation: "resolve_analysis_profile" }, signal));
         const statuses = evaluations.map(({ status }) => status);
         const usable = evaluations.filter((evaluation) => evaluation.profile !== undefined);
         if (usable.length === 0)
@@ -162,36 +389,55 @@ export class AnalysisProviderRegistry {
         return ok(selectedResult("auto", "auto-single-candidate", selected, statuses));
     }
 }
-const candidateStatus = (provider, target) => ({
-    provider: structuredClone(provider.identity()),
-    availability: cloneAvailability(provider.inspectAvailability()),
-    targetSupport: target === undefined
+const candidateStatus = async (provider, target, context) => {
+    const { signal, scope, operation } = context;
+    if (signal.aborted)
+        throw new AnalysisCancelledError(operation, { cause: signal.reason });
+    const readiness = provider.inspectReadinessSnapshot === undefined
         ? {
-            status: "unknown",
-            code: null,
-            reason: "No target is open.",
-            diagnostics: {},
+            availability: await provider.inspectAvailability({ signal, scope }),
+            capabilities: provider.capabilities(),
         }
-        : cloneTargetSupport(provider.inspectTargetSupport(target)),
-    selected: false,
-    capabilities: provider
-        .capabilities()
-        .map((capability) => structuredClone(capability)),
-});
+        : await provider.inspectReadinessSnapshot({ signal, scope });
+    return projectCandidateStatus(provider, target, readiness);
+};
+const projectCandidateStatus = (provider, target, readiness) => {
+    return {
+        provider: structuredClone(provider.identity()),
+        availability: cloneAvailability(readiness.availability),
+        targetSupport: target === undefined
+            ? {
+                status: "unknown",
+                code: null,
+                reason: "No target is open.",
+                diagnostics: {},
+            }
+            : cloneTargetSupport(provider.inspectTargetSupport(target)),
+        selected: false,
+        capabilities: readiness.capabilities.map((capability) => structuredClone(capability)),
+    };
+};
 const signalIsAborted = (signal) => signal?.aborted === true;
 const selectedResult = (requestedProviderId, source, evaluated, statuses) => {
+    const identity = evaluated.profile.provider;
+    const capabilities = evaluated.status.capabilities.map((capability) => ({
+        ...capability,
+        provider: structuredClone(identity),
+    }));
     const selectedStatus = {
         ...evaluated.status,
-        provider: structuredClone(evaluated.profile.provider),
+        provider: structuredClone(identity),
         selected: true,
+        capabilities,
     };
     return {
         requestedProviderId,
         binding: {
             provider: evaluated.candidate,
-            identity: structuredClone(evaluated.profile.provider),
+            identity: structuredClone(identity),
             selectionSource: source,
             profile: structuredClone(evaluated.profile),
+            capabilities,
         },
         candidates: replaceCandidate(statuses, selectedStatus),
     };
@@ -225,3 +471,62 @@ const cloneTargetSupport = (support) => ({
     ...support,
     diagnostics: jsonObjectSchema.parse(support.diagnostics),
 });
+/** Every terminal child remains attributed; cleanup is conjunctive across owners. */
+const providerInspectionFailure = (failures, context, signal) => {
+    const primary = failures.find(({ error }) => !(error instanceof AnalysisCancelledError)) ??
+        failures[0];
+    if (primary === undefined)
+        return new AnalysisCancelledError(context.operation === "resolve_analysis_profile"
+            ? "open_binary"
+            : context.operation, { cause: signal?.reason });
+    if (failures.length === 1 &&
+        (context.operation === "resolve_analysis_profile" ||
+            context.candidates.length === 0))
+        return primary.error;
+    const cleanupFailures = failures
+        .filter(({ error }) => error.cleanupIncomplete)
+        .map(({ error }) => error);
+    const options = {
+        diagnostics: {
+            [context.operation === "resolve_analysis_profile"
+                ? "profile_errors"
+                : "readiness_errors"]: failures.map(({ providerId, error }) => ({
+                provider_id: providerId,
+                error: projectAnalysisError(error),
+            })),
+            ...(context.operation === "resolve_analysis_profile"
+                ? {}
+                : { readiness_candidates: jsonValueSchema.parse(context.candidates) }),
+        },
+        ...(primary.error.capturedOutput === undefined
+            ? {}
+            : { capturedOutput: primary.error.capturedOutput }),
+        ...(primary.error.partialObservation === undefined
+            ? {}
+            : { partialObservation: primary.error.partialObservation }),
+        ...(cleanupFailures.length === 0
+            ? {}
+            : {
+                cleanupPrimary: primary.error,
+                cleanup: {
+                    reason: cleanupFailures.map((error) => error.message).join("; "),
+                    resources: [
+                        ...new Set(cleanupFailures.flatMap((error) => error.cleanupResources)),
+                    ],
+                },
+            }),
+    };
+    const failure = primary.error instanceof AnalysisCancelledError
+        ? new AnalysisCancelledError(context.operation === "resolve_analysis_profile"
+            ? "open_binary"
+            : context.operation, {
+            ...options,
+            cause: primary.error.cause,
+        })
+        : new ProviderAdapterError("rea", context.operation, {
+            ...options,
+            userMessage: projectAnalysisError(primary.error).message,
+            cause: new AggregateError(failures.map(({ error }) => error), "Provider inspections failed", { cause: primary.error }),
+        });
+    return failure.bindCleanupDependencies(cleanupFailures);
+};

package/dist/application/binary/AnalysisSnapshotCache.js

@@ -1,10 +1,14 @@
 import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
 import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
-import {} from "../../domain/analysisErrorBase.js";
+import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js";
 import { err, ok } from "../../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, createAnalysisSnapshotWorkflowEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, createAnalysisSnapshotWorkflowEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, immutableAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+const RELATIONSHIP_OPERATIONS = new Set([
+    "procedure_callers",
+    "procedure_callees",
+]);
 const STATEFUL_OPERATIONS = new Set([
     "health",
     "current_address",
@@ -35,6 +39,8 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
     (descriptor.cachePolicy === "snapshot" ||
         descriptor.effects.mayWriteFilesystem === false) &&
     descriptor.effects.changesPermissions === false;
+/** Windows Ghidra must admit the selected source through its native snapshot owner. */
+export const requiresNativeSourceAdmissionBeforeReplay = (providerId) => process.platform === "win32" && providerId === "ghidra";
 /** Bounded in-memory cache for one immutable binary identity. */
 export class AnalysisSnapshotCache {
     #entries = new Map();
@@ -59,6 +65,7 @@ export class AnalysisSnapshotCache {
     }
     /** Merge already-validated entries and return the new-entry count. */
     stage(snapshot) {
+        snapshot = immutableAnalysisSnapshot(snapshot);
         if ((this.#target !== undefined &&
             JSON.stringify(this.#target) !== JSON.stringify(snapshot.target)) ||
             (this.#binding !== undefined &&
@@ -72,12 +79,12 @@ export class AnalysisSnapshotCache {
                 continue;
             if (!this.#entries.has(entry.query_id))
                 imported += 1;
-            this.#entries.set(entry.query_id, structuredClone(entry));
+            this.#entries.set(entry.query_id, entry);
         }
         for (const entry of snapshot.workflow_entries) {
             if (!this.#workflowEntries.has(entry.query_id) && !this.#hasCapacity())
                 continue;
-            this.#workflowEntries.set(entry.query_id, structuredClone(entry));
+            this.#workflowEntries.set(entry.query_id, entry);
         }
         return imported;
     }
@@ -110,7 +117,7 @@ export class AnalysisSnapshotCache {
     import(snapshot, active, mergeEvidence) {
         let validated;
         try {
-            validated = parseAnalysisSnapshot(snapshot);
+            validated = immutableAnalysisSnapshot(snapshot);
         }
         catch (cause) {
             return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
@@ -157,7 +164,17 @@ export class AnalysisSnapshotCache {
         const cached = this.#entries.get(queryId);
         if (cached === undefined)
             return undefined;
-        const subject = cached.execution.subject;
+        const cachedSubject = cached.execution.subject;
+        const subject = cachedSubject === null
+            ? null
+            : rebindEvidenceSubjectTargetPath({
+                path: cachedSubject.path,
+                sha256: cachedSubject.sha256,
+                format: cachedSubject.format,
+                ...(cachedSubject.architecture === null
+                    ? {}
+                    : { architecture: cachedSubject.architecture }),
+            }, target);
         return structuredClone({
             result: cached.execution.result,
             rawResult: cached.execution.raw_result,
@@ -167,27 +184,31 @@ export class AnalysisSnapshotCache {
                 ...cached.execution.limitations,
                 "Loaded from a local REA analysis snapshot; this call did not re-run the provider.",
             ],
-            locations: cached.execution.locations,
-            subject: subject === null
-                ? null
-                : subject.architecture === null
-                    ? {
-                        path: subject.path,
-                        sha256: subject.sha256,
-                        format: subject.format,
-                    }
-                    : {
-                        path: subject.path,
-                        sha256: subject.sha256,
-                        format: subject.format,
-                        architecture: subject.architecture,
+            ...(cached.execution.relationship_coverage === null &&
+                RELATIONSHIP_OPERATIONS.has(operation)
+                ? {
+                    relationshipCoverage: {
+                        status: "unknown",
+                        reason: "Snapshot entry does not report relationship coverage.",
                     },
+                }
+                : cached.execution.relationship_coverage === null
+                    ? {}
+                    : {
+                        relationshipCoverage: cached.execution.relationship_coverage,
+                    }),
+            locations: cached.execution.locations,
+            subject,
         });
     }
     /** Record one successful immutable call unless the cache is full. */
     record(input) {
         const { target, profile, operation, parameters, execution } = input;
         this.select(target, profile);
+        // The snapshot format does not carry reference truncation; a replay would
+        // present a capped read as complete, so it is not recorded.
+        if (execution.referencesTruncated === true)
+            return;
         const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
         if (!this.#entries.has(queryId) && !this.#hasCapacity())
             return;