rea-agents 1.6.0 → 2.0.0

package/dist/application/BinarySession.js

@@ -1,5 +1,6 @@
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
-import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
+import { analysisProfilesEqual, } from "../domain/analysisProfile.js";
+import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, ProviderAdapterError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { createEvidence } from "../domain/evidence.js";
 import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
@@ -7,27 +8,25 @@ 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";
-import { snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } 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";
+import { SessionProviderRouter, } from "./SessionProviderRouter.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
  *
- * Target transitions are serialized because each client dispatches Hopper API
- * work on its dedicated Python thread, and switching targets tears that bridge
- * down. A failed switch recreates the previous target instead of retaining a
- * client whose bridge was already shut down.
+ * Target transitions are serialized because switching targets tears down the
+ * active provider client. A failed switch recreates the previous target instead
+ * of retaining a client whose resources were already shut down.
  */
 export class BinarySession {
     provider;
     #active;
     #transition = Promise.resolve();
     #calls = new Set();
-    #createClient;
-    #providerIdentity;
-    #capabilities;
+    #providerRouter;
     #evidence = new EvidenceLedger({
         maxRecords: 10_000,
         maxBytes: 64 * 1024 * 1024,
@@ -36,46 +35,55 @@ export class BinarySession {
     #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"
+        this.#providerRouter =
+            provider instanceof SessionProviderRouter
                 ? provider
-                : (target) => provider.createClient(target);
-        this.#providerIdentity =
-            typeof provider === "function"
-                ? { id: "unidentified", name: "Unidentified provider", version: null }
-                : provider.identity();
-        this.#capabilities =
-            typeof provider === "function"
-                ? undefined
-                : new Map(provider
-                    .capabilities()
-                    .map((descriptor) => [descriptor.operation, descriptor]));
+                : SessionProviderRouter.legacy(provider, options);
     }
     /** Identify the provider producing evidence for this session. */
     providerIdentity(operation) {
+        const route = this.#currentRoute();
+        let selected = route.identity;
         if (operation !== undefined) {
-            const exact = this.#capabilities?.get(operation)?.provider;
+            const exact = route.capabilities?.get(operation)?.provider;
             if (exact !== undefined)
-                return structuredClone(exact);
-            if (enhancedToolNameSchema.safeParse(operation).success) {
+                selected = exact;
+            else if (enhancedToolNameSchema.safeParse(operation).success) {
                 const providers = new Map();
-                for (const descriptor of this.#capabilities?.values() ?? [])
+                for (const descriptor of route.capabilities?.values() ?? [])
                     if (descriptor.available &&
                         OFFICIAL_OPERATIONS.has(descriptor.operation))
                         providers.set(descriptor.provider.id, descriptor.provider);
                 if (providers.size === 1) {
                     const provider = providers.values().next().value;
                     if (provider !== undefined)
-                        return structuredClone(provider);
+                        selected = provider;
                 }
             }
         }
-        return structuredClone(this.#providerIdentity);
+        const profile = this.#active?.profile;
+        return structuredClone(profile !== null &&
+            profile !== undefined &&
+            profile.provider.id === selected.id
+            ? profile.provider
+            : selected);
+    }
+    /** Return the selected immutable profile, optionally scoped to an operation. */
+    analysisProfile(operation) {
+        const profile = this.#active?.profile;
+        if (profile === null || profile === undefined)
+            return undefined;
+        if (operation !== undefined &&
+            this.providerIdentity(operation).id !== profile.provider.id)
+            return undefined;
+        return structuredClone(profile);
+    }
+    /** Return opaque adapter metadata retained for legacy open_binary output. */
+    openCompatibility() {
+        return structuredClone(this.#active?.compatibility ?? {});
     }
     /** Observe runtime provider-health changes that affect discovery metadata. */
     onAvailabilityChanged(listener) {
@@ -104,20 +112,24 @@ export class BinarySession {
     }
     /** 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
+        const profile = this.#active?.profile ?? undefined;
+        if (target !== undefined && profile === undefined)
+            return err(new EvidenceIntegrityError("Analysis snapshots require a concrete provider analysis profile"));
+        return this.#snapshot.export(target, profile, 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));
+        const active = this.#active;
+        if (active?.profile === null)
+            return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
+        return this.#snapshot.import(snapshot, active === undefined
+            ? undefined
+            : { target: active.target, profile: active.profile }, (bundle) => this.#evidence.import(bundle));
     }
     /** Retain one validated immutable workspace revision for session resources. */
     retainInvestigationWorkspace(workspace) {
@@ -187,15 +199,31 @@ export class BinarySession {
             const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
             if (!parsed.ok)
                 return parsed;
+            const sameTarget = this.#active?.target.path === parsed.value.path &&
+                snapshotMatchesTarget(snapshotTarget(this.#active.target), parsed.value);
+            const resolvedRoute = sameTarget &&
+                options.providerId === undefined &&
+                this.#active !== undefined
+                ? ok(this.#active.route)
+                : await this.#providerRouter.resolve(parsed.value, options.providerId, options.signal);
+            if (!resolvedRoute.ok)
+                return resolvedRoute;
+            const route = resolvedRoute.value;
+            const { profile, compatibility } = route;
             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"));
+                (profile === null ||
+                    !snapshotMatchesBinding(options.snapshot, parsed.value, profile)))
+                return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the requested binary"));
+            if (this.#active === undefined &&
+                !this.#snapshot.matches(parsed.value, profile ?? undefined))
+                return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: staged target, provider, or analysis profile does not match"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            if (this.#active?.target.path === parsed.value.path &&
-                snapshotMatchesTarget(snapshotTarget(this.#active.target), parsed.value)) {
+            const activeProfile = this.#active?.profile;
+            const sameProfile = activeProfile === null || activeProfile === undefined
+                ? profile === null
+                : profile !== null && analysisProfilesEqual(activeProfile, profile);
+            if (sameTarget && sameProfile) {
                 if (options.snapshot !== undefined) {
                     const imported = this.importAnalysisSnapshot(options.snapshot);
                     if (!imported.ok)
@@ -207,7 +235,7 @@ export class BinarySession {
             const previous = this.#active;
             this.#active = undefined;
             await previous?.client.close();
-            const client = this.#createClient(parsed.value);
+            const client = route.createClient(parsed.value);
             const started = await client.execute("health", {}, options);
             if (!started.ok) {
                 await client.close();
@@ -219,9 +247,18 @@ export class BinarySession {
                 await this.#restore(previous);
                 return err(new AnalysisCancelledError("open_binary"));
             }
-            this.#active = { target: parsed.value, client };
+            this.#active = {
+                target: parsed.value,
+                client,
+                profile,
+                compatibility: structuredClone(compatibility),
+                route,
+            };
             this.#clearRuntimeAvailability();
-            this.#snapshot.select(parsed.value);
+            if (profile === null)
+                this.#snapshot.clear();
+            else
+                this.#snapshot.select(parsed.value, profile);
             if (options.snapshot !== undefined) {
                 const imported = this.importAnalysisSnapshot(options.snapshot);
                 if (!imported.ok) {
@@ -252,59 +289,74 @@ export class BinarySession {
     /** Describe the active binary session. */
     status() {
         const target = this.#active?.target;
+        const route = this.#currentRoute();
+        const configuredProvider = this.#providerRouter.configuredIdentity();
         const provider = {
-            id: this.#providerIdentity.id,
-            name: this.#providerIdentity.name,
-            version: this.#providerIdentity.version,
+            id: configuredProvider.id,
+            name: configuredProvider.name,
+            version: configuredProvider.version,
         };
-        const providers = new Map();
-        if (this.#capabilities === undefined)
-            providers.set(provider.id, provider);
-        else
-            for (const descriptor of this.#capabilities.values())
-                providers.set(descriptor.provider.id, descriptor.provider);
-        const providerList = [...providers.values()]
-            .sort((left, right) => left.id.localeCompare(right.id))
+        const providerList = this.#providerRouter
+            .providerIdentities(route)
             .map(({ id, name, version }) => ({ id, name, version }));
-        const capabilities = this.#capabilities === undefined
+        const capabilities = route.capabilities === undefined
             ? []
-            : [...this.#capabilities.values()]
+            : [...route.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,
-                reason: descriptor.reason,
-                input_contract_version: descriptor.inputContractVersion,
-                output_contract_version: descriptor.outputContractVersion,
-                pagination: descriptor.pagination,
-                exhaustive: descriptor.exhaustive,
-                effects: {
-                    mutates_artifact: descriptor.effects.mutatesArtifact,
-                    launches_process: descriptor.effects.launchesProcess,
-                    may_show_ui: descriptor.effects.mayShowUi,
-                    may_access_network: descriptor.effects.mayAccessNetwork,
-                    may_write_filesystem: descriptor.effects.mayWriteFilesystem,
-                    changes_permissions: descriptor.effects.changesPermissions,
-                    requires_root: descriptor.effects.requiresRoot,
-                },
-                limits: {
-                    max_results: descriptor.limits.maxResults,
-                    max_payload_bytes: descriptor.limits.maxPayloadBytes,
-                    timeout_ms: descriptor.limits.timeoutMs,
+                .map((descriptor) => capabilityStatus(descriptor));
+        const analysisProviderBinding = route.binding === null
+            ? null
+            : {
+                provider: {
+                    id: route.binding.identity.id,
+                    name: route.binding.identity.name,
+                    version: route.binding.identity.version,
                 },
-                limitations: [...descriptor.limitations],
-            }));
+                selection_source: route.binding.selectionSource,
+                analysis_profile: structuredClone(route.binding.profile),
+            };
+        const analysisProviderCandidates = this.#providerRouter
+            .candidateStatuses(route)
+            .map((candidate) => ({
+            provider: {
+                id: candidate.provider.id,
+                name: candidate.provider.name,
+                version: candidate.provider.version,
+            },
+            availability: {
+                status: candidate.availability.status,
+                code: candidate.availability.code,
+                reason: candidate.availability.reason,
+                diagnostics: structuredClone(candidate.availability.diagnostics),
+            },
+            target_support: {
+                status: candidate.targetSupport.status,
+                code: candidate.targetSupport.code,
+                reason: candidate.targetSupport.reason,
+                diagnostics: structuredClone(candidate.targetSupport.diagnostics),
+            },
+            selected: candidate.selected,
+            capabilities: candidate.capabilities
+                .slice()
+                .sort((left, right) => left.operation.localeCompare(right.operation))
+                .map((descriptor) => capabilityStatus(descriptor)),
+        }));
+        const common = {
+            provider,
+            providers: providerList,
+            capabilities,
+            analysis_provider_binding: analysisProviderBinding,
+            analysis_provider_candidates: analysisProviderCandidates,
+        };
         return target === undefined
-            ? { open: false, provider, providers: providerList, capabilities }
+            ? { open: false, ...common }
             : {
                 open: true,
-                provider,
-                providers: providerList,
-                capabilities,
+                ...common,
                 path: target.path,
                 sha256: target.sha256,
                 format: target.format,
@@ -312,14 +364,14 @@ export class BinarySession {
                 architecture: target.architecture ?? null,
             };
     }
-    /** Return the immutable artifact identity captured before Hopper launched. */
+    /** Return the immutable artifact identity captured before its provider started. */
     activeTarget() {
         return this.#active === undefined
             ? undefined
             : structuredClone(this.#active.target);
     }
     /**
-     * Invoke a Hopper tool against the active target.
+     * Invoke a provider operation against the active target.
      * Calls may overlap, but a pending target transition prevents new calls from
      * entering until the transition has settled.
      */
@@ -327,15 +379,26 @@ export class BinarySession {
         const transitioned = await this.#waitForTransition(name, options?.signal);
         if (!transitioned.ok)
             return transitioned;
-        const capability = this.#capabilities?.get(name);
-        if (this.#capabilities !== undefined && capability?.available !== true)
-            return err(new AnalysisCapabilityUnavailableError(this.#providerIdentity.id, name, capability?.reason ?? "operation is not declared by this provider"));
         const active = this.#active;
         if (active === undefined)
             return err(new NoBinaryOpenError());
-        const cacheable = isSnapshotCacheable(name, capability, arguments_);
+        const capability = active.route.capabilities?.get(name);
+        if (active.route.capabilities !== undefined &&
+            capability?.available !== true) {
+            const selectionError = this.#providerRouter.unboundOperationError(name, active.route);
+            if (selectionError !== undefined)
+                return err(selectionError);
+            return err(new AnalysisCapabilityUnavailableError(active.route.binding?.identity.id ?? active.route.identity.id, name, capability?.reason ?? "operation is not declared by this provider"));
+        }
+        const profile = active.profile !== null &&
+            (capability === undefined ||
+                capability.provider.id === active.profile.provider.id)
+            ? active.profile
+            : undefined;
+        const cacheable = profile !== undefined &&
+            isSnapshotCacheable(name, capability, arguments_);
         const cached = cacheable
-            ? this.#snapshot.lookup(active.target, name, arguments_, capability.provider)
+            ? this.#snapshot.lookup(active.target, profile, name, arguments_)
             : undefined;
         if (cached !== undefined)
             return ok(cached);
@@ -343,14 +406,21 @@ export class BinarySession {
         this.#calls.add(call);
         try {
             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) {
+            const profiled = commitExecutionProfile(name, result, profile);
+            this.#observeRuntimeAvailability(name, profiled);
+            if (profiled.ok && cacheable)
+                this.#snapshot.record({
+                    target: active.target,
+                    profile,
+                    operation: name,
+                    parameters: arguments_,
+                    execution: profiled.value,
+                });
+            else if (profiled.ok && capability?.effects.mutatesArtifact === true) {
                 this.#snapshot.clear();
                 this.#snapshotInvalidated = true;
             }
-            return result;
+            return profiled;
         }
         finally {
             this.#calls.delete(call);
@@ -373,9 +443,10 @@ export class BinarySession {
             "HopperStartError",
             "HopperRemoteError",
         ].includes(result.error._tag)) {
-            const providerId = this.#capabilities?.get(operation)?.provider.id;
+            const capabilities = this.#active?.route.capabilities;
+            const providerId = capabilities?.get(operation)?.provider.id;
             let changed = false;
-            for (const descriptor of this.#capabilities?.values() ?? [])
+            for (const descriptor of capabilities?.values() ?? [])
                 if (providerId !== undefined && descriptor.provider.id === providerId)
                     changed =
                         this.#setRuntimeAvailability(descriptor.operation, false, "Provider became unavailable during this session.") || changed;
@@ -414,6 +485,9 @@ export class BinarySession {
             }
         }
     }
+    #currentRoute() {
+        return this.#active?.route ?? this.#providerRouter.initialRoute();
+    }
     #serialize(operation) {
         const result = this.#transition.then(operation, operation);
         this.#transition = result.then(() => undefined, () => undefined);
@@ -425,10 +499,16 @@ export class BinarySession {
     async #restore(previous) {
         if (previous === undefined)
             return;
-        const client = this.#createClient(previous.target);
+        const client = previous.route.createClient(previous.target);
         const started = await client.execute("health", {});
         if (started.ok)
-            this.#active = { target: previous.target, client };
+            this.#active = {
+                target: previous.target,
+                client,
+                profile: previous.profile,
+                compatibility: previous.compatibility,
+                route: previous.route,
+            };
         else
             await client.close();
     }
@@ -459,3 +539,40 @@ export class BinarySession {
     }
 }
 const isAborted = (signal) => signal?.aborted === true;
+const commitExecutionProfile = (operation, result, profile) => {
+    if (!result.ok || profile === undefined)
+        return result;
+    const provider = result.value.provider;
+    if (provider.id !== profile.provider.id ||
+        provider.name !== profile.provider.name ||
+        provider.version !== profile.provider.version)
+        return err(new ProviderAdapterError(profile.provider.id, `${operation}:profile`));
+    return ok({
+        ...result.value,
+        analysisProfile: structuredClone(profile),
+    });
+};
+const capabilityStatus = (descriptor) => ({
+    operation: descriptor.operation,
+    available: descriptor.available,
+    reason: descriptor.reason,
+    input_contract_version: descriptor.inputContractVersion,
+    output_contract_version: descriptor.outputContractVersion,
+    pagination: descriptor.pagination,
+    exhaustive: descriptor.exhaustive,
+    effects: {
+        mutates_artifact: descriptor.effects.mutatesArtifact,
+        launches_process: descriptor.effects.launchesProcess,
+        may_show_ui: descriptor.effects.mayShowUi,
+        may_access_network: descriptor.effects.mayAccessNetwork,
+        may_write_filesystem: descriptor.effects.mayWriteFilesystem,
+        changes_permissions: descriptor.effects.changesPermissions,
+        requires_root: descriptor.effects.requiresRoot,
+    },
+    limits: {
+        max_results: descriptor.limits.maxResults,
+        max_payload_bytes: descriptor.limits.maxPayloadBytes,
+        timeout_ms: descriptor.limits.timeoutMs,
+    },
+    limitations: [...descriptor.limitations],
+});

package/dist/application/CapabilityInventory.js

@@ -44,6 +44,7 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
             available: availability.reason === "available",
             reason: availability.reason,
             remediation: availability.remediation,
+            effects: { ...contract.effects },
             annotations: {
                 read_only: contract.annotations.readOnlyHint ?? false,
                 destructive: contract.annotations.destructiveHint ?? false,
@@ -59,6 +60,23 @@ const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy
             reason: "policy_disabled",
             remediation: "Enable or grant process_capture within the administrator ceiling.",
         };
+    if (name === "run_controlled_replay" && !policy.javascriptReplayEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable javascript_replay with exact source roots and sandbox executables.",
+        };
+    if (name === "run_controlled_replay")
+        return { reason: "available", remediation: null };
+    if (name === "plan_managed_runtime_correlation" &&
+        !policy.managedRuntimeEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable managed_runtime with exact artifact roots and a runtime executable.",
+        };
+    if (name === "plan_managed_runtime_correlation")
+        return { reason: "available", remediation: null };
+    if (kind === "application")
+        return { reason: "available", remediation: null };
     if (name === "import_evidence_bundle" && policy.evidenceFileRoots === 0)
         return {
             reason: "policy_disabled",

package/dist/application/CompositeProvider.js

@@ -1,8 +1,9 @@
-import { ProviderSelectionError } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
-const compositeIdentity = (providers) => ({
-    id: `composite:${providers
-        .map((provider) => provider.identity().id)
+/** Synthetic compatibility identity for a deterministic provider set. */
+export const compositeProviderIdentity = (identities) => ({
+    id: `composite:${identities
+        .map(({ id }) => id)
         .sort()
         .join("+")}`,
     name: "REA composite analysis provider",
@@ -14,11 +15,16 @@ export class CompositeProvider {
     #identity;
     #capabilities;
     #providerByOperation;
+    #profileProvider;
     constructor(providers) {
         this.providers = providers;
         if (providers.length === 0)
             throw new RangeError("CompositeProvider requires at least one provider");
-        this.#identity = Object.freeze(compositeIdentity(providers));
+        const profileProviders = providers.filter(({ resolveAnalysisProfile }) => resolveAnalysisProfile !== undefined);
+        if (profileProviders.length > 1)
+            throw new TypeError("CompositeProvider supports at most one target-bound analysis profile");
+        this.#profileProvider = profileProviders[0];
+        this.#identity = Object.freeze(compositeProviderIdentity(providers.map((provider) => provider.identity())));
         const routes = new Map();
         const capabilities = [];
         for (const provider of providers) {
@@ -39,13 +45,19 @@ export class CompositeProvider {
     capabilities() {
         return this.#capabilities;
     }
-    createClient(target) {
+    resolveAnalysisProfile(target, options) {
+        const resolve = this.#profileProvider?.resolveAnalysisProfile;
+        return resolve === undefined
+            ? Promise.resolve(ok({ profile: null, compatibility: {} }))
+            : resolve.call(this.#profileProvider, target, options);
+    }
+    createClient(target, profile) {
         const clients = new Map();
         const clientFor = (provider) => {
             const existing = clients.get(provider);
             if (existing !== undefined)
                 return existing;
-            const created = provider.createClient(target);
+            const created = provider.createClient(target, profile?.provider.id === provider.identity().id ? profile : undefined);
             clients.set(provider, created);
             return created;
         };
@@ -62,7 +74,7 @@ export class CompositeProvider {
                     }));
                 const provider = this.#providerByOperation.get(operation);
                 return provider === undefined
-                    ? Promise.resolve(err(new ProviderSelectionError(operation)))
+                    ? Promise.resolve(err(new AnalysisCapabilityUnavailableError(this.#identity.id, operation, "operation is not declared by this provider set")))
                     : clientFor(provider).execute(operation, parameters, options);
             },
             close: async () => {

package/dist/application/CrossVersionInvestigation.js

@@ -14,16 +14,20 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         return err(new AnalysisInputError("find_changed_behavior", {
             cause: parsed.error,
         }));
-    const initial = await readInvestigationWorkspace(parsed.data.workspace_path, policy);
+    return runCrossVersionInvestigationValidated(parsed.data, policy, execution);
+};
+/** Run input already parsed by a trusted adapter boundary. */
+export const runCrossVersionInvestigationValidated = async (input, policy, execution) => {
+    const initial = await readInvestigationWorkspace(input.workspace_path, policy);
     if (!initial.ok)
         return initial;
-    const preflight = validateWorkspaceRequest(initial.value, parsed.data);
+    const preflight = validateWorkspaceRequest(initial.value, input);
     if (!preflight.ok)
         return preflight;
     if (isCancelled(execution.signal))
         return err(new AnalysisCancelledError("find_changed_behavior"));
-    if (parsed.data.replay_run_id !== undefined) {
-        const replay = selectCompletedInvestigationReplay(initial.value, parsed.data);
+    if (input.replay_run_id !== undefined) {
+        const replay = selectCompletedInvestigationReplay(initial.value, input);
         if (!replay.ok)
             return replay;
         return completeOutcome(replay.value.workspace, replay.value.run, true, execution.session);
@@ -39,7 +43,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         total: 4,
         message: "Scanning both version inputs",
     });
-    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal, execution.integrityContinueEnabled);
+    const snapshots = await scanVersions(input, execution.inputRoots, execution.signal, execution.integrityContinueEnabled);
     if (!snapshots.ok)
         return snapshots;
     await execution.progress?.report({
@@ -49,7 +53,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         message: "Version inputs scanned",
     });
     return continueInvestigation({
-        input: parsed.data,
+        input,
         initial: initial.value,
         snapshots: snapshots.value,
         policy,