rea-agents 4.1.0 → 5.0.0

package/dist/application/WebRuntimeService.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { err, ok } from "../domain/result.js";
+import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
+import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
+/** Shared public workflows keep instrumentation and listener inspection independently selectable. */
+export class WebRuntimeService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Observe externally triggered execution; selection authorizes the declared instrumentation. */
+    async observe(rawInput, options) {
+        const operation = "observe_web_execution";
+        const parsed = parseInput(observeWebExecutionInputSchema, rawInput, operation, options);
+        if (!parsed.ok)
+            return parsed;
+        const result = await this.provider.observeExecution(parsed.value, options);
+        if (!result.ok)
+            return result;
+        const verified = webExecutionSchema.safeParse(result.value);
+        if (!verified.success)
+            return err(new AnalysisOutputError(operation, verified.error.message));
+        if (verified.data.target.target_id !== parsed.value.target_id ||
+            verified.data.window.requested_ms !== parsed.value.observation_ms)
+            return err(new AnalysisOutputError(operation, "Provider changed the selected target or requested window."));
+        return this.evidence(operation, parsed.value, verified.data, options);
+    }
+    /** Inspect one selected node's listener declarations without dispatching an event. */
+    async inspect(rawInput, options) {
+        const operation = "inspect_web_event_listeners";
+        const parsed = parseInput(inspectWebEventListenersInputSchema, rawInput, operation, options);
+        if (!parsed.ok)
+            return parsed;
+        const result = await this.provider.inspectEventListeners(parsed.value, options);
+        if (!result.ok)
+            return result;
+        const verified = webEventListenersSchema.safeParse(result.value);
+        if (!verified.success)
+            return err(new AnalysisOutputError(operation, verified.error.message));
+        if (verified.data.target.target_id !== parsed.value.target_id ||
+            verified.data.selected_node.selector !== parsed.value.selector)
+            return err(new AnalysisOutputError(operation, "Provider changed the selected target or node selector."));
+        return this.evidence(operation, parsed.value, verified.data, options);
+    }
+    evidence(operation, input, result, options) {
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        if (input.allowed_origins.length > 0 &&
+            !input.allowed_origins.includes(result.target.origin))
+            return err(new AnalysisOutputError(operation, "Provider returned a document outside the selected origin scope."));
+        return ok(createEvidence(undefined, this.provider.identity(), {
+            predicateType: `rea.${operation.replaceAll("_", "-")}`,
+            operation,
+            parameters: jsonObjectSchema.parse(input),
+            result: jsonValueSchema.parse(result),
+            confidence: "observed",
+            authority: "external-service",
+            limitations: result.limitations,
+        }));
+    }
+}
+const parseInput = (schema, rawInput, operation, options) => {
+    if (options?.signal?.aborted)
+        return err(new AnalysisCancelledError(operation));
+    const parsed = schema.safeParse(rawInput);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+};

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/{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, 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,9 +21,7 @@ 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"));
 /** Whether an operation is immutable and independent of provider UI state. */

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 { 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. */

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

@@ -1,3 +1,4 @@
+import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
 import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
 import { BinarySession } from "./BinarySession.js";
 import { SessionProviderRouter } from "./SessionProviderRouter.js";
@@ -7,4 +8,4 @@ import { SessionProviderRouter } from "./SessionProviderRouter.js";
  */
 export const composeBinarySession = (registry, auxiliaryProviders = []) => new BinarySession(registry instanceof SessionProviderRouter
     ? registry
-    : SessionProviderRouter.selectable(registry, auxiliaryProviders));
+    : SessionProviderRouter.selectable(registry, auxiliaryProviders), new InvestigationRecords());

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

@@ -1,8 +1,8 @@
-import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
-import { NoBinaryOpenError } from "../domain/configurationErrors.js";
-import { ProviderAdapterError } from "../domain/providerAdapterError.js";
-import {} from "../domain/analysisErrorBase.js";
-import { err, ok } from "../domain/result.js";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
 import { isSnapshotCacheable } from "./AnalysisSnapshotCache.js";
 /** Resolve capability, profile, and snapshot state before invoking a provider. */
 export const prepareSessionExecution = (input) => {
@@ -59,9 +59,11 @@ export const bindExecutionTarget = (result, operation, target) => {
     };
     if (result.value.subject !== null &&
         result.value.subject.sha256 !== target.sha256 &&
-        !isArtifactInventorySubject(operation, result.value.subject, target))
+        !isArtifactBundleSubject(operation, result.value.subject, target))
         return err(new ProviderAdapterError(result.value.provider.id, `${operation}:subject`));
     return ok({ ...result.value, subject: result.value.subject ?? subject });
 };
-const isArtifactInventorySubject = (operation, subject, target) => (operation === "inventory_artifact" || operation === "inspect_artifact") &&
+const isArtifactBundleSubject = (operation, subject, target) => (operation === "inventory_artifact" ||
+    operation === "inspect_artifact" ||
+    operation === "extract_artifact") &&
     subject.path === (target.sourcePath ?? target.path);

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

@@ -1,9 +1,9 @@
-import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
-import { parseBinaryTarget } from "./BinaryTargetResolver.js";
-import {} from "../domain/binaryTarget.js";
-import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
-import {} from "../domain/analysisErrorBase.js";
-import { err } from "../domain/result.js";
+import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../../domain/analysisSnapshot.js";
+import { parseBinaryTarget } from "../BinaryTargetResolver.js";
+import {} from "../../domain/binaryTarget.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err } from "../../domain/result.js";
 import { SessionProviderRouter } from "./SessionProviderRouter.js";
 /** Parse a target, resolve its provider route, and validate snapshot binding. */
 export const resolveSessionOpen = async (input) => {