@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/model-runtime-lane.js

@@ -0,0 +1,122 @@
+/**
+ * The host lane that turns a parsed `model-runtime` recipe into a callable tool
+ * (docs/runtime/PHASE2.md § Host lane).
+ *
+ * WHAT THIS MODULE OWNS, and what it deliberately does not:
+ *
+ * - It owns the CONTRACT between the recipe and DSH: the tool's name and description, the
+ *   projection of the recipe's JSON-Schema input into what DSH can advertise, the FULL
+ *   schema enforced at call time (the projection is intentionally looser), and the output
+ *   check that stops a malformed payload from being published as a result.
+ * - It does NOT own the engine. The provider is a `ModelProviderV1` created by the factory
+ *   the recipe names, which was resolved from the extension's own package (AT-25).
+ *
+ * TIMING IS PART OF THE DESIGN. Creating a tool resolves the provider module but does not
+ * import or run it; the import and the provider's `load` happen on the FIRST CALL. That keeps
+ * activation lightweight (EXT-19) while still refusing — at registration — a package whose
+ * engine is not installed, because resolution is synchronous.
+ *
+ * @module @try-works/dsh-tool-mode/model-runtime-lane
+ */
+import { assertAgainstSchema, compileSchema, projectSchemaToDsh } from '@try-works/tool-mode-contracts';
+import { importProviderFactory, readModelRuntimeSchema, resolveProviderModule, } from "./model-runtime-recipe.js";
+/** DSH tool arguments are JSON; this only satisfies the index-signature boundary type. */
+function asJsonObject(value) {
+    // SAFETY: the arguments arrived from the DSH registry (JSON by construction) and were just
+    // validated against the recipe's schema, so a JSON round-trip is lossless.
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Build the tool for one model-runtime implementation.
+ *
+ * @param deps - the installed package, the parsed recipe and the host's context/asset hooks.
+ * @returns the tool handle or a named refusal.
+ */
+export function createModelRuntimeTool(deps) {
+    const inputSchema = readModelRuntimeSchema(deps.installPath, deps.recipe.tool.inputSchema);
+    if (!inputSchema.ok)
+        return inputSchema;
+    const outputSchema = readModelRuntimeSchema(deps.installPath, deps.recipe.tool.outputSchema);
+    if (!outputSchema.ok)
+        return outputSchema;
+    // Resolve (not import) the engine now: a package whose factory is missing is refused at
+    // registration rather than at the first caller's expense.
+    const providerModule = resolveProviderModule({ installPath: deps.installPath, recipe: deps.recipe });
+    if (!providerModule.ok)
+        return providerModule;
+    const name = deps.recipe.tool.name;
+    const inputValidator = compileSchema(inputSchema.schema);
+    const outputValidator = compileSchema(outputSchema.schema);
+    const parameters = projectSchemaToDsh(inputSchema.schema).parameters;
+    let factoryPromise;
+    let providerPromise;
+    let disposed = false;
+    /** Import the factory once; a failure is retried on the next call rather than cached forever. */
+    const ensureFactory = async () => {
+        factoryPromise ??= (async () => {
+            const imported = await importProviderFactory({ installPath: deps.installPath, recipe: deps.recipe });
+            if (!imported.ok)
+                throw new Error(`${imported.code}: ${imported.detail}`);
+            return imported.factory;
+        })();
+        return factoryPromise;
+    };
+    /** Create and LOAD the provider once; a failed load is retried rather than reported as ready. */
+    const ensureProvider = async (signal) => {
+        providerPromise ??= (async () => {
+            const factory = await ensureFactory();
+            const assets = deps.assets();
+            const provider = factory(deps.recipe, assets);
+            await provider.load({ assets, signal: signal ?? new AbortController().signal });
+            return provider;
+        })();
+        const pending = providerPromise;
+        pending.catch(() => {
+            if (providerPromise === pending)
+                providerPromise = undefined;
+        });
+        return pending;
+    };
+    return {
+        ok: true,
+        tool: {
+            name,
+            description: deps.recipe.tool.description,
+            parameters,
+            inputSchema: inputSchema.schema,
+            outputSchema: outputSchema.schema,
+            async execute(args, exec) {
+                if (disposed)
+                    throw new Error(`${name}: the owning extension was disposed`);
+                // The FULL schema, before any engine work: the DSH advertisement is a projection.
+                assertAgainstSchema(`${name} input`, inputValidator, args ?? {});
+                const provider = await ensureProvider(exec?.signal);
+                const payload = await provider.invoke({
+                    implementationId: deps.implementationId,
+                    input: asJsonObject(args ?? {}),
+                    context: deps.invocationContext(exec),
+                });
+                assertAgainstSchema(`${name} output`, outputValidator, payload);
+                return payload;
+            },
+            async dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                const pending = providerPromise;
+                providerPromise = undefined;
+                if (pending === undefined)
+                    return;
+                try {
+                    const provider = await pending;
+                    await provider.dispose();
+                }
+                catch (error) {
+                    // A disposer must not throw: deactivation continues, and the reason is recorded.
+                    deps.onError?.(`${deps.extensionId}: ${name} teardown failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            },
+        },
+    };
+}
+//# sourceMappingURL=model-runtime-lane.js.map

package/lib/model-runtime-recipe.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The `model-runtime` recipe: parsing, schema files and the provider factory binding
+ * (docs/runtime/PHASE2.md).
+ *
+ * WHY THE HOST OWNS THE PARSER. The recipe decides what the host will register and which
+ * module it will import, so it is a TRUST BOUNDARY. Validating it with code imported from
+ * the extension would let the extension define what counts as valid; importing a dedicated
+ * runtime-recipes package would put a Phase-2 runtime package in the host's dependency
+ * graph, which AT-25 and ARCH-02 exist to prevent. The rules are therefore structural and
+ * live here: data only, no engine, no model, no vendor SDK.
+ *
+ * WHAT THE HOST DOES DELEGATE — and the whole point of the recipe — is the ENGINE. The
+ * factory is resolved with `createRequire` anchored at the EXTENSION's own package.json, so
+ * a provider package that the extension installed is found, and one that only the host
+ * happens to have is not treated as available. The host declares no runtime; the package
+ * ships one and names it.
+ *
+ * @module @try-works/dsh-tool-mode/model-runtime-recipe
+ */
+import type { ModelProviderV1, PreparedAssetMapV1 } from '@try-works/tool-mode-extension-sdk';
+/** The accelerators a recipe may request; the host decides which are actually available. */
+export type ModelRuntimeAccelerator = 'cpu' | 'dml' | 'webgpu';
+/** The artifact formats the lane knows how to name. */
+export type ModelRuntimeFormat = 'onnx' | 'tflite' | 'gguf';
+/** A parsed, validated `model-runtime` recipe. */
+export interface ModelRuntimeRecipe {
+    readonly kind: 'model-runtime';
+    readonly schemaVersion: 1;
+    readonly provider: {
+        readonly package: string;
+        readonly export: string;
+        readonly accelerators?: readonly ModelRuntimeAccelerator[];
+    };
+    readonly model: {
+        readonly assetSet: string;
+        readonly fileName: string;
+        readonly format: ModelRuntimeFormat;
+    };
+    readonly processor: {
+        readonly id: string;
+    };
+    readonly limits: {
+        readonly maxInputBytes: number;
+        readonly timeoutMs: number;
+    };
+    readonly tool: {
+        readonly name: string;
+        readonly description: string;
+        readonly inputSchema: string;
+        readonly outputSchema: string;
+    };
+}
+/** Why a recipe or its binding was refused. Each is a NAMED refusal, never a silent no-op. */
+export type ModelRuntimeRefusalCode = 'not-model-runtime' | 'unknown-key' | 'bad-schema-version' | 'bad-provider' | 'bad-model' | 'bad-processor' | 'bad-limits' | 'bad-tool' | 'schema-unreadable' | 'factory-unresolved' | 'factory-import-failed' | 'factory-not-function';
+/** A refusal with the exact reason the operator needs. */
+export interface ModelRuntimeRefusal {
+    readonly ok: false;
+    readonly code: ModelRuntimeRefusalCode;
+    readonly detail: string;
+}
+/** A parsed recipe, or a refusal. */
+export type ModelRuntimeRecipeResult = {
+    readonly ok: true;
+    readonly recipe: ModelRuntimeRecipe;
+} | ModelRuntimeRefusal;
+/** The engine binding a recipe names. */
+export type ModelRuntimeProviderFactory = (recipe: ModelRuntimeRecipe, assets: Readonly<PreparedAssetMapV1>) => ModelProviderV1;
+/**
+ * Whether an unvalidated recipe claims to be a `model-runtime` recipe.
+ *
+ * The host branches on this BEFORE any harness behaviour: a harness recipe (or one with no
+ * `kind`) keeps the existing path untouched.
+ * @param raw - the recipe as read from disk.
+ * @returns whether this is the model-runtime lane's business.
+ */
+export declare function isModelRuntimeRecipe(raw: unknown): boolean;
+/**
+ * Parse and validate a `model-runtime` recipe (PHASE2 rules).
+ * @param raw - the recipe as read from disk.
+ * @returns the typed recipe or a named refusal.
+ */
+export declare function parseModelRuntimeRecipe(raw: unknown): ModelRuntimeRecipeResult;
+/** The result of reading one schema file. */
+export type ModelRuntimeSchemaResult = {
+    readonly ok: true;
+    readonly schema: Readonly<Record<string, unknown>>;
+} | ModelRuntimeRefusal;
+/**
+ * Read one package-relative schema file, refusing anything that could leave the package.
+ * @param installPath - the installed package directory.
+ * @param relative - the recipe's `./...` path.
+ * @returns the parsed schema or a named refusal.
+ */
+export declare function readModelRuntimeSchema(installPath: string, relative: string): ModelRuntimeSchemaResult;
+/** The result of resolving the recipe's provider module (a path, not an import). */
+export type ProviderModuleResult = {
+    readonly ok: true;
+    readonly resolved: string;
+} | ModelRuntimeRefusal;
+/**
+ * Resolve the recipe's provider module from the EXTENSION's own package, without importing it.
+ *
+ * Resolution is synchronous, which is what lets `registerDeclarative` — a synchronous host
+ * hook — refuse a package that cannot be resolved AT REGISTRATION, instead of registering a
+ * tool that cannot run. The import itself stays deferred to first call, so activation remains
+ * lightweight (EXT-19).
+ * @param options - the install directory and the parsed recipe.
+ * @returns the resolved module path or a named refusal.
+ */
+export declare function resolveProviderModule(options: {
+    readonly installPath: string;
+    readonly recipe: ModelRuntimeRecipe;
+}): ProviderModuleResult;
+/** The result of importing the recipe's provider factory. */
+export type ProviderFactoryResult = {
+    readonly ok: true;
+    readonly factory: ModelRuntimeProviderFactory;
+} | ModelRuntimeRefusal;
+/**
+ * Import the provider factory the recipe names, resolving from the EXTENSION's own package.
+ *
+ * The anchor is the extension's `package.json`, not the host's module graph: a package that
+ * declares an engine dependency resolves it from its own install, and the host never
+ * carries one (AT-25, ARCH-02).
+ * @param options - the install directory and the parsed recipe.
+ * @returns the factory or a named refusal.
+ */
+export declare function importProviderFactory(options: {
+    readonly installPath: string;
+    readonly recipe: ModelRuntimeRecipe;
+}): Promise<ProviderFactoryResult>;
+//# sourceMappingURL=model-runtime-recipe.d.ts.map

package/lib/model-runtime-recipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-runtime-recipe.d.ts","sourceRoot":"","sources":["../src/model-runtime-recipe.ts"],"names":[],"mappings":"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"}

package/lib/model-runtime-recipe.js

@@ -0,0 +1,291 @@
+/**
+ * The `model-runtime` recipe: parsing, schema files and the provider factory binding
+ * (docs/runtime/PHASE2.md).
+ *
+ * WHY THE HOST OWNS THE PARSER. The recipe decides what the host will register and which
+ * module it will import, so it is a TRUST BOUNDARY. Validating it with code imported from
+ * the extension would let the extension define what counts as valid; importing a dedicated
+ * runtime-recipes package would put a Phase-2 runtime package in the host's dependency
+ * graph, which AT-25 and ARCH-02 exist to prevent. The rules are therefore structural and
+ * live here: data only, no engine, no model, no vendor SDK.
+ *
+ * WHAT THE HOST DOES DELEGATE — and the whole point of the recipe — is the ENGINE. The
+ * factory is resolved with `createRequire` anchored at the EXTENSION's own package.json, so
+ * a provider package that the extension installed is found, and one that only the host
+ * happens to have is not treated as available. The host declares no runtime; the package
+ * ships one and names it.
+ *
+ * @module @try-works/dsh-tool-mode/model-runtime-recipe
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const TOP_LEVEL_KEYS = new Set(['kind', 'schemaVersion', 'provider', 'model', 'processor', 'limits', 'tool']);
+const PROVIDER_KEYS = new Set(['package', 'export', 'accelerators']);
+const MODEL_KEYS = new Set(['assetSet', 'fileName', 'format']);
+const PROCESSOR_KEYS = new Set(['id']);
+const LIMITS_KEYS = new Set(['maxInputBytes', 'timeoutMs']);
+const TOOL_KEYS = new Set(['name', 'description', 'inputSchema', 'outputSchema']);
+const FORMATS = new Set(['onnx', 'tflite', 'gguf']);
+const ACCELERATORS = new Set(['cpu', 'dml', 'webgpu']);
+/** `namespace/processor-version`, lower-case, as documented in PHASE2. */
+const PROCESSOR_ID = /^[a-z0-9]+(?:\/[a-z0-9-]+)*$/;
+/** Whether a value is a non-array object. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Refuse with a code and a reason. */
+function refuse(code, detail) {
+    return { ok: false, code, detail };
+}
+/**
+ * Whether an unvalidated recipe claims to be a `model-runtime` recipe.
+ *
+ * The host branches on this BEFORE any harness behaviour: a harness recipe (or one with no
+ * `kind`) keeps the existing path untouched.
+ * @param raw - the recipe as read from disk.
+ * @returns whether this is the model-runtime lane's business.
+ */
+export function isModelRuntimeRecipe(raw) {
+    return isRecord(raw) && raw['kind'] === 'model-runtime';
+}
+/** Refuse any key a section does not define, naming it. */
+function unknownKey(section, record, allowed) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            return refuse('unknown-key', `${section} declares the unknown key "${key}"`);
+    }
+    return undefined;
+}
+/** A non-empty trimmed string, or undefined. */
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+/**
+ * Whether a value is a package-relative schema path that cannot leave the package.
+ * @param value - the declared path.
+ * @returns whether it is safe to resolve against the install directory.
+ */
+function isContainedRelativePath(value) {
+    if (typeof value !== 'string' || !value.startsWith('./') || value.includes('\\'))
+        return false;
+    if (isAbsolute(value))
+        return false;
+    const segments = value.split('/').filter(segment => segment.length > 0);
+    return !segments.includes('..');
+}
+/**
+ * Parse and validate a `model-runtime` recipe (PHASE2 rules).
+ * @param raw - the recipe as read from disk.
+ * @returns the typed recipe or a named refusal.
+ */
+export function parseModelRuntimeRecipe(raw) {
+    if (!isModelRuntimeRecipe(raw)) {
+        return refuse('not-model-runtime', 'the recipe does not declare kind "model-runtime", so the harness path applies');
+    }
+    if (!isRecord(raw))
+        return refuse('not-model-runtime', 'the recipe is not an object');
+    const top = unknownKey('the recipe', raw, TOP_LEVEL_KEYS);
+    if (top !== undefined)
+        return top;
+    if (raw['schemaVersion'] !== 1) {
+        return refuse('bad-schema-version', `schemaVersion must be 1; this recipe declares ${JSON.stringify(raw['schemaVersion'])}`);
+    }
+    const provider = raw['provider'];
+    if (!isRecord(provider))
+        return refuse('bad-provider', 'provider must be an object');
+    const providerUnknown = unknownKey('provider', provider, PROVIDER_KEYS);
+    if (providerUnknown !== undefined)
+        return providerUnknown;
+    const packageName = nonEmptyString(provider['package']);
+    if (packageName === undefined)
+        return refuse('bad-provider', 'provider.package must be a non-empty string');
+    const exportName = nonEmptyString(provider['export']);
+    if (exportName === undefined)
+        return refuse('bad-provider', 'provider.export must be a non-empty string');
+    const rawAccelerators = provider['accelerators'];
+    let accelerators;
+    if (rawAccelerators !== undefined) {
+        if (!Array.isArray(rawAccelerators) || rawAccelerators.length === 0) {
+            return refuse('bad-provider', 'provider.accelerators must be a non-empty array when declared');
+        }
+        const declared = [];
+        for (const accelerator of rawAccelerators) {
+            if (typeof accelerator !== 'string' || !ACCELERATORS.has(accelerator)) {
+                return refuse('bad-provider', `provider.accelerators admits cpu, dml and webgpu; got ${JSON.stringify(accelerator)}`);
+            }
+            declared.push(accelerator);
+        }
+        accelerators = declared;
+    }
+    const model = raw['model'];
+    if (!isRecord(model))
+        return refuse('bad-model', 'model must be an object');
+    const modelUnknown = unknownKey('model', model, MODEL_KEYS);
+    if (modelUnknown !== undefined)
+        return modelUnknown;
+    const assetSet = nonEmptyString(model['assetSet']);
+    if (assetSet === undefined)
+        return refuse('bad-model', 'model.assetSet must be a non-empty string');
+    const fileName = nonEmptyString(model['fileName']);
+    if (fileName === undefined)
+        return refuse('bad-model', 'model.fileName must be a non-empty string');
+    if (fileName.includes('/') || fileName.includes('\\') || fileName === '.' || fileName === '..') {
+        return refuse('bad-model', `model.fileName must be a bare file name; got ${JSON.stringify(fileName)}`);
+    }
+    const format = model['format'];
+    if (typeof format !== 'string' || !FORMATS.has(format)) {
+        return refuse('bad-model', `model.format admits onnx, tflite and gguf; got ${JSON.stringify(format)}`);
+    }
+    const processor = raw['processor'];
+    if (!isRecord(processor))
+        return refuse('bad-processor', 'processor must be an object');
+    const processorUnknown = unknownKey('processor', processor, PROCESSOR_KEYS);
+    if (processorUnknown !== undefined)
+        return processorUnknown;
+    const processorId = nonEmptyString(processor['id']);
+    if (processorId === undefined)
+        return refuse('bad-processor', 'processor.id must be a non-empty string');
+    if (!PROCESSOR_ID.test(processorId)) {
+        return refuse('bad-processor', `processor.id must match ${PROCESSOR_ID.source}; got ${JSON.stringify(processorId)}`);
+    }
+    const limits = raw['limits'];
+    if (!isRecord(limits))
+        return refuse('bad-limits', 'limits must be an object');
+    const limitsUnknown = unknownKey('limits', limits, LIMITS_KEYS);
+    if (limitsUnknown !== undefined)
+        return limitsUnknown;
+    for (const key of ['maxInputBytes', 'timeoutMs']) {
+        const value = limits[key];
+        if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+            return refuse('bad-limits', `limits.${key} must be a positive integer; got ${JSON.stringify(value)}`);
+        }
+    }
+    const tool = raw['tool'];
+    if (!isRecord(tool))
+        return refuse('bad-tool', 'tool must be an object');
+    const toolUnknown = unknownKey('tool', tool, TOOL_KEYS);
+    if (toolUnknown !== undefined)
+        return toolUnknown;
+    const toolName = nonEmptyString(tool['name']);
+    if (toolName === undefined)
+        return refuse('bad-tool', 'tool.name must be a non-empty string');
+    const description = nonEmptyString(tool['description']);
+    if (description === undefined)
+        return refuse('bad-tool', 'tool.description must be a non-empty string');
+    for (const key of ['inputSchema', 'outputSchema']) {
+        if (!isContainedRelativePath(tool[key])) {
+            return refuse('bad-tool', `tool.${key} must be a package-relative "./..." path that stays inside the package; got ${JSON.stringify(tool[key])}`);
+        }
+    }
+    return {
+        ok: true,
+        recipe: {
+            kind: 'model-runtime',
+            schemaVersion: 1,
+            provider: { package: packageName, export: exportName, ...(accelerators === undefined ? {} : { accelerators }) },
+            model: { assetSet, fileName, format: format },
+            processor: { id: processorId },
+            limits: { maxInputBytes: limits['maxInputBytes'], timeoutMs: limits['timeoutMs'] },
+            tool: {
+                name: toolName,
+                description,
+                inputSchema: tool['inputSchema'],
+                outputSchema: tool['outputSchema'],
+            },
+        },
+    };
+}
+/**
+ * Read one package-relative schema file, refusing anything that could leave the package.
+ * @param installPath - the installed package directory.
+ * @param relative - the recipe's `./...` path.
+ * @returns the parsed schema or a named refusal.
+ */
+export function readModelRuntimeSchema(installPath, relative) {
+    if (!isContainedRelativePath(relative)) {
+        return refuse('bad-tool', `${JSON.stringify(relative)} is not a package-relative schema path`);
+    }
+    const root = resolve(installPath);
+    const absolute = resolve(root, relative);
+    if (absolute !== root && !absolute.startsWith(root + sep)) {
+        return refuse('bad-tool', `${JSON.stringify(relative)} resolves outside the package`);
+    }
+    let text;
+    try {
+        text = readFileSync(absolute, 'utf8');
+    }
+    catch (error) {
+        return refuse('schema-unreadable', `the tool schema ${JSON.stringify(relative)} could not be read from ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return refuse('schema-unreadable', `the tool schema ${JSON.stringify(relative)} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        return refuse('schema-unreadable', `the tool schema ${JSON.stringify(relative)} must be a JSON object`);
+    }
+    return { ok: true, schema: parsed };
+}
+/**
+ * Resolve the recipe's provider module from the EXTENSION's own package, without importing it.
+ *
+ * Resolution is synchronous, which is what lets `registerDeclarative` — a synchronous host
+ * hook — refuse a package that cannot be resolved AT REGISTRATION, instead of registering a
+ * tool that cannot run. The import itself stays deferred to first call, so activation remains
+ * lightweight (EXT-19).
+ * @param options - the install directory and the parsed recipe.
+ * @returns the resolved module path or a named refusal.
+ */
+export function resolveProviderModule(options) {
+    const anchor = join(options.installPath, 'package.json');
+    const require = createRequire(anchor);
+    const specifier = options.recipe.provider.package;
+    try {
+        return { ok: true, resolved: require.resolve(specifier) };
+    }
+    catch (error) {
+        return refuse('factory-unresolved', `the provider package ${JSON.stringify(specifier)} cannot be resolved from the extension package directory (${anchor}): `
+            + `${error instanceof Error ? error.message : String(error)}. The host declares no engine of its own (AT-25)`);
+    }
+}
+/**
+ * Import the provider factory the recipe names, resolving from the EXTENSION's own package.
+ *
+ * The anchor is the extension's `package.json`, not the host's module graph: a package that
+ * declares an engine dependency resolves it from its own install, and the host never
+ * carries one (AT-25, ARCH-02).
+ * @param options - the install directory and the parsed recipe.
+ * @returns the factory or a named refusal.
+ */
+export async function importProviderFactory(options) {
+    const resolvedModule = resolveProviderModule(options);
+    if (!resolvedModule.ok)
+        return resolvedModule;
+    const resolved = resolvedModule.resolved;
+    let namespace;
+    try {
+        namespace = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
+    }
+    catch (error) {
+        return refuse('factory-import-failed', `the provider module ${resolved} failed to import: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const candidate = namespace[options.recipe.provider.export];
+    if (typeof candidate !== 'function') {
+        return refuse('factory-not-function', `the provider module ${resolved} does not export a function named ${JSON.stringify(options.recipe.provider.export)}`);
+    }
+    return { ok: true, factory: candidate };
+}
+//# sourceMappingURL=model-runtime-recipe.js.map