rea-agents 4.1.0 → 6.0.0

package/dist/application/WebScriptExportService.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { publishWebScripts } from "../browser/assets/PublishWebScripts.js";
+import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
+import { exportWebScriptsInputSchema, } from "../domain/webScriptExport.js";
+import { WebScriptExportError } from "../domain/webScriptExportError.js";
+import { WEB_SCRIPT_EXPORT_PROVIDER as PROVIDER } from "./InvestigationProviders.js";
+const OPERATION = "export_web_scripts";
+/** Export one local capture through the shared CLI/MCP application workflow. */
+export const exportWebScripts = async (rawInput, options = {}) => {
+    const input = exportWebScriptsInputSchema.safeParse(rawInput);
+    return input.success
+        ? exportWebScriptsValidated(input.data, options)
+        : err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(input.error.issues, rawInput)));
+};
+/** Publish input already parsed by a named adapter contract. */
+export const exportWebScriptsValidated = async (input, options = {}) => {
+    if (!isAbsolute(input.capture_path) || !isAbsolute(input.output_directory))
+        return err(new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: [],
+                reason: "invalid_format",
+                message: "capture_path and output_directory must be absolute filesystem paths on this host.",
+            },
+        ]));
+    try {
+        options.signal?.throwIfAborted();
+        const bytes = await readFile(input.capture_path, {
+            signal: options.signal,
+        });
+        const loaded = parseCapture(bytes);
+        if (!loaded.ok)
+            return loaded;
+        options.signal?.throwIfAborted();
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const result = await publishWebScripts(input, loaded.value, sha256, options.signal);
+        return ok(createEvidence({ path: input.capture_path, sha256, format: "file" }, PROVIDER, {
+            predicateType: "rea.web-script-export",
+            operation: OPERATION,
+            parameters: {
+                capture_path: input.capture_path,
+                output_directory: input.output_directory,
+            },
+            result: jsonValueSchema.parse(result),
+            rawResult: null,
+            confidence: "derived",
+            authority: "historical-reference",
+            limitations: result.limitations,
+            locations: [{ kind: "artifact-path", path: result.manifest.path }],
+            evidenceLinks: loaded.value.sourceEvidenceId === null
+                ? []
+                : [loaded.value.sourceEvidenceId],
+        }));
+    }
+    catch (cause) {
+        if (cause instanceof WebScriptExportError)
+            return err(cause);
+        if (options.signal?.aborted === true)
+            return err(new AnalysisCancelledError(OPERATION));
+        if (cause instanceof ArtifactReaderFailure)
+            return err(new WebScriptExportError(cause.reason, input.output_directory, cause.message));
+        if (cause instanceof z.ZodError)
+            return err(new AnalysisOutputError(OPERATION, cause.message, { cause }));
+        if (cause instanceof Error &&
+            "code" in cause &&
+            typeof cause.code === "string")
+            return err(new WebScriptExportError("io", `${input.capture_path} → ${input.output_directory}`, cause.message));
+        return err(new ProviderAdapterError(PROVIDER.id, OPERATION, {
+            cause,
+            diagnostics: {
+                capture_path: input.capture_path,
+                output_directory: input.output_directory,
+                error_name: cause instanceof Error ? cause.name : "UnknownError",
+                error_message: cause instanceof Error
+                    ? cause.message
+                    : typeof cause === "string"
+                        ? cause
+                        : "Unknown script export failure",
+            },
+        }));
+    }
+};
+const parseCapture = (bytes) => {
+    try {
+        const text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+        const json = safeParseJson(text);
+        if (!json.ok)
+            throw new TypeError(json.error);
+        return ok(selectScriptCapture(json.value));
+    }
+    catch (cause) {
+        return err(new AnalysisInputError(OPERATION, { cause }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_format",
+                message: cause instanceof Error
+                    ? cause.message
+                    : "Capture is not valid UTF-8 JSON evidence.",
+            },
+        ]));
+    }
+};

package/dist/application/WebSourceLocationService.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { selectedWebScriptArtifactsSchema, webArtifactFileSchema, } from "../domain/webScriptArtifacts.js";
+import { WEB_SOURCE_MAP_LIMITS, webSourceLocationInputSchema, webSourceLocationResultSchema, webSourceMapReportSchema, } from "../domain/webSourceLocation.js";
+import { webSourceOffset } from "../domain/webSourcePosition.js";
+import { capturedWebManifestIdentity, validateSelectedWebScript, } from "./ValidateSelectedWebScript.js";
+const OPERATION = "trace_web_source_location";
+const artifactsSchema = selectedWebScriptArtifactsSchema.extend({
+    sourceMap: z.strictObject({
+        file: webArtifactFileSchema,
+        url: z.string().min(1),
+        text: z.string(),
+    }),
+});
+const LIMITATIONS = [
+    "The source/map pairing and source-map URL context are caller-selected. Deployment authenticity and execution remain unknown.",
+    "Capture metadata and its Evidence reference are historical context; this trace independently verifies only the selected manifest, script and map bytes.",
+    "Source names and sourceRoot are reported declarations. Resolved URLs are derived by the pinned upstream codec; no original source is fetched or executed.",
+    "Embedded source hashes identify the UTF-8 encoding of decoded sourcesContent text, not an independently retained original file. Missing or out-of-range original content positions remain explicit.",
+    "Lookup returns all segments at the greatest generated position not greater than the selected point, including earlier lines and generated-only segments. A mapped point does not establish an executed range or UI causality.",
+    "Regular maps and inline indexed sections are supported. External section URLs are unsupported; unknown extensions are retained in raw map text and are not interpreted.",
+    "Complete evidence has a 4 MiB map, 32 MiB reply, 262144 decoded rows/segments and 64-level section budget. The owned codec has a 20-second deadline, 192 MiB old-generation heap and one V8 worker; cleanup may extend the deadline. V8 heap limits do not establish aggregate RSS limits.",
+];
+/** Join verified captured bytes with an explicitly selected source-map point. */
+export class WebSourceLocationService {
+    artifacts;
+    decoder;
+    constructor(artifacts, decoder) {
+        this.artifacts = artifacts;
+        this.decoder = decoder;
+    }
+    /** Shared CLI/MCP workflow preserves raw declarations and every equal-position match. */
+    async trace(rawInput, options) {
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const parsed = webSourceLocationInputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+        const input = parsed.data;
+        const admitted = admitContext(input);
+        if (!admitted.ok)
+            return admitted;
+        const loaded = await this.artifacts.load(input, options);
+        if (!loaded.ok)
+            return loaded;
+        const verified = artifactsSchema.safeParse(loaded.value);
+        if (!verified.success)
+            return invalidOutput("Artifact port returned malformed source/map evidence.");
+        const data = verified.data;
+        const bound = validateSelectedWebScript(input, data, OPERATION);
+        if (!bound.ok)
+            return bound;
+        const map = data.sourceMap;
+        const pairing = verifyPairing(input, data);
+        if (!pairing.ok)
+            return pairing;
+        const generatedOffset = pairing.value;
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const traced = await this.decoder.trace({
+            text: map.text,
+            path: map.file.path,
+            url: map.url,
+            position: input.generated_position,
+        }, options);
+        if (!traced.ok)
+            return traced;
+        const report = verifyReport(input, map.file.sha256, traced.value);
+        if (!report.ok)
+            return report;
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const normalized = webSourceLocationResultSchema.safeParse({
+            ...report.value,
+            manifest: capturedWebManifestIdentity(data),
+            source: {
+                ...data.sourceFile,
+                script_index: input.script_index,
+                script: bound.value,
+            },
+            source_map: { ...map.file, url: map.url, association: "caller-selected" },
+            generated_offset: generatedOffset,
+            source_authenticity: "unknown",
+            execution: "unknown",
+            limitations: LIMITATIONS,
+        });
+        if (!normalized.success)
+            return invalidOutput(normalized.error.message);
+        return ok(createEvidence({
+            path: data.sourceFile.path,
+            sha256: data.sourceFile.sha256,
+            format: "file",
+        }, {
+            id: "rea-web-source-location",
+            name: "REA captured source-map point trace",
+            version: "1",
+        }, {
+            operation: OPERATION,
+            parameters: jsonObjectSchema.parse(input),
+            result: normalized.data,
+            rawResult: { source_map_text: map.text },
+            confidence: "derived",
+            authority: "historical-reference",
+            limitations: LIMITATIONS,
+            locations: [
+                data.sourceFile.path,
+                data.manifestFile.path,
+                map.file.path,
+            ].map((path) => ({ kind: "artifact-path", path })),
+            evidenceLinks: data.manifest.source_evidence_id === null
+                ? []
+                : [data.manifest.source_evidence_id],
+        }));
+    }
+}
+const invalidOutput = (message) => err(new AnalysisOutputError(OPERATION, message));
+const invalid = (path, message) => err(new AnalysisInputError(OPERATION, undefined, [
+    { path, reason: "invalid_format", message },
+]));
+const admitContext = (input) => {
+    for (const [path, value] of [
+        ["manifest_path", input.manifest_path],
+        ["source_map.path", input.source_map.path],
+    ])
+        if (!isAbsolute(value))
+            return invalid(path.split("."), "Expected an absolute filesystem path on this host.");
+    if (!URL.canParse(input.source_map.url))
+        return invalid(["source_map", "url"], "Expected an absolute source-map URL context. Select its deployment context explicitly; no URL is fetched.");
+    return ok(null);
+};
+const verifyPairing = (input, data) => {
+    const map = data.sourceMap;
+    if (map.file.path !== input.source_map.path ||
+        map.url !== input.source_map.url ||
+        Buffer.byteLength(map.text) !== map.file.bytes ||
+        createHash("sha256").update(map.text).digest("hex") !== map.file.sha256 ||
+        map.file.bytes > WEB_SOURCE_MAP_LIMITS.mapBytes)
+        return invalidOutput("Artifact port changed the selected source-map byte identity or URL context.");
+    const generatedOffset = webSourceOffset(data.source, input.generated_position);
+    if (generatedOffset === undefined)
+        return invalid(["generated_position"], "Selected generated position is outside the retained script text (one-based lines; zero-based UTF-16 columns).");
+    return ok(generatedOffset);
+};
+const verifyReport = (input, sha256, value) => {
+    const report = webSourceMapReportSchema.safeParse(value);
+    if (!report.success)
+        return invalidOutput("Codec port returned malformed source-map point evidence.");
+    if (report.data.source_map_sha256 !== sha256 ||
+        report.data.url_context !== input.source_map.url ||
+        report.data.lookup.requested.line !== input.generated_position.line ||
+        report.data.lookup.requested.column !== input.generated_position.column)
+        return invalidOutput("Codec port changed the selected map, URL context or generated point.");
+    return ok(report.data);
+};

package/dist/application/WindowsCapabilities.js

@@ -3,7 +3,7 @@ import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
-import { probeProcessCaptureCapability, } from "./ProcessCaptureCapability.js";
+import { probeProcessCaptureCapability, } from "../process/capture/ProcessCaptureCapability.js";
 /** Probe named prerequisites without converting missing controls into support. */
 export const probeWindowsCapabilities = async (dependencies = systemDependencies()) => {
     const [symlinkCreation, pty] = await Promise.all([

package/dist/application/{AndroidAnalysisService.js → android/AndroidAnalysisService.js}

@@ -1,9 +1,9 @@
-import { parseBinaryTarget } from "./BinaryTargetResolver.js";
-import { androidRequestSchema, } from "../domain/androidAnalysis.js";
-import { AnalysisCancelledError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
-import { createEvidence } from "../domain/evidence.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { err, ok } from "../domain/result.js";
+import { parseBinaryTarget } from "../BinaryTargetResolver.js";
+import { androidRequestSchema, } from "../../domain/android/androidAnalysis.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
 /** Shared CLI/MCP admission, execution and Evidence composition for Android. */
 export class AndroidAnalysisService {
     provider;

package/dist/application/{AndroidApplicationService.js → android/AndroidApplicationService.js}

@@ -1,6 +1,6 @@
-import { androidApplicationProjectionInputSchema, projectAndroidApplication, } from "../domain/androidApplication.js";
-import { ANDROID_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
-import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+import { androidApplicationProjectionInputSchema, projectAndroidApplication, } from "../../domain/android/androidApplication.js";
+import { ANDROID_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
+import { projectInventoryEvidence } from "../InventoryProjectionEvidence.js";
 const OPERATION = "project_android_application_graph";
 /** Project authenticated APK inventory Evidence into Android application Evidence. */
 export const projectAndroidApplicationEvidence = (rawInput) => {

package/dist/application/{AppleApplicationService.js → apple/AppleApplicationService.js}

@@ -1,8 +1,8 @@
-import { appleApplicationProjectionInputSchema, projectAppleApplication, } from "../domain/appleApplication.js";
-import { APPLE_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
-import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+import { appleApplicationProjectionInputSchema, projectAppleApplication, } from "../../domain/apple/appleApplication.js";
+import { APPLE_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
+import { projectInventoryEvidence } from "../InventoryProjectionEvidence.js";
 const OPERATION = "project_apple_application_graph";
-/** Project authenticated IPA inventory Evidence into Apple application evidence. */
+/** Project authenticated IPA or macOS app inventory Evidence into Apple application evidence. */
 export const projectAppleApplicationEvidence = (rawInput) => {
     return projectInventoryEvidence({
         rawInput,
@@ -11,7 +11,7 @@ export const projectAppleApplicationEvidence = (rawInput) => {
         operation: OPERATION,
         predicateType: "rea.apple-application-graph",
         provider: APPLE_APPLICATION_PROVIDER,
-        subjectFormat: () => "ipa",
+        subjectFormat: (first) => first.subject?.format ?? "unknown",
         protocolError: "Apple application projection produced an invalid result",
     });
 };

package/dist/application/{AnalysisClientCleanup.js → binary/AnalysisClientCleanup.js}

@@ -1,5 +1,5 @@
-import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { err, ok } from "../domain/result.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok } from "../../domain/result.js";
 /** Close one provider client and normalize unexpected adapter rejection. */
 export const closeAnalysisClient = async (client, providerId, options = {}) => {
     try {

package/dist/application/{AnalysisProviderEvaluation.js → binary/AnalysisProviderEvaluation.js}

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

package/dist/application/{AnalysisProviderRegistry.js → binary/AnalysisProviderRegistry.js}

@@ -1,8 +1,8 @@
-import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../contracts/providerSelection.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
-import { ProviderSelectionError, } from "../domain/providerSelectionError.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { err, ok } from "../domain/result.js";
+import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../../contracts/providerSelection.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { ProviderSelectionError, } from "../../domain/providerSelectionError.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
 import { evaluateAnalysisProviderCandidate, } from "./AnalysisProviderEvaluation.js";
 /**
  * Discover and select overlapping deep providers without starting their clients.

package/dist/application/{AnalysisSnapshotCache.js → binary/AnalysisSnapshotCache.js}

@@ -1,9 +1,9 @@
-import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
-import { NoBinaryOpenError } from "../domain/configurationErrors.js";
-import {} from "../domain/analysisErrorBase.js";
-import { err, ok } from "../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, createAnalysisSnapshotWorkflowEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
     "current_address",
@@ -21,11 +21,11 @@ const CURSOR_DEFAULT_OPERATIONS = new Set([
     "prev_address",
     "xrefs",
 ]);
-const DOCUMENT_SCOPED_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy")
-    .map(({ name }) => name)
-    .filter((name) => name !== "current_document" &&
+const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
     name !== "list_documents" &&
     name !== "set_current_document"));
+/** Maximum duplicated result bindings retained across direct and workflow queries. */
+export const SNAPSHOT_CACHE_ENTRY_CEILING = 10_000;
 /** 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) ||
@@ -39,6 +39,7 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
 /** Bounded in-memory cache for one immutable binary identity. */
 export class AnalysisSnapshotCache {
     #entries = new Map();
+    #workflowEntries = new Map();
     #target;
     #binding;
     /** Whether staged entries belong to the supplied target and profile. */
@@ -53,7 +54,7 @@ export class AnalysisSnapshotCache {
     /** Replace cache state when the target or selected profile changes. */
     select(target, profile) {
         if (!this.matches(target, profile))
-            this.#entries.clear();
+            this.#clearEntries();
         this.#target = snapshotTarget(target);
         this.#binding = snapshotBinding(profile);
     }
@@ -63,15 +64,22 @@ export class AnalysisSnapshotCache {
             JSON.stringify(this.#target) !== JSON.stringify(snapshot.target)) ||
             (this.#binding !== undefined &&
                 !snapshotMatchesProfile(this.#binding, snapshot.binding.analysis_profile)))
-            this.#entries.clear();
+            this.#clearEntries();
         this.#target = structuredClone(snapshot.target);
         this.#binding = structuredClone(snapshot.binding);
         let imported = 0;
         for (const entry of snapshot.entries) {
+            if (!this.#entries.has(entry.query_id) && !this.#hasCapacity())
+                continue;
             if (!this.#entries.has(entry.query_id))
                 imported += 1;
             this.#entries.set(entry.query_id, structuredClone(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));
+        }
         return imported;
     }
     /** Build a complete snapshot for an active target. */
@@ -86,6 +94,9 @@ export class AnalysisSnapshotCache {
                 target: snapshotTargetIdentity,
                 binding,
                 entries: this.entries(),
+                ...(this.workflowEntries().length === 0
+                    ? {}
+                    : { workflow_entries: this.workflowEntries() }),
                 evidence_bundle: retainedEvidence,
             }));
         }
@@ -119,6 +130,27 @@ export class AnalysisSnapshotCache {
             .sort((left, right) => left.query_id.localeCompare(right.query_id))
             .map((entry) => structuredClone(entry));
     }
+    /** Return canonical composed-workflow entries for persistence. */
+    workflowEntries() {
+        return [...this.#workflowEntries.values()]
+            .sort((left, right) => left.query_id.localeCompare(right.query_id))
+            .map((entry) => structuredClone(entry));
+    }
+    /** Record one exact derived workflow result unless the shared cache is full. */
+    recordWorkflow(input) {
+        this.select(input.target, input.profile);
+        const queryId = analysisQueryId(snapshotTarget(input.target), snapshotBinding(input.profile), input.operation, input.parameters);
+        if (!this.#workflowEntries.has(queryId) && !this.#hasCapacity())
+            return;
+        const entry = createAnalysisSnapshotWorkflowEntry({
+            target: snapshotTarget(input.target),
+            binding: snapshotBinding(input.profile),
+            operation: input.operation,
+            parameters: input.parameters,
+            execution: input.execution,
+        });
+        this.#workflowEntries.set(entry.query_id, entry);
+    }
     /** Replay an exact provider-specific query, marking its cached provenance. */
     lookup(target, profile, operation, parameters) {
         const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
@@ -155,9 +187,10 @@ export class AnalysisSnapshotCache {
     /** Record one successful immutable call unless the cache is full. */
     record(input) {
         const { target, profile, operation, parameters, execution } = input;
-        if (this.#entries.size >= 10_000)
-            return;
         this.select(target, profile);
+        const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
+        if (!this.#entries.has(queryId) && !this.#hasCapacity())
+            return;
         const entry = createAnalysisSnapshotEntry({
             target: snapshotTarget(target),
             binding: snapshotBinding(profile),
@@ -169,8 +202,16 @@ export class AnalysisSnapshotCache {
     }
     /** Forget all target-bound entries. */
     clear() {
-        this.#entries.clear();
+        this.#clearEntries();
         this.#target = undefined;
         this.#binding = undefined;
     }
+    #clearEntries() {
+        this.#entries.clear();
+        this.#workflowEntries.clear();
+    }
+    #hasCapacity() {
+        return (this.#entries.size + this.#workflowEntries.size <
+            SNAPSHOT_CACHE_ENTRY_CEILING);
+    }
 }

package/dist/application/{AnalysisSnapshotFiles.js → binary/AnalysisSnapshotFiles.js}

@@ -1,7 +1,7 @@
-import { parseAnalysisSnapshot, 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 { parseAnalysisSnapshot, 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";
 /** Read and validate an analysis snapshot from the caller's path. */
 export const readAnalysisSnapshot = async (path) => {
     const loaded = await readJsonFile(path);

package/dist/application/{BinarySession.js → binary/BinarySession.js}

@@ -1,18 +1,20 @@
 import { randomUUID } from "node:crypto";
-import { analysisProfilesEqual, } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
-import { err, ok } from "../domain/result.js";
-import { createEvidence } from "../domain/evidence.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { analysisProfilesEqual, } from "../../domain/analysisProfile.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
+import { ENHANCED_TOOL_CONTRACTS } from "../../contracts/enhancedToolContracts.js";
 import { SessionProviderRouter, } from "./SessionProviderRouter.js";
+import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
 import { BinarySessionRecords } from "./BinarySessionRecords.js";
 import { binarySessionStatus } from "./BinarySessionStatus.js";
-import { resolveSessionOpen, } from "./BinarySessionOpen.js";
+import { resolveSessionOpen, resolveSessionTarget, validateResolvedSessionTarget, } from "./BinarySessionOpen.js";
 import { bindExecutionTarget, commitExecutionProfile, prepareSessionExecution, } from "./BinarySessionExecution.js";
 import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
-const OFFICIAL_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy").map(({ name }) => name));
-const ENHANCED_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "enhanced").map(({ name }) => name));
+const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
+const ENHANCED_OPERATIONS = new Set(ENHANCED_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
  *
@@ -27,8 +29,8 @@ export class BinarySession extends BinarySessionRecords {
     #providerRouter;
     #runtimeUnavailability = new Map();
     #availabilityListeners = new Set();
-    constructor(providerRouter) {
-        super();
+    constructor(providerRouter, records = new InvestigationRecords()) {
+        super(records);
         this.#providerRouter = providerRouter;
     }
     /** Identify the provider producing evidence for this session. */
@@ -86,21 +88,47 @@ export class BinarySession extends BinarySessionRecords {
         this.#availabilityListeners.add(listener);
         return () => this.#availabilityListeners.delete(listener);
     }
+    /** Resolve a target and provider profile without creating a provider client. */
+    previewTarget(target, options = {}) {
+        if (isAborted(options.signal))
+            return Promise.resolve(err(new AnalysisCancelledError("open_binary")));
+        return resolveSessionTarget({
+            router: this.#providerRouter,
+            current: this.#active,
+            target,
+            options,
+            stagedSnapshotMatches: (target, profile) => this.matchesSnapshot(target, profile),
+        }).then((resolved) => isAborted(options.signal)
+            ? err(new AnalysisCancelledError("open_binary"))
+            : resolved);
+    }
     /**
      * Open or switch targets after draining calls against the current target.
      * Returns the switch failure even if best-effort restoration also fails.
      */
     open(path, options = {}) {
+        return this.#open(() => resolveSessionOpen({
+            router: this.#providerRouter,
+            current: this.#active,
+            path,
+            options,
+            stagedSnapshotMatches: (target, profile) => this.matchesSnapshot(target, profile),
+        }), options);
+    }
+    /** Open a previewed target without repeating parsing or provider profile discovery. */
+    openResolvedTarget(resolved, options = {}) {
+        return this.#open(() => Promise.resolve(validateResolvedSessionTarget({
+            ...resolved,
+            current: this.#active,
+            options,
+            stagedSnapshotMatches: (target, profile) => this.matchesSnapshot(target, profile),
+        })), options);
+    }
+    #open(resolve, options) {
         return this.#serialize(async () => {
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            const resolved = await resolveSessionOpen({
-                router: this.#providerRouter,
-                current: this.#active,
-                path,
-                options,
-                stagedSnapshotMatches: (target, profile) => this.matchesSnapshot(target, profile),
-            });
+            const resolved = await resolve();
             if (!resolved.ok)
                 return resolved;
             const { target, route, sameTarget } = resolved.value;
@@ -230,7 +258,8 @@ export class BinarySession extends BinarySessionRecords {
             unboundOperationError: (operation, route) => this.#providerRouter.unboundOperationError(operation, route),
             lookupSnapshot: (target, profile, operation, parameters) => operation === "decode_interface_builder" ||
                 operation === "inspect_asset_catalog" ||
-                operation === "inspect_keyed_archive"
+                operation === "inspect_keyed_archive" ||
+                operation === "trace_dylib_resolution"
                 ? undefined
                 : this.lookupSnapshot(target, profile, operation, parameters),
         });
@@ -250,7 +279,8 @@ export class BinarySession extends BinarySessionRecords {
                 profile !== undefined &&
                 name !== "decode_interface_builder" &&
                 name !== "inspect_asset_catalog" &&
-                name !== "inspect_keyed_archive") {
+                name !== "inspect_keyed_archive" &&
+                name !== "trace_dylib_resolution") {
                 const evidence = createEvidence(profiled.value.subject ?? active.target, profiled.value.provider, {
                     operation: name,
                     parameters: arguments_,