@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/lib/prepared-assets.js

@@ -0,0 +1,286 @@
+/**
+ * The host's prepared-assets path (RES-02/03/05, the last in-repo slice):
+ * lock reading → preparation plan → approval-gated, digest-verified acquisition
+ * into an isolated content-addressed cache → the prepared-cold readiness flip →
+ * the PreparedAssetMapV1 the provider routes consume.
+ *
+ * The verified components this module finally gives callers to:
+ *
+ * - `planPreparation`/`DeploymentIdentity` (deployment-coordinator.ts) — the
+ *   pre-approval disclosure;
+ * - `acquireAsset` (asset-acquisition.ts) — digest+size verified, atomic,
+ *   resumable acquisition with tamper refusal;
+ * - `createHttpSource` (http-acquisition.ts) — the default ranged source.
+ *
+ * Honesty rules carried through:
+ *
+ * - a lock with no digests REFUSES (no guessed values);
+ * - an executable asset WITHOUT the explicit executable-preparation approval
+ *   refuses (RES-02);
+ * - a tampered final path is refused and never flips readiness;
+ * - the cache lives under the host's isolated state dir, never the repo or
+ *   HOME; a REAL network run is opt-in (the default source), and the suite
+ *   injects a local file source so it performs no network.
+ *
+ * @module @try-works/dsh-model-as-tool/prepared-assets
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireAsset } from "./asset-acquisition.js";
+/**
+ * Parse a models.lock.json document.
+ *
+ * A lock with no digest on any asset REFUSES: a preparation built on guessed
+ * bytes would verify nothing (RES-03).
+ * @param bytes - the lock document.
+ * @returns the parsed lock.
+ */
+export function parseAssetLock(bytes) {
+    let document;
+    try {
+        document = JSON.parse(bytes);
+    }
+    catch (error) {
+        throw new Error(`the asset lock is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof document !== 'object' || document === null)
+        throw new Error('the asset lock is not a document');
+    const root = document;
+    const assetSets = root['assetSets'];
+    if (typeof assetSets !== 'object' || assetSets === null)
+        throw new Error('the asset lock declares no assetSets');
+    const sets = {};
+    for (const [setId, rawSet] of Object.entries(assetSets)) {
+        const set = rawSet;
+        const revision = typeof set['pinning'] === 'object' && set['pinning'] !== null
+            ? set['pinning']['revision']
+            : undefined;
+        const license = typeof set['license'] === 'object' && set['license'] !== null
+            ? set['license']
+            : {};
+        const rawGroups = set['groups'];
+        if (!Array.isArray(rawGroups))
+            throw new Error(`asset set ${setId} declares no groups`);
+        const groups = rawGroups.map((rawGroup, groupIndex) => {
+            const group = rawGroup;
+            const rawAssets = group['assets'];
+            if (!Array.isArray(rawAssets))
+                throw new Error(`asset set ${setId} group ${groupIndex} declares no assets`);
+            const assets = rawAssets.map((rawAsset, assetIndex) => {
+                const asset = rawAsset;
+                const digest = typeof asset['digest'] === 'string' ? asset['digest'] : '';
+                const bytes = typeof asset['bytes'] === 'number' ? asset['bytes'] : NaN;
+                const id = typeof asset['id'] === 'string' ? asset['id'] : '';
+                const file = typeof asset['file'] === 'string' ? asset['file'] : '';
+                const source = typeof asset['source'] === 'string' ? asset['source'] : '';
+                if (digest.length === 0 || !Number.isFinite(bytes) || id.length === 0 || file.length === 0) {
+                    throw new Error(`asset set ${setId} group ${groupIndex} asset ${assetIndex} is incomplete; a lock without pinned digests and sizes refuses (RES-03)`);
+                }
+                return { id, file, bytes, source, digest, executable: asset['executable'] === true };
+            });
+            return { id: typeof group['id'] === 'string' ? group['id'] : `group-${groupIndex}`, assets };
+        });
+        sets[setId] = {
+            groups,
+            revision: typeof revision === 'string' ? revision : '',
+            license: {
+                name: typeof license['name'] === 'string' ? license['name'] : 'undeclared',
+                url: typeof license['url'] === 'string' ? license['url'] : '',
+            },
+        };
+    }
+    const lockRevision = Object.values(sets)[0]?.revision ?? '';
+    if (lockRevision.length === 0)
+        throw new Error('the asset lock pins no model revision; a preparation cannot be planned');
+    return { revision: lockRevision, license: Object.values(sets)[0]?.license ?? { name: 'undeclared', url: '' }, sets };
+}
+/** The identity the lock implies for one model deployment. */
+export function identityFor(extensionId, modelId, lock) {
+    return {
+        extensionId,
+        modelId,
+        modelRevision: lock.revision,
+        engineVersion: 'onnxruntime-node',
+        quantization: 'unquantized-fp32',
+        tokenizer: 'gemma',
+        preprocessingRecipe: 'pinned',
+    };
+}
+/** The flat PlannedAsset list for one asset set. */
+export function plannedAssets(lock, assetSetId) {
+    const set = lock.sets[assetSetId];
+    if (set === undefined)
+        throw new Error(`the lock declares no asset set "${assetSetId}"`);
+    return set.groups.flatMap(group => group.assets.map(asset => ({
+        assetId: `${group.id}/${asset.id}`,
+        bytes: asset.bytes,
+        source: asset.source,
+        digest: asset.digest,
+        executable: asset.executable,
+    })));
+}
+/** The group map for one asset set, keyed by group id. */
+export function lockGroups(lock, assetSetId) {
+    const set = lock.sets[assetSetId];
+    if (set === undefined)
+        throw new Error(`the lock declares no asset set "${assetSetId}"`);
+    return set.groups;
+}
+/** The filesystem store acquisition needs, over node:fs. */
+function fsStore() {
+    return {
+        write(path, bytes) {
+            mkdirSync(join(path, '..'), { recursive: true });
+            writeFileSync(path, bytes);
+        },
+        read(path) {
+            if (!existsSync(path))
+                return undefined;
+            return new Uint8Array(readFileSync(path));
+        },
+        sizeOf(path) {
+            if (!existsSync(path))
+                return 0;
+            return statSyncSize(path);
+        },
+        rename(from, to) {
+            renameSync(from, to);
+        },
+        remove(path) {
+            rmSync(path, { force: true });
+        },
+        exists(path) {
+            return existsSync(path);
+        },
+    };
+}
+/** Synchronous size (the store interface is sync). */
+function statSyncSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Create the prepared-assets registry.
+ * @param options - the cache root and the default source.
+ * @returns the registry.
+ */
+export function createPreparedAssetRegistry(options) {
+    const cacheRoot = options.cacheRoot;
+    const held = new Map();
+    // The content-addressed blob pool, shared across extensions (RES-03: two
+    // owners share one set of bytes).
+    return {
+        plans() {
+            return new Map([...held.entries()].map(([extensionId, preparation]) => [extensionId, preparation.plan]));
+        },
+        assetMapFor(extensionId) {
+            const preparation = held.get(extensionId);
+            if (preparation === undefined)
+                return undefined;
+            /**
+             * TWO projections over one verified preparation, both truthful:
+             *
+             * - the GROUP id resolves to the group directory (embeddinggemma's selective
+             *   loading asks for `text-backbone` and reads `onnx/model.onnx` under it);
+             * - each ASSET id resolves to the individual materialized file (needle asks
+             *   for `needle-engine-win-x64` and needs the executable's path).
+             *
+             * The SDK documents the map as asset ids to local handles, so the per-asset
+             * entries are the canonical projection and the group entry is the directory
+             * convenience the first-party group consumers already rely on. An exact
+             * asset-id match wins over a group-id match; the ids are namespaced by the
+             * lock and a collision is not silently served as the other kind.
+             */
+            const groupHandles = new Map();
+            const assetHandles = new Map();
+            for (const group of preparation.groups) {
+                groupHandles.set(group.groupId, { path: group.path, digest: group.digests.join(',') });
+                for (const file of group.files) {
+                    assetHandles.set(file.assetId, { path: file.path, digest: file.digest });
+                }
+            }
+            return {
+                assetIds: [...groupHandles.keys(), ...assetHandles.keys()],
+                get(assetId) {
+                    return assetHandles.get(assetId) ?? groupHandles.get(assetId);
+                },
+            };
+        },
+        groupsFor(extensionId) {
+            return held.get(extensionId)?.groups ?? [];
+        },
+        async prepare(extensionId, plan, groups, options) {
+            if (!options.allowExecutable && plan.requiresExecutableApproval) {
+                return {
+                    ok: false,
+                    reason: 'the plan includes an EXECUTABLE asset, which requires the separate executable-preparation approval (RES-02); this call did not grant it',
+                };
+            }
+            const store = fsStore();
+            mkdirSync(cacheRoot, { recursive: true });
+            const prepared = [];
+            for (const group of groups) {
+                const groupDir = join(cacheRoot, 'groups', plan.identity.extensionId.replaceAll('/', '__'), plan.identity.modelId, group.id);
+                const digests = [];
+                const files = [];
+                for (const asset of group.assets) {
+                    const planned = {
+                        assetId: asset.id,
+                        bytes: asset.bytes,
+                        source: asset.source,
+                        digest: asset.digest,
+                        executable: asset.executable,
+                    };
+                    // NO in-memory blob shortcut: acquireAsset re-verifies the on-disk
+                    // bytes on every call (a cache HIT transfers zero bytes but still
+                    // checks the digest), so a blob tampered on disk is re-acquired
+                    // rather than trusted from a stale memory record — and two owners
+                    // still share the verified bytes.
+                    const result = await acquireAsset(planned, {
+                        store,
+                        source: options.source,
+                        root: cacheRoot,
+                        signal: options.signal,
+                    });
+                    if (!result.acquired) {
+                        return { ok: false, reason: `${group.id}/${asset.id}: ${result.reason}` };
+                    }
+                    const blob = { digest: result.digest, path: result.path };
+                    // Materialize the lock's per-asset FILE layout inside the group dir via
+                    // a hard link: the provider resolves `${groupDir}/onnx/model.onnx` etc.
+                    // The link shares the verified blob's bytes (same volume); the digest
+                    // was verified at acquisition and the blob path never changes.
+                    mkdirSync(join(groupDir, asset.file, '..'), { recursive: true });
+                    const linkTarget = join(groupDir, asset.file);
+                    if (!existsSync(linkTarget)) {
+                        try {
+                            linkSync(blob.path, linkTarget);
+                        }
+                        catch {
+                            // Hard links can fail across volumes; a copy is the fallback and
+                            // is equally verified because the blob's digest was checked.
+                            writeFileSync(linkTarget, readFileSync(blob.path));
+                        }
+                    }
+                    else if (createHash('sha256').update(readFileSync(linkTarget)).digest('hex') !== asset.digest) {
+                        // A tampered FINAL path never poisons readiness: it is removed and
+                        // the verified blob re-linked.
+                        rmSync(linkTarget, { force: true });
+                        linkSync(blob.path, linkTarget);
+                    }
+                    digests.push(asset.digest);
+                    files.push({ assetId: asset.id, file: asset.file, path: linkTarget, digest: asset.digest });
+                }
+                prepared.push({ groupId: group.id, path: groupDir, digests, files });
+            }
+            held.set(extensionId, { plan, groups: prepared });
+            return { ok: true, groups: prepared };
+        },
+    };
+}
+//# sourceMappingURL=prepared-assets.js.map

package/lib/provider-bridge.d.ts

@@ -14,7 +14,9 @@
  *
  * @module @try-works/dsh-model-as-tool/provider-bridge
  */
+import { type ProviderInspectionV1 } from '@try-works/tool-mode-extension-sdk';
 import { type ToolGrant } from './authority.ts';
+import type { ManagedWorkerRegistry } from './managed-workers.ts';
 import type { ModelCatalogEntry } from './types.ts';
 import type { ModelAdapter } from './adapters/types.ts';
 /** How a model's provider is obtained. */
@@ -43,10 +45,45 @@ export declare class ProviderBridge {
     constructor(options: {
         readonly grant: ToolGrant;
         readonly activationGeneration: number;
+        readonly managed?: ManagedWorkerRegistry;
         readonly log?: (message: string, fields?: Record<string, unknown>) => void;
     });
     /** The extensions currently activated, for diagnostics. */
     get activatedExtensions(): readonly string[];
+    /**
+     * Inspect one extension-backed catalog entry through its provider.
+     *
+     * Inspection is the extension's read-only readiness path (EXT-18). It may import
+     * and activate the extension, but it does not load model assets or invoke the
+     * model; the provider itself must report only approved local state. This is used
+     * by publication and discovery so the host does not equate "the package
+     * resolves" with "the selected deployment is prepared".
+     * @param entry - the catalog entry to inspect.
+     * @param signal - cancellation for the read-only inspection.
+     * @returns the provider's inspection, or undefined for entries with no provider binding.
+     */
+    inspect(entry: ModelCatalogEntry, signal: AbortSignal): Promise<ProviderInspectionV1 | undefined>;
+    /**
+     * Inspect one extension INSTALLED IN THE STORE, keyed by its own manifest model id.
+     *
+     * The catalog-driven {@link inspect} cannot reach an extension that has no catalog
+     * row (EmbeddingGemma and Needle ship declared tools but are not catalogued), which
+     * left their deployments permanently `needs-preparation`. This route activates the
+     * extension through its public entry and inspects the provider the MANIFEST declares,
+     * so "prepared" can become a durable fact for store-installed packages too.
+     *
+     * Inspection remains read-only (EXT-18): no model assets are loaded.
+     * @param specifier - the installed extension package name or ABSOLUTE install path.
+     *   An absolute path runs the exact store copy the caller verified, rather than
+     *   whatever the package name resolves to in the host's own dependency graph.
+     * @param modelId - the model id the extension's manifest declares.
+     * @param signal - cancellation for the read-only inspection.
+     * @returns the provider's inspection, or undefined when the model is not declared.
+     * @throws ProviderBridgeError when the package cannot be resolved or the provider
+     *   refuses creation for this model id (the model's declaredness is the provider's
+     *   to assert, so an undeclared id surfaces as a throw rather than undefined).
+     */
+    inspectExtension(specifier: string, modelId: string, signal: AbortSignal): Promise<ProviderInspectionV1 | undefined>;
     /**
      * Build an adapter for one catalog entry.
      *

package/lib/provider-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-bridge.d.ts","sourceRoot":"","sources":["../src/provider-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAAgC,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAErF,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAeD,2EAA2E;AAC3E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;CAC/C;AAED;;;;;GAKG;AACH,qBAAa,cAAc;;gBAMb,OAAO,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;QACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;KAC3E;IAMD,2DAA2D;IAC3D,IAAI,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAE3C;IAED;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS;IAyB9D,yCAAyC;IACnC,OAAO,CAAC,MAAM,GAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,OAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAoHjH"}
+{"version":3,"file":"provider-bridge.d.ts","sourceRoot":"","sources":["../src/provider-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EASL,KAAK,oBAAoB,EAC1B,MAAM,oCAAoC,CAAA;AAE3C,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAGjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAAgC,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAErF,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAeD,2EAA2E;AAC3E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;CAC/C;AAED;;;;;GAKG;AACH,qBAAa,cAAc;;gBAcb,OAAO,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;QACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAA;QACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;KAC3E;IAOD,2DAA2D;IAC3D,IAAI,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAE3C;IAED;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAoBvG;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAa1H;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS;IAkF9D,yCAAyC;IACnC,OAAO,CAAC,MAAM,GAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,OAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CA0HjH"}

package/lib/provider-bridge.js

@@ -16,6 +16,8 @@
  */
 import { activateExtension, assertNoReservedMeta, EXTENSION_ENTRY, loadExtensionModule, } from '@try-works/tool-mode-extension-sdk';
 import { createInvocationAuthority } from "./authority.js";
+import { isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 /** Raised when a model cannot be served through its declared extension. */
 export class ProviderBridgeError extends Error {
     name = 'ProviderBridgeError';
@@ -31,15 +33,88 @@ export class ProviderBridge {
     #grant;
     #generation;
     #log;
+    /**
+     * The managed-worker registry (EXT-20). Present ONLY when the operator opted in
+     * (`managedWorkers: true`): every executable route — catalog invocation and
+     * inspection — then goes through the worker, and the in-process import/activate
+     * path below is never taken for it. There is NO silent in-process fallback: a
+     * phase the protocol cannot serve is REFUSED with its reason.
+     */
+    #managed;
     constructor(options) {
         this.#grant = options.grant;
         this.#generation = options.activationGeneration;
+        this.#managed = options.managed;
         this.#log = options.log ?? (() => { });
     }
     /** The extensions currently activated, for diagnostics. */
     get activatedExtensions() {
         return [...this.#activated.keys()];
     }
+    /**
+     * Inspect one extension-backed catalog entry through its provider.
+     *
+     * Inspection is the extension's read-only readiness path (EXT-18). It may import
+     * and activate the extension, but it does not load model assets or invoke the
+     * model; the provider itself must report only approved local state. This is used
+     * by publication and discovery so the host does not equate "the package
+     * resolves" with "the selected deployment is prepared".
+     * @param entry - the catalog entry to inspect.
+     * @param signal - cancellation for the read-only inspection.
+     * @returns the provider's inspection, or undefined for entries with no provider binding.
+     */
+    async inspect(entry, signal) {
+        const binding = entry.provider;
+        if (binding === undefined)
+            return undefined;
+        if (this.#managed !== undefined) {
+            // EXT-20, managed mode: inspection runs ENTIRELY in the managed process
+            // through the verified SDK inspect API — the entry is never imported in-host.
+            const resolved = await resolveExtensionPackage(binding.extension, entry);
+            const worker = await this.#managed.adapterFor({
+                extensionId: resolved.manifestId,
+                entryPath: resolved.entryPath,
+                manifestPath: resolved.manifestPath,
+                generation: this.#generation,
+            });
+            return await worker.inspect(binding.modelId, { signal });
+        }
+        const activated = await this.#activate(binding.extension, entry);
+        const provider = await this.#providerFor(activated, binding);
+        return provider.inspect(signal);
+    }
+    /**
+     * Inspect one extension INSTALLED IN THE STORE, keyed by its own manifest model id.
+     *
+     * The catalog-driven {@link inspect} cannot reach an extension that has no catalog
+     * row (EmbeddingGemma and Needle ship declared tools but are not catalogued), which
+     * left their deployments permanently `needs-preparation`. This route activates the
+     * extension through its public entry and inspects the provider the MANIFEST declares,
+     * so "prepared" can become a durable fact for store-installed packages too.
+     *
+     * Inspection remains read-only (EXT-18): no model assets are loaded.
+     * @param specifier - the installed extension package name or ABSOLUTE install path.
+     *   An absolute path runs the exact store copy the caller verified, rather than
+     *   whatever the package name resolves to in the host's own dependency graph.
+     * @param modelId - the model id the extension's manifest declares.
+     * @param signal - cancellation for the read-only inspection.
+     * @returns the provider's inspection, or undefined when the model is not declared.
+     * @throws ProviderBridgeError when the package cannot be resolved or the provider
+     *   refuses creation for this model id (the model's declaredness is the provider's
+     *   to assert, so an undeclared id surfaces as a throw rather than undefined).
+     */
+    async inspectExtension(specifier, modelId, signal) {
+        if (this.#managed !== undefined) {
+            // Managed mode: the SAME worker-backed inspection as the catalog path —
+            // the entry is imported and created only in the child process.
+            const entry = { id: modelId, provider: { extension: specifier, modelId } };
+            return await this.inspect(entry, signal);
+        }
+        const entry = { id: modelId, provider: { extension: specifier, modelId } };
+        const activated = await this.#activate(specifier, entry);
+        const provider = await this.#providerFor(activated, { extension: specifier, modelId });
+        return provider.inspect(signal);
+    }
     /**
      * Build an adapter for one catalog entry.
      *
@@ -59,6 +134,62 @@ export class ProviderBridge {
         const binding = entry.provider;
         if (binding === undefined)
             return undefined;
+        if (this.#managed !== undefined) {
+            /**
+             * EXT-20, MANAGED MODE: the catalog invocation runs OUT OF PROCESS. The
+             * bridge resolves the entry path by DISCOVERY ONLY (reading the manifest is
+             * not importing), binds the worker to the activation generation, and sends
+             * the pre-authorized input over the wire — the grant, the caller identity
+             * and the host environment never cross, and the HOST resolves the path
+             * authority before the wire because the child's resolver DENIES by design.
+             */
+            const registry = this.#managed;
+            return {
+                modelId: entry.id,
+                invoke: async (invocation) => {
+                    const resolved = await resolveExtensionPackage(binding.extension, entry);
+                    const authority = invocation.authority ?? createInvocationAuthority(this.#grant, 'interactive');
+                    const input = {};
+                    for (const [key, value] of Object.entries(invocation.args)) {
+                        input[key] = value;
+                    }
+                    // SEC-06: the HOST's authority is the child's path broker — the verified
+                    // SDK protocol asks the host for EVERY path the provider touches, and an
+                    // unauthorized candidate is refused by the authority inside this callback
+                    // BEFORE the child ever opens the file. The broker is request-scoped and
+                    // carries no grant or identity beyond the resolution function.
+                    const resolvePath = (candidate) => authority.resolvePath(candidate);
+                    // EXT-20: the worker is keyed by the TRUE MANIFEST ID, never by the path
+                    // or the package specifier — and the manifest path rides along so the
+                    // registry can stage an owning-package layout for manifest-less store copies.
+                    const worker = await registry.adapterFor({
+                        extensionId: resolved.manifestId,
+                        entryPath: resolved.entryPath,
+                        manifestPath: resolved.manifestPath,
+                        generation: this.#generation,
+                    });
+                    // The CHILD's strict protocol maps IMPLEMENTATION ids to model ids through
+                    // the manifest, so the wire carries the manifest's implementation id for
+                    // this model — never the model id itself (a strict provider refuses a
+                    // model id passed as an implementation id).
+                    const implementationId = resolved.implementations
+                        .find(implementation => implementation.modelId === binding.modelId)?.id
+                        ?? binding.modelId;
+                    const payload = await worker.invoke({
+                        implementationId,
+                        input,
+                        signal: invocation.signal,
+                        resolvePath,
+                    });
+                    // The same reserved-root assertion as the in-process path (EXT-17).
+                    assertNoReservedMeta(payload, binding.modelId);
+                    return payload;
+                },
+                dispose: async () => {
+                    await registry.dispose(binding.extension);
+                },
+            };
+        }
         return {
             modelId: entry.id,
             invoke: async (invocation) => {
@@ -111,6 +242,10 @@ export class ProviderBridge {
             return { instance, providers: new Map() };
         })();
         this.#activated.set(specifier, pending);
+        pending.catch(() => {
+            if (this.#activated.get(specifier) === pending)
+                this.#activated.delete(specifier);
+        });
         return pending;
     }
     /** Create or reuse the provider for one model. */
@@ -123,6 +258,10 @@ export class ProviderBridge {
             configuration: {},
         });
         activated.providers.set(binding.modelId, pending);
+        pending.catch(() => {
+            if (activated.providers.get(binding.modelId) === pending)
+                activated.providers.delete(binding.modelId);
+        });
         return pending;
     }
     /** Run one invocation through the provider. */
@@ -187,32 +326,70 @@ export class ProviderBridge {
     }
 }
 /**
- * Import an extension package's public entry.
+ * Resolve an extension package's entry path, manifest identity and manifest path BY
+ * DISCOVERY ONLY (EXT-20).
  *
- * The specifier is resolved by Node like any other dependency, then the package's
- * own discovery runs so the entry comes from its real `exports` map rather than
- * from a host-side convention.
- * @param specifier - the package name or path.
+ * This reads the package's metadata — the package.json and the manifest — and
+ * returns the absolute `./tool-mode` entry path, the manifest's TRUE id, and the
+ * manifest path WITHOUT importing the entry. Managed mode needs exactly this: the
+ * worker child imports the entry in its own process and derives its model mapping
+ * from the manifest, so the host must never load the module — and must key the
+ * worker by the manifest id, never by a path.
+ * @param specifier - the package name or absolute install path.
  * @param entry - the catalog entry, for diagnostics.
- * @returns the validated extension module.
+ * @returns the entry path, the manifest id and the manifest path.
  * @throws ProviderBridgeError when the package cannot be resolved or has no entry.
  */
-async function loadExtensionPackage(specifier, entry) {
+async function resolveExtensionPackage(specifier, entry) {
     let packageJsonPath;
     try {
         // `import.meta.resolve` is the resolver the runtime itself uses, so the
-        // extension is found exactly as Node would find it at call time.
-        packageJsonPath = import.meta.resolve(`${specifier}/package.json`);
+        // extension is found exactly as Node would find it at call time. An ABSOLUTE
+        // path resolves to the exact installed copy.
+        if (isAbsolute(specifier)) {
+            packageJsonPath = pathToFileURL(join(specifier, 'package.json')).href;
+        }
+        else {
+            packageJsonPath = import.meta.resolve(`${specifier}/package.json`);
+        }
     }
     catch (error) {
-        throw new ProviderBridgeError(`model "${entry.id}" declares the extension "${specifier}", which could not be resolved: `
-            + `${error instanceof Error ? error.message : String(error)}. Install it, or correct the catalog binding.`);
+        const origin = isAbsolute(specifier)
+            ? 'the installed package'
+            : `the dependency "${specifier}"`;
+        throw new ProviderBridgeError(`model "${entry.id}" cannot reach ${origin}, which could not be resolved: `
+            + `${error instanceof Error ? error.message : String(error)}. `
+            + (isAbsolute(specifier)
+                ? 'The store install path is unreadable; reinstall the package and retry.'
+                : 'Install it, or correct the catalog binding.'));
     }
     const { discoverExtension } = await import('@try-works/tool-mode-extension-sdk');
     const discovery = discoverExtension(new URL('.', packageJsonPath).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
     if (discovery.entryPath === undefined) {
         throw new ProviderBridgeError(`extension "${specifier}" declares no ${EXTENSION_ENTRY} entry, so it cannot provide model "${entry.id}"`);
     }
-    return loadExtensionModule(discovery.entryPath);
+    return {
+        entryPath: discovery.entryPath,
+        manifestId: discovery.manifest.id,
+        manifestPath: discovery.manifestPath,
+        implementations: discovery.manifest.implementations
+            .filter((implementation) => typeof implementation.modelId === 'string')
+            .map(implementation => ({ id: implementation.id, modelId: implementation.modelId })),
+    };
+}
+/**
+ * Import an extension package's public entry.
+ *
+ * The specifier is resolved by Node like any other dependency, then the package's
+ * own discovery runs so the entry comes from its real `exports` map rather than
+ * from a host-side convention.
+ * @param specifier - the package name or path.
+ * @param entry - the catalog entry, for diagnostics.
+ * @returns the validated extension module.
+ * @throws ProviderBridgeError when the package cannot be resolved or has no entry.
+ */
+async function loadExtensionPackage(specifier, entry) {
+    const { entryPath } = await resolveExtensionPackage(specifier, entry);
+    return loadExtensionModule(entryPath);
 }
 //# sourceMappingURL=provider-bridge.js.map