rea-agents 1.2.0 → 1.3.0

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/ArtifactInventory.js

@@ -24,6 +24,10 @@ export const inventoryArtifact = async (inputPath, limits, page, options = {}) =
 export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
+    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount);
+};
+/** Scan one already-canonical artifact path without resolving it again. */
+export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()

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) => {
+    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);
+};

package/dist/application/BinarySession.js

@@ -2,15 +2,14 @@ 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";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
@@ -32,8 +31,12 @@ export class BinarySession {
         maxRecords: 10_000,
         maxBytes: 64 * 1024 * 1024,
     });
-    constructor(provider) {
+    #snapshot = new AnalysisSnapshotCache();
+    #snapshotsEnabled;
+    #snapshotInvalidated = false;
+    constructor(provider, options = {}) {
         this.provider = provider;
+        this.#snapshotsEnabled = options.snapshotsEnabled ?? true;
         this.#createClient =
             typeof provider === "function"
                 ? provider
@@ -90,6 +93,23 @@ 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));
+    }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
         const evidence = unknownMutationEvidence(this.#active?.target, input);
@@ -101,7 +121,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 +157,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 +189,17 @@ export class BinarySession {
                 return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = { target: parsed.value, client };
+            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 +211,8 @@ export class BinarySession {
             await this.#drainCalls();
             await previous?.client.close();
             this.#evidence.clear();
+            this.#snapshot.clear();
+            this.#snapshotInvalidated = false;
             return ok(null);
         });
     }
@@ -250,10 +294,23 @@ 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;
+            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);
@@ -303,31 +360,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 {};

package/dist/application/BoundedJsonFiles.js

@@ -0,0 +1,109 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { EvidenceFileError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Read bounded JSON data from a regular file beneath an approved root. */
+export const readBoundedJson = async (path, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("read", "disabled"));
+    try {
+        const canonicalPath = await realpath(resolve(path));
+        if (!(await isApproved(canonicalPath, policy.roots)))
+            return err(new EvidenceFileError("read", "outside-root"));
+        const stats = await lstat(canonicalPath);
+        if (!stats.isFile())
+            return err(new EvidenceFileError("read", "not-file"));
+        if (stats.size > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        const encoded = await readFile(canonicalPath);
+        if (encoded.byteLength > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded.toString("utf8"));
+        }
+        catch (cause) {
+            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+        }
+        const limits = validateJsonLimits(decoded, policy);
+        return limits.ok ? ok(decoded) : limits;
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("read", "io", { cause }));
+    }
+};
+/** Atomically write bounded text to a regular file beneath an approved root. */
+export const writeBoundedText = async (encoded, path, overwrite, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("write", "disabled"));
+    const bytes = Buffer.byteLength(encoded, "utf8");
+    if (bytes > policy.maxBytes)
+        return err(new EvidenceFileError("write", "too-large"));
+    try {
+        const requestedPath = resolve(path);
+        const canonicalParent = await realpath(dirname(requestedPath));
+        const destination = resolve(canonicalParent, basename(requestedPath));
+        if (!(await isApproved(destination, policy.roots)))
+            return err(new EvidenceFileError("write", "outside-root"));
+        const existing = await lstat(destination).catch((cause) => {
+            if (isFileNotFound(cause))
+                return undefined;
+            throw cause;
+        });
+        if (existing !== undefined) {
+            if (!overwrite)
+                return err(new EvidenceFileError("write", "exists"));
+            if (!existing.isFile() || existing.isSymbolicLink())
+                return err(new EvidenceFileError("write", "not-file"));
+        }
+        await writeFileAtomic(destination, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+            fsync: true,
+        });
+        return ok({ path: requestedPath, bytes });
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("write", "io", { cause }));
+    }
+};
+const isApproved = async (candidate, roots) => {
+    for (const configuredRoot of roots) {
+        const root = await realpath(resolve(configuredRoot));
+        const relation = relative(root, candidate);
+        if (relation === "" ||
+            (!relation.startsWith("..") && !isAbsolute(relation)))
+            return true;
+    }
+    return false;
+};
+const validateJsonLimits = (root, policy) => {
+    const pending = [
+        { value: root, depth: 0 },
+    ];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        nodes += 1;
+        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value === "string" &&
+            current.value.length > policy.maxStringLength)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value !== "object" || current.value === null)
+            continue;
+        for (const [key, value] of Object.entries(current.value)) {
+            if (key.length > policy.maxStringLength)
+                return err(new EvidenceFileError("read", "too-large"));
+            pending.push({ value, depth: current.depth + 1 });
+        }
+    }
+    return ok(null);
+};
+const isFileNotFound = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";

package/dist/application/CrossVersionInventory.js

@@ -0,0 +1,98 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { createEvidence } from "../domain/evidence.js";
+import { AnalysisCancelledError, ArtifactOperationError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { paginateArtifactInventory, } from "./ArtifactInventory.js";
+import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
+export const AUTOMATIC_RUN_LIMITATION = "Automatic cross-version runs compare shipped artifact structure only; they do not execute either version.";
+/** Authorize and scan both inputs once under the same bounded traversal policy. */
+export const scanVersions = async (input, inputRoots, signal) => {
+    try {
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError("find_changed_behavior"));
+        const limits = artifactLimits(input.options);
+        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal);
+        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal);
+        return ok({ left, right });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            return err(new ArtifactOperationError("inventory_artifact", cause.reason, cause.details));
+        return err(new ArtifactOperationError("inventory_artifact", "io"));
+    }
+};
+/** Project complete snapshots into bounded, comparable Evidence page sets. */
+export const createInventoryEvidencePages = (input, snapshots) => {
+    const left = inventoryPages(input.left_path, snapshots.left, input.options);
+    const right = inventoryPages(input.right_path, snapshots.right, input.options);
+    if (left.length > 100 || right.length > 100)
+        return err(new ArtifactOperationError("inventory_artifact", "limit"));
+    return ok({ left, right });
+};
+/** Reduce a snapshot to the content commitments used by run identity. */
+export const targetFor = (snapshot) => ({
+    root_sha256: snapshot.manifest.root_sha256,
+    graph_sha256: snapshot.manifest.graph_sha256,
+    manifest_id: snapshot.manifest.manifest_id,
+    format: snapshot.manifest.root_format,
+});
+/** Preserve scan and execution limitations in stable order. */
+export const runLimitations = (snapshots) => [
+    ...new Set([
+        ...snapshots.left.limitations.map((item) => `Left: ${item}`),
+        ...snapshots.right.limitations.map((item) => `Right: ${item}`),
+        AUTOMATIC_RUN_LIMITATION,
+    ]),
+].sort((left, right) => left.localeCompare(right));
+const inventoryPages = (path, snapshot, options) => {
+    const count = Math.max(1, Math.ceil(snapshot.nodes.length / options.page_size), Math.ceil(snapshot.occurrences.length / options.page_size), Math.ceil(snapshot.edges.length / options.page_size));
+    return Array.from({ length: count }, (_, index) => inventoryPage(path, snapshot, options, index * options.page_size));
+};
+const inventoryPage = (path, snapshot, options, offset) => {
+    const result = paginateArtifactInventory(snapshot, {
+        nodeOffset: offset,
+        nodeLimit: options.page_size,
+        occurrenceOffset: offset,
+        occurrenceLimit: options.page_size,
+        edgeOffset: offset,
+        edgeLimit: options.page_size,
+    });
+    return createEvidence({
+        path,
+        sha256: snapshot.manifest.root_sha256,
+        format: snapshot.manifest.root_format,
+    }, ARTIFACT_GRAPH_PROVIDER, {
+        operation: "inventory_artifact",
+        parameters: {
+            node_offset: offset,
+            node_limit: options.page_size,
+            occurrence_offset: offset,
+            occurrence_limit: options.page_size,
+            edge_offset: offset,
+            edge_limit: options.page_size,
+            max_entries: options.max_entries,
+            max_total_bytes: options.max_total_bytes,
+            max_entry_bytes: options.max_entry_bytes,
+            max_compression_ratio: options.max_compression_ratio,
+            max_depth: options.max_depth,
+            max_path_bytes: options.max_path_bytes,
+        },
+        result: jsonValueSchema.parse(result),
+        rawResult: null,
+        limitations: result.limitations,
+        locations: result.occurrences.items.map(({ logical_path: logicalPath }) => ({
+            kind: "artifact-path",
+            path: logicalPath,
+        })),
+    });
+};
+const artifactLimits = (options) => ({
+    maxEntries: options.max_entries,
+    maxTotalBytes: options.max_total_bytes,
+    maxEntryBytes: options.max_entry_bytes,
+    maxCompressionRatio: options.max_compression_ratio,
+    maxDepth: options.max_depth,
+    maxPathBytes: options.max_path_bytes,
+});