rea-agents 6.4.0 → 6.5.0

package/dist/application/analysisView/AnalysisViewService.js

@@ -1,13 +1,16 @@
+import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../../domain/analysisView/analysisViewErrors.js";
 import { z } from "zod";
 import { ANALYSIS_VIEW_PROVIDER } from "../InvestigationProviders.js";
 import { resolveEvidenceInput } from "../EvidenceInputResolver.js";
-import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
 import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
 import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
 import { createEvidence, parseEvidence, } from "../../domain/evidence.js";
-import { INSPECT_ANALYSIS_VIEW_OPERATION, inspectAnalysisViewInputSchema, projectAnalysisView, } from "../../domain/analysisView/analysisView.js";
+import { inspectAnalysisViewInputSchema, projectAnalysisView, } from "../../domain/analysisView/analysisView.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { isImmutableJsonSnapshot } from "../../domain/immutableJson.js";
 import { err, ok } from "../../domain/result.js";
+import { WebNetworkApiSurfaceAccumulator } from "../../domain/analysisView/WebNetworkApiSurfaceAccumulator.js";
 /** Authenticate a selected-view request and project already completed Evidence. */
 export const inspectAnalysisView = (rawInput, lookup) => {
     const parsed = inspectAnalysisViewInputSchema.safeParse(rawInput);
@@ -15,8 +18,16 @@ export const inspectAnalysisView = (rawInput, lookup) => {
         return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, parsed.error.issues, rawInput, { cause: parsed.error }));
     return inspectAnalysisViewValidated(parsed.data, lookup);
 };
-/** Project a view from input already parsed by a trusted adapter. */
+/** Authenticate borrowed inline Evidence after adapter envelope validation. */
 export const inspectAnalysisViewValidated = (input, lookup) => {
+    const accumulator = input.view.kind === "api-surface"
+        ? new WebNetworkApiSurfaceAccumulator(undefined, input.view.include_query_parameter_names === true)
+        : undefined;
+    if (input.source.kind === "inline" && accumulator !== undefined) {
+        const admitted = accumulator.admitInlineEvidence(input.source.evidence);
+        if (!admitted.ok)
+            return admitted;
+    }
     const resolved = resolveAnalysisViewSource(input.source, lookup);
     if (!resolved.ok)
         return resolved;
@@ -25,14 +36,18 @@ export const inspectAnalysisViewValidated = (input, lookup) => {
         evidenceId: parent.evidence_id,
         operation: parent.operation,
         normalizedResult: parent.normalized_result,
+        // Sealing an Evidence root deep-freezes it; only the root is registered.
+        sealedResult: isImmutableJsonSnapshot(parent),
+        subject: parent.subject,
         limitations: parent.limitations,
+        parameters: parent.parameters,
         artifact: parent.subject === null
             ? null
             : {
                 path: parent.subject.local_path,
                 sha256: parent.subject.digest.sha256,
             },
-    }, input.view);
+    }, input.view, accumulator);
     if (!projected.ok)
         return projected;
     if (parent.subject !== null &&
@@ -40,28 +55,47 @@ export const inspectAnalysisViewValidated = (input, lookup) => {
         return err(new EvidenceIntegrityError(`Parent subject SHA-256 ${parent.subject.digest.sha256} differs from analysis artifact SHA-256 ${projected.value.artifact.sha256}.`));
     return ok(createAnalysisViewEvidence(input, parent, projected.value));
 };
+/** Fail before analysis when selected delivery cannot keep its complete source. */
+export const requireAnalysisViewRetention = (operation, retention) => {
+    if (retention.recordEvidence === undefined ||
+        retention.evidenceById === undefined)
+        return err(new AnalysisCapabilityUnavailableError(ANALYSIS_VIEW_PROVIDER.id, operation, "summary detail requires a server session that retains Evidence for later views", {
+            userMessage: "This server does not retain Evidence. Select detail complete to receive the complete analysis inline.",
+        }));
+    return ok({
+        evidenceById: retention.evidenceById,
+        recordEvidence: retention.recordEvidence,
+    });
+};
 /**
  * Retain complete analysis Evidence in the session, then project its summary
  * view from the retained record. Callers page or select the rest through
  * inspect_analysis_view with the view's parent Evidence ID.
  */
 export const summarizeRetainedAnalysis = (evidence, retention) => {
-    if (retention.recordEvidence === undefined ||
-        retention.evidenceById === undefined)
-        return err(new AnalysisCapabilityUnavailableError(ANALYSIS_VIEW_PROVIDER.id, evidence.operation, "summary detail requires a server session that retains Evidence for later views", {
-            userMessage: "This server does not retain Evidence. Select detail complete to receive the complete analysis inline.",
-        }));
-    const recorded = retention.recordEvidence(evidence);
+    const ready = requireAnalysisViewRetention(evidence.operation, retention);
+    if (!ready.ok)
+        return ready;
+    const recorded = ready.value.recordEvidence(evidence);
     if (!recorded.ok)
         return recorded;
     return inspectAnalysisViewValidated({
         source: { kind: "retained-evidence", evidence_id: evidence.evidence_id },
         view: { kind: "summary" },
-    }, retention.evidenceById);
+    }, ready.value.evidenceById);
 };
 const resolveAnalysisViewSource = (source, lookup) => {
     if (source.kind === "retained-evidence")
         return resolveEvidenceInput(source, lookup);
+    const invalidDataPath = inlineEvidenceInvalidDataPath(source.evidence);
+    if (invalidDataPath !== undefined)
+        return err(new AnalysisInputError(INSPECT_ANALYSIS_VIEW_OPERATION, undefined, [
+            {
+                path: ["source", "evidence", ...invalidDataPath],
+                reason: "invalid_type",
+                message: "Inline Evidence must contain plain JSON data properties without accessors or cycles.",
+            },
+        ]));
     try {
         return ok(parseEvidence(source.evidence));
     }
@@ -76,6 +110,46 @@ const resolveAnalysisViewSource = (source, lookup) => {
         throw cause;
     }
 };
+/** Reject non-JSON object behavior before Zod reads caller-owned Evidence. */
+const inlineEvidenceInvalidDataPath = (root) => {
+    const active = new Set();
+    const pending = [{ value: root, path: [] }];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            continue;
+        if (current.exit !== undefined) {
+            active.delete(current.exit);
+            continue;
+        }
+        const { value, path } = current;
+        if (typeof value !== "object" || value === null)
+            continue;
+        const isArray = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if ((isArray && prototype !== Array.prototype) ||
+            (!isArray && prototype !== Object.prototype && prototype !== null) ||
+            active.has(value))
+            return path;
+        active.add(value);
+        pending.push({ value, path, exit: value });
+        const keys = Object.getOwnPropertyNames(value);
+        for (let index = keys.length - 1; index >= 0; index -= 1) {
+            const key = keys[index];
+            if (key === undefined)
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            const childPath = [
+                ...path,
+                isArray && /^(0|[1-9]\d*)$/u.test(key) ? Number(key) : key,
+            ];
+            if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
+                return childPath;
+            pending.push({ value: descriptor.value, path: childPath });
+        }
+    }
+    return undefined;
+};
 const createAnalysisViewEvidence = (input, parent, result) => {
     const target = parent.subject === null
         ? undefined
@@ -96,7 +170,11 @@ const createAnalysisViewEvidence = (input, parent, result) => {
         },
         result: jsonValueSchema.parse(result),
         rawResult: null,
-        confidence: "derived",
+        confidence: 
+        // Paging follows the full grouping, so any templated group makes every page inferred.
+        result.kind === "api-surface" && result.templated_groups > 0
+            ? "inferred"
+            : "derived",
         authority: parent.authority,
         limitations: result.limitations,
         locations: [

package/dist/application/android/AndroidPackageInspection.js

@@ -0,0 +1,25 @@
+import { requireAnalysisViewRetention, summarizeRetainedAnalysis, } from "../analysisView/AnalysisViewService.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { androidPackageInspectionInputSchema } from "../../domain/android/androidAnalysis.js";
+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
+import { err } from "../../domain/result.js";
+/** Preserve the complete provider request; select retained delivery explicitly. */
+export const inspectAndroidPackage = async (service, rawInput, retention, options) => {
+    const operation = "inspect_android_package";
+    if (options?.signal?.aborted === true)
+        return err(new AnalysisCancelledError(operation));
+    const parsed = androidPackageInspectionInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(analysisInputErrorFromIssues(operation, parsed.error.issues, rawInput, {
+            cause: parsed.error,
+        }));
+    if (parsed.data.detail === "summary") {
+        const ready = requireAnalysisViewRetention(operation, retention);
+        if (!ready.ok)
+            return ready;
+    }
+    const executed = await service.execute(operation, { path: parsed.data.path }, options);
+    if (!executed.ok || parsed.data.detail !== "summary")
+        return executed;
+    return summarizeRetainedAnalysis(executed.value, retention);
+};

package/dist/application/android/AndroidSearchEvidenceSummary.js

@@ -0,0 +1,100 @@
+import { createEvidence } from "../../domain/evidence.js";
+import { ok } from "../../domain/result.js";
+/**
+ * Complete class-inventory pages dominate raw-call provenance for focused
+ * searches: one traversal embeds every examined class name regardless of the
+ * match count. The summary keeps the pagination audit inline (totals, page
+ * offsets and sizes, elided item counts) and links the retained record that
+ * still carries the complete inventory.
+ */
+const elideInventoryText = (text) => {
+    let page;
+    try {
+        page = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof page !== "object" ||
+        page === null ||
+        Array.isArray(page) ||
+        !Array.isArray(page.items))
+        return undefined;
+    const { items, ...audited } = page;
+    return JSON.stringify({ ...audited, items_omitted: items.length });
+};
+/** Replace inventoried page bodies with their pagination audit. */
+const summarizeInventoryCall = (call) => {
+    if (typeof call !== "object" ||
+        call === null ||
+        Array.isArray(call) ||
+        call.operation !== "list_classes")
+        return call;
+    const response = call.response;
+    if (typeof response !== "object" ||
+        response === null ||
+        Array.isArray(response) ||
+        !Array.isArray(response.content))
+        return call;
+    let elided = false;
+    const content = response.content.map((entry) => {
+        if (typeof entry !== "object" ||
+            entry === null ||
+            Array.isArray(entry) ||
+            typeof entry.text !== "string")
+            return entry;
+        const summarized = elideInventoryText(entry.text);
+        if (summarized === undefined)
+            return entry;
+        elided = true;
+        return { ...entry, text: summarized };
+    });
+    return elided
+        ? { ...call, inventory_elided: true, response: { ...response, content } }
+        : call;
+};
+/**
+ * Retain the complete search Evidence — full raw provider calls included —
+ * in the session record, then deliver a bounded summary Evidence inline.
+ * Callers without a retaining session keep the complete inline delivery, so
+ * complete CLI JSON output is unchanged. Coverage metadata stays truthful in
+ * both copies: the examined inventory is never rewritten to matched-only.
+ */
+export const summarizeRetainedAndroidSearch = (evidence, recordEvidence) => {
+    if (recordEvidence === undefined)
+        return ok(evidence);
+    const recorded = recordEvidence(evidence);
+    if (!recorded.ok)
+        return recorded;
+    const subject = evidence.subject;
+    const raw = evidence.raw_result;
+    const summarized = raw === null ||
+        typeof raw !== "object" ||
+        Array.isArray(raw) ||
+        !Array.isArray(raw.calls)
+        ? raw
+        : {
+            ...raw,
+            complete_evidence_id: evidence.evidence_id,
+            calls: raw.calls.map(summarizeInventoryCall),
+        };
+    return ok(createEvidence(subject === null
+        ? undefined
+        : {
+            path: subject.local_path,
+            sha256: subject.digest.sha256,
+            format: subject.format,
+            ...(subject.architecture === null
+                ? {}
+                : { architecture: subject.architecture }),
+        }, evidence.provider, {
+        operation: evidence.operation,
+        parameters: evidence.parameters,
+        result: evidence.normalized_result,
+        rawResult: summarized,
+        confidence: evidence.confidence,
+        limitations: evidence.limitations,
+        locations: evidence.locations,
+        evidenceLinks: [evidence.evidence_id],
+    }));
+};

package/dist/application/binary/AnalysisProviderEvaluation.js

@@ -2,7 +2,7 @@ import { analysisProfileSchema, } from "../../domain/analysisProfile.js";
 import { AnalysisCancelledError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
-import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
+import { ABORTED, waitForAbortable } from "../../process/AbortablePromise.js";
 /** Resolve and validate one provider profile without starting its client. */
 export const evaluateAnalysisProviderCandidate = async (candidate, status, target, signal) => {
     if (signalIsAborted(signal))

package/dist/application/binary/AnalysisProviderRegistry.js

@@ -4,6 +4,7 @@ import { ProviderSelectionError, } from "../../domain/providerSelectionError.js"
 import { jsonObjectSchema } 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.
@@ -37,9 +38,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() {
@@ -74,7 +75,7 @@ export class AnalysisProviderRegistry {
         if (signalIsAborted(options.signal))
             return err(new AnalysisCancelledError("open_binary"));
         if (request === undefined &&
-            selector !== "auto" &&
+            this.#byId.has(selector) &&
             baseline.length > 0 &&
             baseline.every(({ targetSupport }) => targetSupport.status === "unsupported"))
             return ok({
@@ -146,6 +147,9 @@ export class AnalysisProviderRegistry {
                 throw new TypeError("Cancelled candidate evaluation disappeared");
             return result.value;
         });
+        const cleanupFailure = evaluations.find(({ profileError }) => profileError?.cleanupIncomplete === true)?.profileError;
+        if (cleanupFailure !== undefined)
+            return err(cleanupFailure);
         const statuses = evaluations.map(({ status }) => status);
         const usable = evaluations.filter((evaluation) => evaluation.profile !== undefined);
         if (usable.length === 0)
@@ -162,36 +166,47 @@ 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
-        ? {
-            status: "unknown",
-            code: null,
-            reason: "No target is open.",
-            diagnostics: {},
-        }
-        : cloneTargetSupport(provider.inspectTargetSupport(target)),
-    selected: false,
-    capabilities: provider
-        .capabilities()
-        .map((capability) => structuredClone(capability)),
-});
+const candidateStatus = (provider, target) => {
+    const readiness = provider.inspectReadinessSnapshot?.() ?? {
+        availability: provider.inspectAvailability(),
+        capabilities: provider.capabilities(),
+    };
+    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),
     };

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;

package/dist/application/binary/AnalysisSnapshotFiles.js

@@ -1,21 +1,87 @@
-import { parseAnalysisSnapshot, serializeAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { setImmediate } from "node:timers/promises";
+import { prepareSnapshotEntry, parsePreparedAnalysisSnapshot, serializeAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
 import { EvidenceFileError, EvidenceIntegrityError, } from "../../domain/evidenceErrors.js";
 import { err, ok } from "../../domain/result.js";
-import { readJsonFile, writeTextFile } from "../JsonFiles.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { readJsonObjectMembersFile, writeTextFile } from "../JsonFiles.js";
+import { RegularFileCleanupFailure } from "../RegularFileRead.js";
 /** Read and validate an analysis snapshot from the caller's path. */
-export const readAnalysisSnapshot = async (path) => {
-    const loaded = await readJsonFile(path);
-    if (!loaded.ok)
-        return loaded;
+export const readAnalysisSnapshot = async (path, signal, resources) => {
+    const entries = snapshotEntryReader("provider");
+    const workflows = snapshotEntryReader("workflow");
+    const header = {};
+    const metadata = new Map(["target", "binding", "evidence_bundle"].map((name) => [
+        name,
+        {
+            mode: "value",
+            begin: () => {
+                delete header[name];
+            },
+            accept: (value) => {
+                header[name] = value;
+            },
+            reject: (cause) => {
+                throw cause;
+            },
+        },
+    ]));
     try {
-        return ok(parseAnalysisSnapshot(loaded.value));
+        const loaded = await readJsonObjectMembersFile(path, [
+            new Map([
+                ["entries", entries.reader],
+                ["workflow_entries", workflows.reader],
+            ]),
+            metadata,
+        ], signal, resources);
+        if (!loaded.ok)
+            return loaded;
+        signal?.throwIfAborted();
+        const snapshot = parsePreparedAnalysisSnapshot(header, entries.finish(), workflows.finish());
+        // Deliver queued cancellation before handing a complete cache to the session.
+        await setImmediate();
+        signal?.throwIfAborted();
+        return ok(snapshot);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError("read_evidence_file", { cause }));
         return err(new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }));
     }
 };
+const snapshotEntryReader = (kind) => {
+    let seen = false;
+    let entries = [];
+    let failure;
+    const reader = {
+        mode: "array",
+        begin: () => {
+            seen = true;
+            entries = [];
+            failure = undefined;
+        },
+        accept: (value) => {
+            if (failure === undefined)
+                entries.push(prepareSnapshotEntry(value, kind));
+        },
+        reject: (cause) => {
+            failure ??= { cause };
+        },
+    };
+    return {
+        reader,
+        finish: () => {
+            if (!seen)
+                throw new TypeError(`Analysis snapshot ${kind === "provider" ? "entries" : "workflow_entries"} is missing`);
+            if (failure !== undefined)
+                throw failure.cause;
+            return entries;
+        },
+    };
+};
 /** Atomically write a deterministic analysis snapshot to the caller's path. */
-export const writeAnalysisSnapshot = async (snapshot, path, overwrite) => {
+export const writeAnalysisSnapshot = async (snapshot, path, overwrite, resources) => {
     let encoded;
     try {
         encoded = serializeAnalysisSnapshot(snapshot);
@@ -23,7 +89,7 @@ export const writeAnalysisSnapshot = async (snapshot, path, overwrite) => {
     catch (cause) {
         return err(new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }));
     }
-    return writeTextFile(encoded, path, overwrite);
+    return writeTextFile(encoded, path, overwrite, resources);
 };
 const snapshotValidationMessage = (cause) => cause instanceof TypeError
     ? cause.message