rea-agents 6.4.0 → 6.7.0

package/dist/application/binary/BinarySessionOpen.js

@@ -1,8 +1,6 @@
 import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../../domain/analysisSnapshot.js";
 import { parseBinaryTarget } from "../BinaryTargetResolver.js";
-import {} from "../../domain/binaryTargetTypes.js";
 import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } 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. */
@@ -15,6 +13,12 @@ export const resolveSessionOpen = async (input) => {
         ...(options.formatHint === undefined
             ? {}
             : { formatHint: options.formatHint }),
+        ...(options.architecture === undefined
+            ? {}
+            : { architecture: options.architecture }),
+        ...(options.entryPoint === undefined
+            ? {}
+            : { entryPoint: options.entryPoint }),
         ...(options.signal === undefined ? {} : { signal: options.signal }),
     });
     if (!parsed.ok)
@@ -24,8 +28,7 @@ export const resolveSessionOpen = async (input) => {
 /** Resolve a known target's provider route and validate snapshot binding. */
 export const resolveSessionTarget = async (input) => {
     const { router, current, target, options } = input;
-    const sameTarget = current?.target.path === target.path &&
-        snapshotMatchesTarget(snapshotTarget(current.target), target);
+    const sameTarget = sameSessionTarget(current?.target, target);
     const resolvedRoute = sameTarget && options.providerId === undefined && current !== undefined
         ? { ok: true, value: current.route }
         : await router.resolve(target, options.providerId, options.signal);
@@ -39,8 +42,7 @@ export const resolveSessionTarget = async (input) => {
 /** Revalidate a previewed route against the current session and snapshot binding. */
 export const validateResolvedSessionTarget = (input) => {
     const { current, target, route, options, stagedSnapshotMatches } = input;
-    const sameTarget = current?.target.path === target.path &&
-        snapshotMatchesTarget(snapshotTarget(current.target), target);
+    const sameTarget = sameSessionTarget(current?.target, target);
     const snapshotError = validateSnapshot({
         snapshot: options.snapshot,
         target,
@@ -52,6 +54,11 @@ export const validateResolvedSessionTarget = (input) => {
         return err(snapshotError);
     return { ok: true, value: { target, route, sameTarget } };
 };
+const sameSessionTarget = (current, target) => current !== undefined &&
+    current.path === target.path &&
+    // Native admission is bound to the requested path, not just its realpath.
+    (current.sourcePath ?? current.path) === (target.sourcePath ?? target.path) &&
+    snapshotMatchesTarget(snapshotTarget(current), target);
 const validateSnapshot = ({ snapshot, target, profile, current, stagedSnapshotMatches, }) => {
     if (snapshot !== undefined &&
         (profile === null || !snapshotMatchesBinding(snapshot, target, profile)))

package/dist/application/binary/BinarySessionRecords.js

@@ -1,14 +1,19 @@
 import { evidenceBundleForTarget } from "../../domain/evidenceBundle.js";
-import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
-import {} from "../../domain/analysisErrorBase.js";
-import {} from "../../domain/unknownRegistryError.js";
+import { EvidenceFileError, EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
 import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { writeAnalysisSnapshot as writeSnapshotFile } from "./AnalysisSnapshotFiles.js";
 const SNAPSHOT_MUTATION_RECOVERY = "Export session observations through export_evidence_bundle if needed. Close the active target without saving a snapshot, then reopen it before importing or saving a snapshot.";
 /** Own binary snapshots and coordinate the composed investigation records. */
 export class BinarySessionRecords {
     #records;
+    #writeResources = new ArtifactResourceScope();
+    get hasPendingFileResources() {
+        return this.#writeResources.hasPending;
+    }
     #snapshot = new AnalysisSnapshotCache();
     #snapshotInvalidated = false;
     #snapshotListeners = new Set();
@@ -43,6 +48,27 @@ export class BinarySessionRecords {
     evidenceBundleForSerialization() {
         return this.#records.evidenceBundleForSerialization();
     }
+    /** Persist one provider-neutral snapshot under this session's resource owner. */
+    writeAnalysisSnapshot(snapshot, path, overwrite) {
+        return writeSnapshotFile(snapshot, path, overwrite, this.#writeResources);
+    }
+    /** Retry and release staged snapshot files at the owning session shutdown. */
+    async closeWriteResources() {
+        try {
+            await this.#writeResources.retryCleanup();
+            return ok(null);
+        }
+        catch (cause) {
+            const observation = ArtifactReaderFailure.cleanupObservation(cause, "analysis snapshot staging");
+            return err(new EvidenceFileError("write", "io", {
+                cause,
+                cleanup: {
+                    reason: observation.reason,
+                    resources: observation.resources,
+                },
+            }));
+        }
+    }
     importEvidenceBundle(bundle) {
         const imported = this.#records.mergeEvidenceBundle(bundle);
         if (!imported.ok)
@@ -56,8 +82,8 @@ export class BinarySessionRecords {
     exportAnalysisSnapshot() {
         const active = this.activeAnalysisBinding();
         if (this.#snapshotInvalidated)
-            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations", {
-                userMessage: `Analysis snapshots are unavailable after analysis metadata mutations. ${SNAPSHOT_MUTATION_RECOVERY}`,
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable because analysis metadata may have changed", {
+                userMessage: `Analysis snapshots are unavailable because analysis metadata may have changed. ${SNAPSHOT_MUTATION_RECOVERY}`,
             }));
         const target = active?.target;
         const profile = active?.profile ?? undefined;
@@ -70,8 +96,8 @@ export class BinarySessionRecords {
     importAnalysisSnapshot(snapshot) {
         const active = this.activeAnalysisBinding();
         if (active !== undefined && this.#snapshotInvalidated)
-            return err(new EvidenceIntegrityError("Analysis snapshots cannot be imported after analysis metadata mutations", {
-                userMessage: `Analysis snapshots cannot be imported after analysis metadata mutations. ${SNAPSHOT_MUTATION_RECOVERY}`,
+            return err(new EvidenceIntegrityError("Analysis snapshots cannot be imported because analysis metadata may have changed", {
+                userMessage: `Analysis snapshots cannot be imported because analysis metadata may have changed. ${SNAPSHOT_MUTATION_RECOVERY}`,
             }));
         if (active?.profile === null)
             return err(new AnalysisSnapshotMismatchError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
@@ -187,6 +213,9 @@ export class BinarySessionRecords {
     listUnknowns(filters = {}) {
         return this.#records.listUnknowns(filters);
     }
+    listUnknownsPage(query = {}) {
+        return this.#records.listUnknownsPage(query);
+    }
     verifyUnknownResolution(unknownId) {
         return this.#records.verifyUnknownResolution(unknownId);
     }

package/dist/application/binary/BinarySessionStatus.js

@@ -1,8 +1,11 @@
+import { binaryTargetSummary } from "./BinaryTargetSummary.js";
+import { PROVIDER_EFFECT_NAMES, } from "../../contracts/toolOutputSchemaPrimitives.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 /** Project internal provider routing state into the caller-visible session status. */
-export const binarySessionStatus = ({ target, route, router, runtimeUnavailability, runId, runtimeLineageSnapshots, requestActivitySnapshots, providerOperationHealth, }) => {
-    const capabilities = [...route.capabilities.values()]
+export const binarySessionStatus = async ({ target, route, router, runtimeUnavailability, runId, runtimeLineageSnapshots, requestActivitySnapshots, providerOperationHealth, cleanupPending = false, signal, }) => {
+    const routeCapabilities = [...route.capabilities.values()]
         .filter(({ operation }) => operation !== "inventory_artifact")
-        .sort((left, right) => left.operation.localeCompare(right.operation))
+        .sort((left, right) => compareUnicodeCodePoints(left.operation, right.operation))
         .map((descriptor) => {
         const unavailable = runtimeUnavailability.get(descriptor.operation);
         return unavailable === undefined
@@ -12,8 +15,8 @@ export const binarySessionStatus = ({ target, route, router, runtimeUnavailabili
                 available: false,
                 reason: unavailable.reason,
             };
-    })
-        .map(capabilityStatus);
+    });
+    const capabilities = providerCapabilitySets(routeCapabilities);
     const analysisProviderBinding = route.binding === null
         ? null
         : {
@@ -21,20 +24,18 @@ export const binarySessionStatus = ({ target, route, router, runtimeUnavailabili
             selection_source: route.binding.selectionSource,
             analysis_profile: structuredClone(route.binding.profile),
         };
-    const analysisProviderCandidates = router
-        .candidateStatuses(route)
-        .map((candidate) => ({
+    const analysisProviderCandidates = (await router.candidateStatuses(route, signal)).map((candidate) => ({
         provider: providerSummary(candidate.provider),
         availability: structuredClone(candidate.availability),
         target_support: structuredClone(candidate.targetSupport),
         selected: candidate.selected,
-        capabilities: candidate.capabilities
+        capabilities: providerCapabilitySets(candidate.capabilities
             .slice()
             .filter(({ operation }) => operation !== "inventory_artifact")
-            .sort((left, right) => left.operation.localeCompare(right.operation))
-            .map(capabilityStatus),
+            .sort((left, right) => compareUnicodeCodePoints(left.operation, right.operation))),
     }));
     const common = {
+        cleanup_pending: cleanupPending,
         capabilities,
         analysis_provider_binding: analysisProviderBinding,
         analysis_provider_candidates: analysisProviderCandidates,
@@ -52,17 +53,13 @@ export const binarySessionStatus = ({ target, route, router, runtimeUnavailabili
         : {
             open: true,
             ...common,
-            path: target.path,
-            sha256: target.sha256,
-            format: target.format,
-            kind: target.kind,
-            architecture: target.architecture ?? null,
+            ...binaryTargetSummary(target),
         };
 };
 const requestActivityStatus = (snapshots) => {
     const providers = snapshots
         .slice()
-        .sort((left, right) => left.provider.id.localeCompare(right.provider.id))
+        .sort((left, right) => compareUnicodeCodePoints(left.provider.id, right.provider.id))
         .map(({ provider, active, queuedRequests }) => ({
         provider: providerSummary(provider),
         active: active === null
@@ -92,7 +89,7 @@ const processLineageStatus = (snapshots) => snapshots.length === 0
         status: "snapshots",
         snapshots: snapshots
             .slice()
-            .sort((left, right) => left.provider.id.localeCompare(right.provider.id))
+            .sort((left, right) => compareUnicodeCodePoints(left.provider.id, right.provider.id))
             .map(({ provider, observation }) => ({
             provider: providerSummary(provider),
             observation: observation.status === "unavailable"
@@ -117,12 +114,84 @@ const processLineageStatus = (snapshots) => snapshots.length === 0
                 },
         })),
     };
-const capabilityStatus = (descriptor) => ({
-    operation: descriptor.operation,
-    available: descriptor.available,
-    reason: descriptor.reason,
-    availability_code: descriptor.availabilityCode ?? null,
-    effects: {
+/** Group inline capability facts without merging distinct providers or states. */
+/** Project provider descriptors once for binary and target-free status consumers. */
+export const providerCapabilitySets = (descriptors) => {
+    const providers = new Map();
+    for (const descriptor of descriptors) {
+        const key = JSON.stringify([
+            descriptor.provider.id,
+            descriptor.provider.name,
+            descriptor.provider.version,
+        ]);
+        const provider = providers.get(key);
+        if (provider === undefined)
+            providers.set(key, {
+                identity: descriptor.provider,
+                descriptors: [descriptor],
+            });
+        else
+            provider.descriptors.push(descriptor);
+    }
+    return [...providers.values()].map(({ identity, descriptors: owned }) => {
+        const sharedLimitations = commonLimitationsPrefix(owned);
+        const groups = new Map();
+        for (const descriptor of owned) {
+            const effects = enabledCapabilityEffects(descriptor);
+            const limitations = descriptor.limitations.slice(sharedLimitations.length);
+            const availabilityCode = descriptor.availabilityCode ?? null;
+            const status = descriptor.available
+                ? {
+                    available: true,
+                    reason: null,
+                    availability_code: null,
+                }
+                : {
+                    available: false,
+                    reason: descriptor.reason,
+                    availability_code: availabilityCode,
+                };
+            const key = JSON.stringify([
+                effects,
+                limitations,
+                status.available,
+                status.reason,
+                status.availability_code,
+            ]);
+            const group = groups.get(key);
+            if (group === undefined)
+                groups.set(key, {
+                    operations: [descriptor.operation],
+                    effects,
+                    limitations,
+                    ...status,
+                });
+            else
+                group.operations.push(descriptor.operation);
+        }
+        return {
+            provider: providerSummary(identity),
+            shared_limitations: sharedLimitations,
+            groups: [...groups.values()],
+        };
+    });
+};
+const commonLimitationsPrefix = (descriptors) => {
+    const first = descriptors[0]?.limitations;
+    if (first === undefined)
+        return [];
+    let length = first.length;
+    for (const descriptor of descriptors.slice(1)) {
+        length = Math.min(length, descriptor.limitations.length);
+        let index = 0;
+        while (index < length && first[index] === descriptor.limitations[index])
+            index++;
+        length = index;
+    }
+    return first.slice(0, length);
+};
+const enabledCapabilityEffects = (descriptor) => {
+    const effectValues = {
         mutates_artifact: descriptor.effects.mutatesArtifact,
         launches_process: descriptor.effects.launchesProcess,
         may_show_ui: descriptor.effects.mayShowUi,
@@ -130,9 +199,9 @@ const capabilityStatus = (descriptor) => ({
         may_write_filesystem: descriptor.effects.mayWriteFilesystem,
         changes_permissions: descriptor.effects.changesPermissions,
         requires_root: descriptor.effects.requiresRoot,
-    },
-    limitations: [...descriptor.limitations],
-});
+    };
+    return PROVIDER_EFFECT_NAMES.filter((name) => effectValues[name]);
+};
 const providerOperationHealthStatus = (health) => {
     if (health === undefined || health === null)
         return null;

package/dist/application/binary/BinaryTargetSummary.js

@@ -0,0 +1,9 @@
+/** Preserve the admitted target interpretation in public lifecycle results. */
+export const binaryTargetSummary = (target) => ({
+    path: target.path,
+    format: target.format,
+    kind: target.kind,
+    sha256: target.sha256,
+    architecture: target.architecture ?? null,
+    ...(target.format === "raw-binary" ? { entry_point: target.entryPoint } : {}),
+});

package/dist/application/binary/CompositeProvider.js

@@ -1,6 +1,10 @@
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
 import { err, ok } from "../../domain/result.js";
-import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
+import { closeAnalysisClient } from "../../providers/AnalysisClientCleanup.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 /** Synthetic identity for a deterministic provider set. */
 const compositeProviderIdentity = (identities) => ({
     id: `composite:${identities
@@ -10,6 +14,73 @@ const compositeProviderIdentity = (identities) => ({
     name: "REA composite analysis provider",
     version: null,
 });
+const closeCompositeClients = (identity, clients) => {
+    const completed = new Set();
+    return async (options) => {
+        const outcomes = await Promise.all([...clients.entries()].map(async ([provider, client]) => {
+            const providerId = provider.identity().id;
+            if (completed.has(client))
+                return { providerId, result: ok(null) };
+            const result = await closeAnalysisClient(client, providerId, options);
+            if (result.ok)
+                completed.add(client);
+            return { providerId, result };
+        }));
+        const failures = outcomes.flatMap(({ providerId, result }) => result.ok ? [] : [{ providerId, error: result.error }]);
+        if (failures.length === 0)
+            return ok(null);
+        if (failures.length === 1) {
+            const failure = failures[0];
+            if (failure !== undefined)
+                return err(failure.error);
+        }
+        const resources = [
+            ...new Set(failures.flatMap(({ error }) => error.cleanupResources)),
+        ];
+        return err(new ProviderCleanupError(identity.id, resources, {
+            reason: "Multiple composed provider clients could not be confirmed closed.",
+            failures: failures.map(({ providerId, error }) => ({
+                provider_id: providerId,
+                message: error.message,
+                resources: [...error.cleanupResources],
+                ...(error.diagnostics === undefined
+                    ? {}
+                    : { diagnostics: error.diagnostics }),
+            })),
+        }, {
+            remediationAction: [
+                ...new Set(failures.map(({ error }) => projectAnalysisError(error).remediation.action)),
+            ].join("\n"),
+            cause: new AggregateError(failures.map(({ error }) => error), "Composed provider cleanup failed."),
+        }).bindCleanupDependencies(failures
+            .map(({ error }) => error)
+            .filter((error) => error.cleanupIncomplete)));
+    };
+};
+const executeCompositeHealth = async (identity, clients, options) => {
+    for (const [provider, client] of clients) {
+        const health = client.operationHealthSnapshot?.();
+        if (health !== undefined &&
+            health.state !== "idle" &&
+            health.state !== "busy")
+            return err(new ProviderAdapterError(provider.identity().id, "health", {
+                diagnostics: {
+                    reason: `instantiated provider client is ${health.state}`,
+                },
+            }));
+        const checked = await client.execute("health", {}, options);
+        if (!checked.ok)
+            return checked;
+    }
+    return ok({
+        result: null,
+        rawResult: null,
+        provider: identity,
+        limitations: [],
+        locations: [],
+        subject: null,
+    });
+};
 /** Deterministically route disjoint operations without eagerly starting children. */
 export class CompositeProvider {
     providers;
@@ -32,8 +103,8 @@ export class CompositeProvider {
             }
         }
         this.#providerByOperation = routes;
-        this.#capabilities = Object.freeze(capabilities.sort((left, right) => left.operation.localeCompare(right.operation) ||
-            left.provider.id.localeCompare(right.provider.id)));
+        this.#capabilities = Object.freeze(capabilities.sort((left, right) => compareUnicodeCodePoints(left.operation, right.operation) ||
+            compareUnicodeCodePoints(left.provider.id, right.provider.id)));
     }
     identity() {
         return this.#identity;
@@ -51,21 +122,26 @@ export class CompositeProvider {
             clients.set(provider, created);
             return created;
         };
-        const close = async (options) => {
-            const outcomes = await Promise.all([...clients.entries()].map(([provider, client]) => closeAnalysisClient(client, provider.identity().id, options)));
-            return outcomes.find((outcome) => !outcome.ok) ?? ok(null);
+        let closed = false;
+        const closeClients = closeCompositeClients(this.#identity, clients);
+        const close = (options) => {
+            closed = true;
+            return closeClients(options);
         };
         return {
-            execute: (operation, parameters, options) => {
-                if (operation === "health")
-                    return Promise.resolve(ok({
-                        result: null,
-                        rawResult: null,
-                        provider: this.#identity,
-                        limitations: [],
-                        locations: [],
-                        subject: null,
+            executeIfReady: (operation, parameters, options) => {
+                const provider = this.#providerByOperation.get(operation);
+                const client = provider === undefined || closed ? undefined : clients.get(provider);
+                return (client?.executeIfReady?.(operation, parameters, options) ??
+                    Promise.resolve(undefined));
+            },
+            execute: async (operation, parameters, options) => {
+                if (closed)
+                    return err(new ProviderAdapterError(this.#identity.id, operation, {
+                        diagnostics: { reason: "client_closed" },
                     }));
+                if (operation === "health")
+                    return executeCompositeHealth(this.#identity, clients, options);
                 const provider = this.#providerByOperation.get(operation);
                 return provider === undefined
                     ? Promise.resolve(err(new AnalysisCapabilityUnavailableError(this.#identity.id, operation, "operation is not declared by this provider set")))
@@ -73,22 +149,34 @@ export class CompositeProvider {
             },
             runtimeLineageSnapshots: () => [...clients.values()]
                 .flatMap((client) => client.runtimeLineageSnapshots?.() ?? [])
-                .sort((left, right) => left.provider.id.localeCompare(right.provider.id)),
+                .sort((left, right) => compareUnicodeCodePoints(left.provider.id, right.provider.id)),
             requestActivitySnapshots: () => [...clients.values()]
                 .flatMap((client) => client.requestActivitySnapshots?.() ?? [])
-                .sort((left, right) => left.provider.id.localeCompare(right.provider.id)),
+                .sort((left, right) => compareUnicodeCodePoints(left.provider.id, right.provider.id)),
+            reuseReadiness: () => {
+                if (closed)
+                    return "blocked";
+                const states = [...clients.values()].map((client) => client.reuseReadiness?.() ?? "unknown");
+                if (states.some((state) => state === "blocked"))
+                    return "blocked";
+                return states.some((state) => state === "unknown")
+                    ? "unknown"
+                    : "ready";
+            },
             operationHealthSnapshot: () => {
-                for (const client of clients.values()) {
-                    const snapshot = client.operationHealthSnapshot?.();
-                    if (snapshot !== undefined && snapshot.state !== "idle")
-                        return snapshot;
-                }
-                for (const client of clients.values()) {
-                    const snapshot = client.operationHealthSnapshot?.();
-                    if (snapshot !== undefined)
-                        return snapshot;
-                }
-                return undefined;
+                const snapshots = [...clients.values()].map((client) => client.operationHealthSnapshot?.());
+                const failed = snapshots.find((snapshot) => snapshot !== undefined &&
+                    (snapshot.state === "exited" ||
+                        snapshot.state === "unreachable" ||
+                        snapshot.state === "not_started"));
+                if (failed !== undefined)
+                    return failed;
+                const nonIdle = snapshots.find((snapshot) => snapshot !== undefined && snapshot.state !== "idle");
+                if (nonIdle !== undefined)
+                    return nonIdle;
+                if (snapshots.some((snapshot) => snapshot === undefined))
+                    return undefined;
+                return snapshots[0];
             },
             close,
         };

package/dist/application/binary/LazyAnalysisProvider.js

@@ -1,9 +1,5 @@
 import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
-import { AnalysisError } from "../../domain/analysisErrorBase.js";
-import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
-import { err, ok } from "../../domain/result.js";
-import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
-const isAborted = (signal) => signal?.aborted === true;
+import { DeferredAnalysisClient } from "../../providers/DeferredAnalysisClient.js";
 /**
  * Preserve synchronous provider discovery while loading implementation modules
  * only when a target-bound client first executes.
@@ -28,8 +24,12 @@ export class LazyAnalysisProvider {
     }
     /** Create a client whose implementation is loaded on first execution. */
     createClient(target, profile, context) {
-        return new LazyAnalysisClient(async () => {
+        return new DeferredAnalysisClient(async (signal) => {
             const provider = await this.#load();
+            if (signal.aborted)
+                throw new AnalysisCancelledError("create_analysis_client", {
+                    cause: signal.reason,
+                });
             return provider.createClient(target, profile, context);
         }, this.#providerIdentity.id);
     }
@@ -41,63 +41,3 @@ export class LazyAnalysisProvider {
         return this.#provider;
     }
 }
-class LazyAnalysisClient {
-    #loadClient;
-    #providerId;
-    #client;
-    #loading;
-    #closed = false;
-    constructor(loadClient, providerId) {
-        this.#loadClient = loadClient;
-        this.#providerId = providerId;
-    }
-    execute = async (operation, parameters, options) => {
-        try {
-            if (isAborted(options?.signal))
-                return err(new AnalysisCancelledError(operation));
-            const loaded = await waitForAbortable(this.#load(operation), options?.signal);
-            if (loaded === ABORTED)
-                return err(new AnalysisCancelledError(operation));
-            return await loaded.execute(operation, parameters, options);
-        }
-        catch (cause) {
-            if (cause instanceof AnalysisError)
-                return err(cause);
-            return err(new ProviderAdapterError(this.#providerId, operation, {
-                cause,
-            }));
-        }
-    };
-    runtimeLineageSnapshots() {
-        return this.#client?.runtimeLineageSnapshots?.() ?? [];
-    }
-    requestActivitySnapshots() {
-        return this.#client?.requestActivitySnapshots?.() ?? [];
-    }
-    operationHealthSnapshot() {
-        return this.#client?.operationHealthSnapshot?.();
-    }
-    close = async (options) => {
-        this.#closed = true;
-        if (this.#loading === undefined)
-            return ok(null);
-        const client = await this.#loading;
-        return client.close(options);
-    };
-    async #load(operation) {
-        if (this.#closed)
-            throw new ProviderAdapterError(this.#providerId, operation, {
-                diagnostics: { reason: "client_closed" },
-            });
-        this.#loading ??= this.#loadClient()
-            .then((client) => {
-            this.#client = client;
-            return client;
-        })
-            .catch((cause) => {
-            this.#loading = undefined;
-            throw cause;
-        });
-        return this.#loading;
-    }
-}

package/dist/application/binary/SessionProviderRouter.js

@@ -1,6 +1,5 @@
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
 import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
-import {} from "../../domain/analysisErrorBase.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisProviderRegistry, } from "./AnalysisProviderRegistry.js";
 import { CompositeProvider } from "./CompositeProvider.js";
@@ -32,6 +31,14 @@ export class SessionProviderRouter {
     initialRoute() {
         return this.route;
     }
+    /** Close provider owners not represented by the currently bound client. */
+    closeOwnedResources() {
+        return this.registry.closeOwnedResources();
+    }
+    /** Report retained candidate cleanup without performing cleanup work. */
+    hasPendingOwnedResources() {
+        return this.registry.hasPendingOwnedResources();
+    }
     /** Resolve target routes before any provider client is created. */
     async resolve(target, providerId, signal) {
         const resolutionOptions = signal === undefined ? undefined : { signal };
@@ -41,8 +48,9 @@ export class SessionProviderRouter {
             : selected;
     }
     /** Candidate status authoritative for the active or target-free route. */
-    candidateStatuses(route) {
-        return route.selection?.candidates ?? this.registry.candidates();
+    async candidateStatuses(route, signal) {
+        return (route.selection?.candidates ??
+            this.registry.candidates(undefined, signal === undefined ? {} : { signal }));
     }
     /** Produce exact candidate rejections for an intentionally unbound route. */
     unboundOperationError(operation, route) {
@@ -65,7 +73,11 @@ const selectableRoute = (auxiliaryProviders, selection) => {
             ? undefined
             : new CompositeProvider(providers);
     const identity = provider?.identity() ?? emptyProviderIdentity();
-    const capabilities = capabilityMap(provider?.capabilities() ?? []);
+    // The binding attributes deep-provider capabilities to the resolved version.
+    const capabilities = capabilityMap([
+        ...auxiliaryProviders.flatMap((auxiliary) => auxiliary.capabilities()),
+        ...(binding?.capabilities ?? []),
+    ]);
     return {
         identity,
         capabilities,