rea-agents 1.2.0 → 1.4.0

package/dist/application/AnalysisSnapshotCache.js

@@ -0,0 +1,131 @@
+import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+const STATEFUL_OPERATIONS = new Set([
+    "health",
+    "current_address",
+    "current_procedure",
+    "current_document",
+    "goto_address",
+    "list_documents",
+    "set_current_document",
+]);
+const CURSOR_DEFAULT_OPERATIONS = new Set([
+    "address_name",
+    "comment",
+    "inline_comment",
+    "next_address",
+    "prev_address",
+    "xrefs",
+]);
+const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
+    name !== "list_documents" &&
+    name !== "set_current_document"));
+/** Whether an operation is immutable and independent of provider UI state. */
+export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATEFUL_OPERATIONS.has(operation) &&
+    (!DOCUMENT_SCOPED_OPERATIONS.has(operation) ||
+        typeof parameters.document === "string") &&
+    (!CURSOR_DEFAULT_OPERATIONS.has(operation) ||
+        typeof parameters.address === "string") &&
+    descriptor?.effects.mutatesArtifact === false &&
+    descriptor.effects.mayWriteFilesystem === false &&
+    descriptor.effects.changesPermissions === false;
+/** Bounded in-memory cache for one immutable binary identity. */
+export class AnalysisSnapshotCache {
+    #entries = new Map();
+    #target;
+    /** Whether staged entries belong to the supplied binary. */
+    matches(target) {
+        return (this.#target === undefined || snapshotMatchesTarget(this.#target, target));
+    }
+    /** Replace cache state when the active binary identity changes. */
+    select(target) {
+        if (!this.matches(target))
+            this.#entries.clear();
+        this.#target = snapshotTarget(target);
+    }
+    /** Merge already-validated entries and return the new-entry count. */
+    stage(snapshot) {
+        if (this.#target !== undefined &&
+            (this.#target.sha256 !== snapshot.target.sha256 ||
+                this.#target.format !== snapshot.target.format ||
+                this.#target.architecture !== snapshot.target.architecture))
+            this.#entries.clear();
+        this.#target = snapshot.target;
+        let imported = 0;
+        for (const entry of snapshot.entries) {
+            if (!this.#entries.has(entry.query_id))
+                imported += 1;
+            this.#entries.set(entry.query_id, entry);
+        }
+        return imported;
+    }
+    /** Build a complete snapshot for an active target. */
+    export(target, evidenceBundle) {
+        if (target === undefined)
+            return err(new NoBinaryOpenError());
+        return ok({
+            snapshot_version: 1,
+            target: snapshotTarget(target),
+            entries: this.entries(),
+            evidence_bundle: evidenceBundle,
+        });
+    }
+    /** Validate target identity, merge evidence atomically, then stage entries. */
+    import(snapshot, active, mergeEvidence) {
+        if (active !== undefined && !snapshotMatchesTarget(snapshot.target, active))
+            return err(new EvidenceIntegrityError("Analysis snapshot target does not match the active binary"));
+        const importedEvidence = mergeEvidence(snapshot.evidence_bundle);
+        return importedEvidence.ok ? ok(this.stage(snapshot)) : importedEvidence;
+    }
+    /** Return canonical entries for persistence. */
+    entries() {
+        return [...this.#entries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+    }
+    /** Replay an exact provider-specific query, marking its cached provenance. */
+    lookup(target, operation, parameters, provider) {
+        const queryId = analysisQueryId(snapshotTarget(target), operation, parameters, provider);
+        const cached = this.#entries.get(queryId);
+        if (cached === undefined)
+            return undefined;
+        const subject = cached.execution.subject;
+        return {
+            result: cached.execution.result,
+            rawResult: cached.execution.raw_result,
+            provider: cached.execution.provider,
+            limitations: [
+                ...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,
+                    },
+        };
+    }
+    /** Record one successful immutable call unless the cache is full. */
+    record(target, operation, parameters, execution) {
+        if (this.#entries.size >= 10_000)
+            return;
+        this.select(target);
+        const entry = createAnalysisSnapshotEntry(snapshotTarget(target), operation, parameters, execution);
+        this.#entries.set(entry.query_id, entry);
+    }
+    /** Forget all target-bound entries. */
+    clear() {
+        this.#entries.clear();
+        this.#target = undefined;
+    }
+}

package/dist/application/AnalysisSnapshotFiles.js

@@ -0,0 +1,31 @@
+import { parseAnalysisSnapshot, serializeAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
+import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { readBoundedJson, writeBoundedText } from "./BoundedJsonFiles.js";
+/** Read and validate a bounded analysis snapshot inside an approved root. */
+export const readAnalysisSnapshot = async (path, policy) => {
+    const loaded = await readBoundedJson(path, policy);
+    if (!loaded.ok)
+        return loaded;
+    try {
+        return ok(parseAnalysisSnapshot(loaded.value));
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+            cause,
+        }));
+    }
+};
+/** Atomically write a deterministic analysis snapshot inside an approved root. */
+export const writeAnalysisSnapshot = async (snapshot, path, overwrite, policy) => {
+    let encoded;
+    try {
+        encoded = serializeAnalysisSnapshot(snapshot);
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+            cause,
+        }));
+    }
+    return writeBoundedText(encoded, path, overwrite, policy);
+};

package/dist/application/ArtifactGraphConstruction.js

@@ -83,7 +83,7 @@ export const createArtifactNode = (input) => ({
     architecture: null,
     executable: input.executable,
     content_state: input.contentState,
-    limitations: [],
+    limitations: [...(input.limitations ?? [])],
 });
 export const rootOccurrenceFor = (node, declaredSize) => ({
     occurrence_id: `occ_${digestCanonical({ root: node.artifact_id })}`,

package/dist/application/ArtifactInventory.js

@@ -15,15 +15,28 @@ const NATIVE_MOUNT_DISABLED = {
     nativeMountApproved: false,
     nativeMountEnabled: false,
 };
+const STRICT_INTEGRITY_POLICY = {
+    mode: "fail",
+    approved: false,
+    enabled: false,
+    maxMismatches: 1,
+};
 /** Inventory one local artifact without extracting or mounting it. */
 export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED, options.integrity ?? STRICT_INTEGRITY_POLICY);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
+    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount, integrity);
+};
+/** Scan one already-canonical artifact path without resolving it again. */
+export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
+    if (integrity.mode === "record-and-continue" &&
+        (!integrity.approved || !integrity.enabled))
+        throw new ArtifactReaderFailure("unavailable", "Integrity continuation requires explicit approval and operator policy");
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()
@@ -31,7 +44,7 @@ export const scanArtifactInventory = async (inputPath, limits, signal, nativeMou
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
     const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
-        const { nodes, occurrences } = await scanReader(reader, limits, signal);
+        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, limits, signal, integrity);
         materializeDirectoryNodes(occurrences, nodes);
         const rootNode = createRootNode({
             path,
@@ -47,6 +60,36 @@ export const scanArtifactInventory = async (inputPath, limits, signal, nativeMou
             if (occurrence.parent_occurrence_id === null)
                 occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
         occurrences.unshift(rootOccurrence);
+        const occurrenceById = new Map(occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]));
+        const integrityContradictions = pendingContradictions.map((contradiction) => {
+            const occurrence = occurrences.find(({ logical_path: path }) => path === contradiction.logicalPath);
+            if (occurrence === undefined)
+                throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
+            const parent = occurrence.parent_occurrence_id === null
+                ? undefined
+                : occurrenceById.get(occurrence.parent_occurrence_id);
+            const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;
+            return {
+                contradiction_id: `ic_${digestCanonical({
+                    root_artifact_id: rootNode.artifact_id,
+                    logical_path: contradiction.logicalPath,
+                    declared_sha256: contradiction.declaredSha256,
+                    observed_sha256: contradiction.observedSha256,
+                })}`,
+                occurrence_id: occurrence.occurrence_id,
+                parent_artifact_id: parentArtifactId,
+                logical_path: contradiction.logicalPath,
+                declared_sha256: contradiction.declaredSha256,
+                observed_sha256: contradiction.observedSha256,
+                entry_kind: contradiction.entryKind,
+                unpacked: contradiction.unpacked,
+                trust: "observed-untrusted",
+                provenance: "container-integrity-metadata-versus-observed-bytes",
+                limitations: [
+                    "Observed bytes contradict declared integrity metadata and cannot support equivalence.",
+                ],
+            };
+        });
         const edges = createArtifactEdges(rootNode.artifact_id, occurrences, reader?.provenance()[0]);
         const orderedNodes = [...nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
         const orderedOccurrences = occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
@@ -61,6 +104,7 @@ export const scanArtifactInventory = async (inputPath, limits, signal, nativeMou
             nodes: orderedNodes,
             occurrences: orderedOccurrences,
             edges: orderedEdges,
+            integrity_contradictions: integrityContradictions,
         });
         const manifestId = `agm_${digestCanonical({
             schema_version: 1,
@@ -84,7 +128,15 @@ export const scanArtifactInventory = async (inputPath, limits, signal, nativeMou
             edges: orderedEdges,
             limits: toOutputLimits(limits),
             provenance: reader?.provenance() ?? [],
-            limitations: inventoryLimitations(rootFormat, reader),
+            integrity_contradictions: integrityContradictions,
+            limitations: [
+                ...inventoryLimitations(rootFormat, reader),
+                ...(integrityContradictions.length === 0
+                    ? []
+                    : [
+                        `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
+                    ]),
+            ],
         };
     }
     finally {
@@ -145,11 +197,11 @@ const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
 const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
     logicalPath.toLowerCase().endsWith(".asar") &&
     entry.adapterKey.startsWith("/");
-const emptyScan = () => ({ nodes: new Map(), occurrences: [] });
-const scanReader = async (reader, limits, signal) => {
-    const { nodes, occurrences } = emptyScan();
+const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
+const scanReader = async (reader, limits, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+    const { nodes, occurrences, pendingContradictions } = emptyScan();
     if (reader === undefined)
-        return { nodes, occurrences };
+        return { nodes, occurrences, pendingContradictions };
     const occurrenceByPath = new Map();
     const registry = new ArtifactPathRegistry();
     let totalBytes = 0;
@@ -163,24 +215,44 @@ const scanReader = async (reader, limits, signal) => {
             throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
         const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
         totalBytes += digest.bytes;
-        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+        const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
+        if (mismatched && integrity.mode === "fail")
             throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
                 logicalPath,
                 declaredSha256: entry.declaredSha256,
                 calculatedSha256: digest.sha256,
                 unpacked: entry.unpacked,
             });
+        if (mismatched && entry.declaredSha256 !== null) {
+            if (pendingContradictions.length >= integrity.maxMismatches)
+                throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
+            pendingContradictions.push({
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                observedSha256: digest.sha256,
+                entryKind: entry.kind,
+                unpacked: entry.unpacked,
+            });
+        }
         const classified = entry.kind === "slice"
             ? { kind: "universal-slice", format: "mach-o" }
             : classifyArtifactContent(logicalPath, digest.prefix);
-        return createArtifactNode({
-            sha256: digest.sha256,
-            size: digest.bytes,
-            kind: classified.kind,
-            format: classified.format,
-            executable: entry.executable,
-            contentState: "embedded",
-        });
+        return {
+            node: createArtifactNode({
+                sha256: digest.sha256,
+                size: digest.bytes,
+                kind: classified.kind,
+                format: classified.format,
+                executable: entry.executable,
+                contentState: "embedded",
+                limitations: mismatched
+                    ? [
+                        "Observed content contradicts declared integrity metadata and is untrusted.",
+                    ]
+                    : [],
+            }),
+            mismatched,
+        };
     };
     const visit = async (currentReader, prefix) => {
         for await (const entry of currentReader.entries(signal)) {
@@ -192,20 +264,24 @@ const scanReader = async (reader, limits, signal) => {
             preflightEntry(entry, limits);
             const parent = nearestParent(logicalPath, occurrenceByPath);
             const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-            const node = await digestEntry(currentReader, entry, logicalPath);
-            if (node !== undefined) {
-                nodes.set(node.artifact_id, node);
-                occurrence.artifact_id = node.artifact_id;
-                occurrence.hash_status = "verified";
+            const digested = await digestEntry(currentReader, entry, logicalPath);
+            if (digested !== undefined) {
+                nodes.set(digested.node.artifact_id, digested.node);
+                occurrence.artifact_id = digested.node.artifact_id;
+                occurrence.hash_status = digested.mismatched
+                    ? "mismatched"
+                    : "verified";
+                if (digested.mismatched)
+                    occurrence.limitations.push("Declared integrity metadata contradicts observed bytes.");
             }
             occurrences.push(occurrence);
             occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar)
+            if (expandableAsar && digested?.mismatched !== true)
                 await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
     };
     await visit(reader, "");
-    return { nodes, occurrences };
+    return { nodes, occurrences, pendingContradictions };
 };
 const classifyRoot = async (path, directory) => {
     if (directory)

package/dist/application/AuthorizedArtifactInventory.js

@@ -0,0 +1,16 @@
+import { realpath } from "node:fs/promises";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
+import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
+/** Resolve, authorize, and scan one artifact without a second path resolution. */
+export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal, integrity) => {
+    if (roots.length === 0)
+        throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
+    const [path, approved] = await Promise.all([
+        realpath(inputPath),
+        Promise.all(roots.map(async (root) => realpath(root))),
+    ]);
+    if (!approved.some((root) => withinRoot(root, path)))
+        throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");
+    return scanCanonicalArtifactInventory(path, limits, signal, undefined, integrity);
+};

package/dist/application/BinarySession.js

@@ -2,15 +2,15 @@ import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { createEvidence } from "../domain/evidence.js";
+import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
 import { EvidenceLedger } from "./EvidenceLedger.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-const REGISTRY_PROVIDER = {
-    id: "rea-unknown-registry",
-    name: "REA residual unknown registry",
-    version: "1",
-};
+import { snapshotMatchesTarget } from "../domain/analysisSnapshot.js";
+import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
+import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
+import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
@@ -32,8 +32,15 @@ export class BinarySession {
         maxRecords: 10_000,
         maxBytes: 64 * 1024 * 1024,
     });
-    constructor(provider) {
+    #snapshot = new AnalysisSnapshotCache();
+    #investigationWorkspaces = new Map();
+    #runtimeAvailability = new Map();
+    #availabilityListeners = new Set();
+    #snapshotsEnabled;
+    #snapshotInvalidated = false;
+    constructor(provider, options = {}) {
         this.provider = provider;
+        this.#snapshotsEnabled = options.snapshotsEnabled ?? true;
         this.#createClient =
             typeof provider === "function"
                 ? provider
@@ -70,6 +77,11 @@ export class BinarySession {
         }
         return this.#providerIdentity;
     }
+    /** Observe runtime provider-health changes that affect discovery metadata. */
+    onAvailabilityChanged(listener) {
+        this.#availabilityListeners.add(listener);
+        return () => this.#availabilityListeners.delete(listener);
+    }
     /** Add one successful public observation to the session ledger. */
     recordEvidence(evidence) {
         return this.#evidence.record(evidence);
@@ -90,6 +102,41 @@ export class BinarySession {
     importEvidenceBundle(bundle) {
         return this.#evidence.import(bundle);
     }
+    /** Export immutable cached calls and session evidence for the active target. */
+    exportAnalysisSnapshot() {
+        if (!this.#snapshotsEnabled)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments"));
+        if (this.#snapshotInvalidated)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations"));
+        const target = this.#active?.target;
+        return this.#snapshot.export(target, target === undefined
+            ? this.#evidence.export()
+            : evidenceBundleForTarget(this.#evidence.export(), target.sha256));
+    }
+    /** Stage validated cached calls for an identical binary and merge its evidence. */
+    importAnalysisSnapshot(snapshot) {
+        if (!this.#snapshotsEnabled)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments"));
+        return this.#snapshot.import(snapshot, this.#active?.target, (bundle) => this.#evidence.import(bundle));
+    }
+    /** Retain one validated immutable workspace revision for session resources. */
+    retainInvestigationWorkspace(workspace) {
+        const parsed = parseInvestigationWorkspace(workspace);
+        const key = `${parsed.workspace_id}:${String(parsed.revision)}`;
+        if (this.#investigationWorkspaces.has(key))
+            return "duplicate";
+        this.#investigationWorkspaces.set(key, parsed);
+        return "added";
+    }
+    /** Read one session-retained immutable workspace revision. */
+    investigationWorkspace(workspaceId, revision) {
+        return this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+    }
+    /** List retained workspace revisions in canonical identity order. */
+    investigationWorkspaces() {
+        return [...this.#investigationWorkspaces.values()].sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
+            left.revision - right.revision);
+    }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
         const evidence = unknownMutationEvidence(this.#active?.target, input);
@@ -101,7 +148,7 @@ export class BinarySession {
     }
     /** Update one unknown using compare-and-swap revision semantics. */
     updateUnknown(input) {
-        const evidence = createEvidence(this.#active?.target, REGISTRY_PROVIDER, {
+        const evidence = createEvidence(this.#active?.target, UNKNOWN_REGISTRY_PROVIDER, {
             predicateType: "rea.residual-unknown-mutation/v1",
             operation: "update_unknown",
             parameters: {
@@ -137,10 +184,21 @@ export class BinarySession {
             const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
             if (!parsed.ok)
                 return parsed;
+            if (options.snapshot !== undefined &&
+                !snapshotMatchesTarget(options.snapshot.target, parsed.value))
+                return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
+            if (this.#active === undefined && !this.#snapshot.matches(parsed.value))
+                return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            if (this.#active?.target.path === parsed.value.path)
+            if (this.#active?.target.path === parsed.value.path) {
+                if (options.snapshot !== undefined) {
+                    const imported = this.importAnalysisSnapshot(options.snapshot);
+                    if (!imported.ok)
+                        return imported;
+                }
                 return ok(parsed.value);
+            }
             await this.#drainCalls();
             const previous = this.#active;
             this.#active = undefined;
@@ -158,6 +216,18 @@ export class BinarySession {
                 return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = { target: parsed.value, client };
+            this.#clearRuntimeAvailability();
+            this.#snapshot.select(parsed.value);
+            if (options.snapshot !== undefined) {
+                const imported = this.importAnalysisSnapshot(options.snapshot);
+                if (!imported.ok) {
+                    this.#active = undefined;
+                    await client.close();
+                    await this.#restore(previous);
+                    return imported;
+                }
+            }
+            this.#snapshotInvalidated = false;
             return ok(parsed.value);
         });
     }
@@ -169,6 +239,9 @@ export class BinarySession {
             await this.#drainCalls();
             await previous?.client.close();
             this.#evidence.clear();
+            this.#snapshot.clear();
+            this.#snapshotInvalidated = false;
+            this.#clearRuntimeAvailability();
             return ok(null);
         });
     }
@@ -193,6 +266,10 @@ export class BinarySession {
             ? []
             : [...this.#capabilities.values()]
                 .sort((left, right) => left.operation.localeCompare(right.operation))
+                .map((descriptor) => ({
+                ...descriptor,
+                ...this.#runtimeAvailability.get(descriptor.operation),
+            }))
                 .map((descriptor) => ({
                 operation: descriptor.operation,
                 available: descriptor.available,
@@ -250,15 +327,78 @@ export class BinarySession {
         const active = this.#active;
         if (active === undefined)
             return err(new NoBinaryOpenError());
+        const cacheable = isSnapshotCacheable(name, capability, arguments_);
+        const cached = cacheable
+            ? this.#snapshot.lookup(active.target, name, arguments_, capability.provider)
+            : undefined;
+        if (cached !== undefined)
+            return ok(cached);
         const call = active.client.execute(name, arguments_, options);
         this.#calls.add(call);
         try {
-            return await call;
+            const result = await call;
+            this.#observeRuntimeAvailability(name, result);
+            if (result.ok && cacheable)
+                this.#snapshot.record(active.target, name, arguments_, result.value);
+            else if (result.ok && capability?.effects.mutatesArtifact === true) {
+                this.#snapshot.clear();
+                this.#snapshotInvalidated = true;
+            }
+            return result;
         }
         finally {
             this.#calls.delete(call);
         }
     }
+    #observeRuntimeAvailability(operation, result) {
+        if (result.ok) {
+            if (this.#setRuntimeAvailability(operation, true, null))
+                this.#emitAvailabilityChanged();
+            return;
+        }
+        if (result.error._tag === "AnalysisCapabilityUnavailableError") {
+            if (this.#setRuntimeAvailability(operation, false, result.error.message))
+                this.#emitAvailabilityChanged();
+            return;
+        }
+        if ([
+            "ProviderAdapterError",
+            "HopperProcessError",
+            "HopperStartError",
+            "HopperRemoteError",
+        ].includes(result.error._tag)) {
+            const providerId = this.#capabilities?.get(operation)?.provider.id;
+            let changed = false;
+            for (const descriptor of this.#capabilities?.values() ?? [])
+                if (providerId !== undefined && descriptor.provider.id === providerId)
+                    changed =
+                        this.#setRuntimeAvailability(descriptor.operation, false, "Provider became unavailable during this session.") || changed;
+            if (changed)
+                this.#emitAvailabilityChanged();
+        }
+    }
+    #setRuntimeAvailability(operation, available, reason) {
+        const current = this.#runtimeAvailability.get(operation);
+        if (current?.available === available && current.reason === reason)
+            return false;
+        if (available && current === undefined)
+            return false;
+        if (available)
+            this.#runtimeAvailability.delete(operation);
+        else
+            this.#runtimeAvailability.set(operation, { available, reason });
+        return true;
+    }
+    #clearRuntimeAvailability() {
+        if (this.#runtimeAvailability.size === 0)
+            return;
+        this.#runtimeAvailability.clear();
+        this.#emitAvailabilityChanged();
+    }
+    #emitAvailabilityChanged() {
+        for (const listener of this.#availabilityListeners)
+            listener();
+    }
     #serialize(operation) {
         const result = this.#transition.then(operation, operation);
         this.#transition = result.then(() => undefined, () => undefined);
@@ -303,31 +443,4 @@ export class BinarySession {
         });
     }
 }
-const unknownMutationEvidence = (target, input) => createEvidence(target, REGISTRY_PROVIDER, {
-    predicateType: "rea.residual-unknown-mutation/v1",
-    operation: "record_unknown",
-    parameters: {
-        domain: input.domain,
-        severity: input.severity,
-    },
-    result: {
-        action: "record",
-        question: input.question,
-        required_authority: input.required_authority,
-        required_confidence: input.required_confidence,
-    },
-    confidence: "derived",
-    authority: "analyst-inference",
-    evidenceLinks: unknownEvidenceLinks(input),
-    limitations: [
-        "Registry mutation evidence records analyst intent, not proof of the answer.",
-    ],
-});
-const unknownEvidenceLinks = (input) => [
-    ...input.supporting_evidence_ids,
-    ...input.contradicting_evidence_ids,
-    ...("resolution" in input && input.resolution !== null
-        ? input.resolution.evidence_ids
-        : []),
-].filter((id, index, values) => values.indexOf(id) === index);
 const isAborted = (signal) => signal?.aborted === true;

package/dist/application/BinarySessionPort.js

@@ -0,0 +1 @@
+export {};