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

package/lib/extension-dispatch.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-tool-mode/extension-dispatch
+ */
+import type { PreparedAssetMap } from './prepared-assets.ts';
+/** What a manifest declares about one tool. */
+export interface DeclaredTool {
+    readonly name: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+}
+/** What a manifest declares about one implementation. */
+export interface DeclaredImplementation {
+    readonly id: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+    /** The model that serves the contract. */
+    readonly modelId: string;
+}
+/** The parts of a manifest this module needs. */
+export interface DispatchManifest {
+    readonly tools: readonly DeclaredTool[];
+    readonly implementations: readonly DeclaredImplementation[];
+}
+/** A provider, narrowed to what dispatch needs. */
+export interface DispatchProvider {
+    load(request: {
+        readonly assets: unknown;
+        readonly signal: AbortSignal;
+        /** The manifest model id; the managed worker's load keys by it. */
+        readonly modelId?: string;
+    }): Promise<void>;
+    invoke(request: {
+        readonly implementationId: string;
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly context: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/** What dispatch needs from the host to reach an extension. */
+export interface DispatchEnvironment {
+    /** The manifest of the activated extension that declared the tool. */
+    getManifest(): DispatchManifest;
+    /** Create (or return a cached) provider for a model deployment. */
+    providerFor(modelId: string): Promise<DispatchProvider>;
+    /** Build the invocation context, which carries host-issued identity. */
+    contextFor(implementationId: string, signal: AbortSignal): unknown;
+    /**
+     * The host's verified prepared-asset map for THIS extension, or undefined
+     * when nothing was prepared (the load then receives the EMPTY map — an
+     * extension needing assets refuses by name inside its own load, which is the
+     * honest MOD-02 behavior rather than an invented verification). Closes over
+     * the extension the environment was built for.
+     */
+    assetsFor?(): PreparedAssetMap | undefined;
+}
+/** Why a tool could not be dispatched. */
+export interface DispatchFailure {
+    readonly code: 'not-declared' | 'no-implementation' | 'unsupported';
+    readonly message: string;
+    readonly remedy: string;
+}
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export declare function resolveImplementation(manifest: DispatchManifest, toolName: string): {
+    readonly ok: true;
+    readonly tool: DeclaredTool;
+    readonly implementation: DeclaredImplementation;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+};
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export declare function createDispatch(environment: DispatchEnvironment, toolName: string): Promise<{
+    readonly ok: true;
+    readonly execute: (args: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+}>;
+/**
+ * Resolve the implementation chain for a declared CONTRACT id (TASK-121).
+ *
+ * An extension whose manifest declares ONLY implementations (no `tools[]` —
+ * the MiniLM pair's shape) still serves a caller-facing standard tool: the
+ * contract id maps to the standard tool name the host knows, and this
+ * resolution finds the implementation by the contract id alone.
+ * @param manifest - the activated extension's manifest.
+ * @param contractId - the contract identity.
+ * @returns the implementation, or why the chain is incomplete.
+ */
+export declare function resolveImplementationByContract(manifest: DispatchManifest, contractId: string): {
+    readonly ok: true;
+    readonly implementation: DeclaredImplementation;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+};
+/**
+ * Build an `execute` for a standard-named contract tool served by an
+ * IMPLEMENTATION-ONLY extension (TASK-121). The provider is created lazily on
+ * first call, exactly like the declared-tool path.
+ * @param environment - how to reach the extension.
+ * @param contractId - the contract identity to dispatch.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export declare function createDispatchForContract(environment: DispatchEnvironment, contractId: string): Promise<{
+    readonly ok: true;
+    readonly execute: (args: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+}>;
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export declare function describeDispatchFailure(failure: DispatchFailure): string;
+//# sourceMappingURL=extension-dispatch.d.ts.map

package/lib/extension-dispatch.d.ts.map

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

package/lib/extension-dispatch.js

@@ -0,0 +1,178 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-tool-mode/extension-dispatch
+ */
+import { assertNoReservedMeta } from '@try-works/tool-mode-extension-sdk';
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export function resolveImplementation(manifest, toolName) {
+    const tool = manifest.tools.find(candidate => candidate.name === toolName);
+    if (tool === undefined) {
+        return {
+            ok: false,
+            failure: {
+                code: 'not-declared',
+                message: `${toolName} is not declared by this extension's manifest`,
+                remedy: 'A registered tool must be declared in the manifest it was published from.',
+            },
+        };
+    }
+    const implementation = manifest.implementations.find(candidate => candidate.contractId === tool.contractId && candidate.contractVersion === tool.contractVersion);
+    if (implementation === undefined) {
+        /**
+         * THE HONEST REFUSAL, and the case the earlier stub conflated with every other.
+         *
+         * An extension may DECLARE a tool it does not yet serve — EmbeddingGemma does exactly
+         * this, listing contracts whose ONNX path is not wired. The name is legitimately
+         * registered and legitimately uncallable, and the caller must be told WHICH of those
+         * two situations they are in.
+         */
+        return {
+            ok: false,
+            failure: {
+                code: 'no-implementation',
+                message: `${toolName} declares contract ${tool.contractId}, which no implementation serves`,
+                remedy: 'The extension declares this tool but binds no model to it yet; it is not callable in this build.',
+            },
+        };
+    }
+    return { ok: true, tool, implementation };
+}
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export async function createDispatch(environment, toolName) {
+    const resolved = resolveImplementation(environment.getManifest(), toolName);
+    if (!resolved.ok)
+        return resolved;
+    const { implementation } = resolved;
+    return {
+        ok: true,
+        async execute(args, signal) {
+            // Resolved per call rather than captured, so a provider that was unloaded — or an
+            // extension that was deactivated and reactivated — is not served from a stale handle.
+            const provider = await environment.providerFor(implementation.modelId);
+            /**
+             * The HOST-VERIFIED prepared-asset map, when a preparation completed.
+             * An absent map means the empty map — the extension's own load refuses a
+             * missing group by name (MOD-02), which is the honest outcome rather than
+             * a host that invents a verification that never happened. The same map
+             * reaches BOTH provider routes here: the in-process module provider and
+             * the managed worker (its load forwards the assets to the child).
+             */
+            const prepared = environment.assetsFor?.();
+            await provider.load({ assets: prepared ?? { get: () => undefined, assetIds: [] }, signal, modelId: implementation.modelId });
+            const value = await provider.invoke({
+                implementationId: implementation.id,
+                input: args,
+                context: environment.contextFor(implementation.id, signal),
+            });
+            /**
+             * THE EXT-17 META RESERVATION IS ENFORCED HERE, AT THE DISPATCH BOUNDARY.
+             *
+             * The reserved root `meta` is HOST-authored provenance; an extension supplying one
+             * is asserting who ran it and under what receipt, which it does not get to do. The
+             * ProviderBridge asserts this on the CATALOG path, but the contribution path
+             * (module and declarative providers alike) went unasserted — so a provider that
+             * smuggled a `meta` key reached callers whenever its declared output schema did not
+             * require the envelope. Asserting at the boundary the two provider routes share
+             * closes the gap for both, and it runs BEFORE any host stamping, so a forged
+             * envelope is refused rather than overwritten.
+             */
+            assertNoReservedMeta(value, implementation.id);
+            return value;
+        },
+    };
+}
+/**
+ * Resolve the implementation chain for a declared CONTRACT id (TASK-121).
+ *
+ * An extension whose manifest declares ONLY implementations (no `tools[]` —
+ * the MiniLM pair's shape) still serves a caller-facing standard tool: the
+ * contract id maps to the standard tool name the host knows, and this
+ * resolution finds the implementation by the contract id alone.
+ * @param manifest - the activated extension's manifest.
+ * @param contractId - the contract identity.
+ * @returns the implementation, or why the chain is incomplete.
+ */
+export function resolveImplementationByContract(manifest, contractId) {
+    const implementation = manifest.implementations.find(candidate => candidate.contractId === contractId);
+    if (implementation === undefined) {
+        return {
+            ok: false,
+            failure: {
+                code: 'no-implementation',
+                message: `contract ${contractId} has no implementation in this extension's manifest`,
+                remedy: 'The extension declares the contract but binds no model to it.',
+            },
+        };
+    }
+    return { ok: true, implementation };
+}
+/**
+ * Build an `execute` for a standard-named contract tool served by an
+ * IMPLEMENTATION-ONLY extension (TASK-121). The provider is created lazily on
+ * first call, exactly like the declared-tool path.
+ * @param environment - how to reach the extension.
+ * @param contractId - the contract identity to dispatch.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export async function createDispatchForContract(environment, contractId) {
+    const resolved = resolveImplementationByContract(environment.getManifest(), contractId);
+    if (!resolved.ok)
+        return resolved;
+    const { implementation } = resolved;
+    return {
+        ok: true,
+        async execute(args, signal) {
+            const provider = await environment.providerFor(implementation.modelId);
+            const prepared = environment.assetsFor?.();
+            await provider.load({ assets: prepared ?? { get: () => undefined, assetIds: [] }, signal, modelId: implementation.modelId });
+            const value = await provider.invoke({
+                implementationId: implementation.id,
+                input: args,
+                context: environment.contextFor(implementation.id, signal),
+            });
+            assertNoReservedMeta(value, implementation.id);
+            return value;
+        },
+    };
+}
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export function describeDispatchFailure(failure) {
+    return `${failure.message}. ${failure.remedy}`;
+}
+//# sourceMappingURL=extension-dispatch.js.map

package/lib/extension-page-state.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The Extensions-page row state derivation (RC3).
+ *
+ * ONE source of truth for how a describe() row renders. The host payload is
+ * unchanged: `{ installed, active, blocked, reason, requirements[] }` — the
+ * contradiction the RC3 audit found was purely a RENDERING one: the client
+ * drew the lifecycle's `active: true` as a plain "active" badge and an ON
+ * toggle even when the same row's `blocked` flag and an unmet requirement
+ * said activation is refused.
+ *
+ * THE RULE (one sentence): a row that the host reports `blocked` — or that
+ * carries any unmet requirement which blocks this row — is never rendered as
+ * plainly "active"/ON; it renders the blocked badge and an OFF visual toggle
+ * whose enabled/disabled state and title are unchanged.
+ *
+ * This module is dependency-free and pure so the SAME classification is
+ * testable in Node and documented as the contract the client bundle
+ * implements (the bundle inlines the identical rule; the test pins this
+ * module, and the client's rule is kept verbatim-adjacent).
+ *
+ * @module @try-works/dsh-tool-mode/extension-page-state
+ */
+/** One requirement as the describe() payload carries it. */
+export interface PageRequirement {
+    readonly kind: string;
+    readonly satisfied: boolean;
+    readonly reason: string;
+}
+/** The fields of the describe() row this derivation reads. */
+export interface ExtensionPageRow {
+    readonly installed: boolean;
+    readonly active: boolean;
+    readonly blocked: boolean;
+    readonly reason: string | null;
+    readonly requirements: readonly PageRequirement[];
+}
+/**
+ * Whether one UNMET requirement blocks THIS row.
+ * @param installed - whether the store holds an installed copy.
+ * @param requirement - the requirement to classify.
+ */
+export declare function requirementBlocksRow(installed: boolean, requirement: PageRequirement): boolean;
+/** The badge a row renders: the lifecycle fact, qualified by the block. */
+export type PageBadge = 'not-installed' | 'active' | 'active-blocked' | 'inactive';
+/** The derived rendering state for one describe() row. */
+export interface ExtensionPageState {
+    /** The badge text class: 'active' ONLY when active and not blocked. */
+    readonly badge: PageBadge;
+    /** The visual toggle: ON only when active and not blocked (blocked rows render OFF). */
+    readonly toggleOn: boolean;
+    /**
+     * The lifecycle fact behind the badge/toggle, preserved so the aria state
+     * and the action title can still say what the store observes.
+     */
+    readonly active: boolean;
+    /** The host's blocked flag, verbatim. */
+    readonly blocked: boolean;
+    /** The unmet requirements that block this row (in host order). */
+    readonly blockingReasons: readonly string[];
+    /** The unmet requirements that are post-install notes for this row. */
+    readonly noteReasons: readonly string[];
+}
+/**
+ * Derive the page state for one describe() row.
+ * @param row - the describe() payload.
+ * @returns the badge/toggle/note derivation.
+ */
+export declare function extensionPageState(row: ExtensionPageRow): ExtensionPageState;
+//# sourceMappingURL=extension-page-state.d.ts.map

package/lib/extension-page-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-page-state.d.ts","sourceRoot":"","sources":["../src/extension-page-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAA;CAClD;AAoBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,GAAG,OAAO,CAI9F;AAED,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,CAAA;AAElF,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,kBAAkB,CAuB5E"}

package/lib/extension-page-state.js

@@ -0,0 +1,82 @@
+/**
+ * The Extensions-page row state derivation (RC3).
+ *
+ * ONE source of truth for how a describe() row renders. The host payload is
+ * unchanged: `{ installed, active, blocked, reason, requirements[] }` — the
+ * contradiction the RC3 audit found was purely a RENDERING one: the client
+ * drew the lifecycle's `active: true` as a plain "active" badge and an ON
+ * toggle even when the same row's `blocked` flag and an unmet requirement
+ * said activation is refused.
+ *
+ * THE RULE (one sentence): a row that the host reports `blocked` — or that
+ * carries any unmet requirement which blocks this row — is never rendered as
+ * plainly "active"/ON; it renders the blocked badge and an OFF visual toggle
+ * whose enabled/disabled state and title are unchanged.
+ *
+ * This module is dependency-free and pure so the SAME classification is
+ * testable in Node and documented as the contract the client bundle
+ * implements (the bundle inlines the identical rule; the test pins this
+ * module, and the client's rule is kept verbatim-adjacent).
+ *
+ * @module @try-works/dsh-tool-mode/extension-page-state
+ */
+/**
+ * The requirement kinds that block a NOT-installed row.
+ *
+ * Mirrors the host service's classification (extensions-service.ts
+ * `blocksRow`): store/source, dependencies, platform, harness-model and
+ * runtime stop the INSTALL or make the eventual activation impossible.
+ * Readiness/executable/integrity/activation/assets describe installed bytes
+ * and are post-install facts, never pre-install blockers.
+ */
+const NOT_INSTALLED_BLOCKING_KINDS = new Set([
+    'store',
+    'source',
+    'dependencies',
+    'platform',
+    'harness-model',
+    'runtime',
+]);
+/**
+ * Whether one UNMET requirement blocks THIS row.
+ * @param installed - whether the store holds an installed copy.
+ * @param requirement - the requirement to classify.
+ */
+export function requirementBlocksRow(installed, requirement) {
+    if (requirement.satisfied)
+        return false;
+    if (installed)
+        return true;
+    return NOT_INSTALLED_BLOCKING_KINDS.has(requirement.kind);
+}
+/**
+ * Derive the page state for one describe() row.
+ * @param row - the describe() payload.
+ * @returns the badge/toggle/note derivation.
+ */
+export function extensionPageState(row) {
+    const blocking = [];
+    const notes = [];
+    for (const requirement of row.requirements) {
+        if (requirement.satisfied)
+            continue;
+        (requirementBlocksRow(row.installed, requirement) ? blocking : notes).push(requirement.reason);
+    }
+    const blocked = row.blocked || blocking.length > 0;
+    const badge = !row.installed
+        ? 'not-installed'
+        : row.active && blocked
+            ? 'active-blocked'
+            : row.active
+                ? 'active'
+                : 'inactive';
+    return {
+        badge,
+        toggleOn: row.active && !blocked,
+        active: row.active,
+        blocked,
+        blockingReasons: blocking,
+        noteReasons: notes,
+    };
+}
+//# sourceMappingURL=extension-page-state.js.map

package/lib/extension-registrar.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The host-side contribution registrar (EXT-21..EXT-30, ARCH-06).
+ *
+ * This is the bridge that was MISSING: `ExtensionLifecycle` could install, activate and
+ * publish contributions, and the SDK was fully tested doing so — but the HOST never
+ * mounted the lifecycle, so **no extension's tools ever reached the DSH registry**. An
+ * extension could be installed, activated and reported `observedActivation: 'active'` with
+ * its tool listed, and a caller still could not invoke it.
+ *
+ * The registrar is the other half: it turns a published contribution into a real registry
+ * entry, and withdraws it again on deactivation.
+ *
+ * Four rules, each of which has been a real defect somewhere:
+ *
+ * - **Handles are opaque and unguessable.** An extension must not be able to construct a
+ *   handle and withdraw a contribution it does not own. A sequence number is guessable;
+ *   the handle is a branded object the caller never sees the inside of.
+ * - **Withdrawing is idempotent.** A deactivation that runs twice must not throw the
+ *   second time, and must not withdraw a DIFFERENT contribution that reused the handle.
+ * - **A name collision is refused, not silently overwritten.** Two extensions contributing
+ *   `transcribe` is a configuration error; letting the second win would silently change
+ *   what an existing caller reaches.
+ * - **The host stamps identity.** The contribution carries an extension id, but the HOST
+ *   decides what that means; a package claiming another's id is refused rather than
+ *   trusted.
+ *
+ * @module @try-works/dsh-tool-mode/extension-registrar
+ */
+import type { Contribution, ContributionRegistrar } from '@try-works/tool-mode-extension-sdk';
+/** One thing the registrar can put into the DSH registry. */
+export interface RegistrableTool {
+    /** The caller-facing tool name. */
+    readonly name: string;
+    /** The extension that owns it, as the HOST resolved it. */
+    readonly ownerExtension: string;
+    /** The contract it implements, when it declares one. */
+    readonly contractId?: string;
+}
+/** What the registrar needs from the host registry. */
+export interface HostRegistrySurface {
+    /**
+     * Register one tool.
+     * @param tool - the tool, with identity already stamped by the host.
+     * @returns a disposer that removes it.
+     */
+    registerTool(tool: RegistrableTool): () => void;
+    /** Register one skill, returning a disposer. */
+    registerSkill?(skill: {
+        readonly name: string;
+        readonly ownerExtension: string;
+    }): () => void;
+    /**
+     * Register the CALLER-FACING tools of one declarative implementation (RCP-01).
+     *
+     * A declarative package declares implementations only — its manifest has no
+     * `tools` array — so the tool names and schemas come from the RESOLVED RECIPES,
+     * which only the host can turn into registry entries (the recipes need the
+     * deployment's harness provider to be served at all). The contribution arrives
+     * per implementation; the host resolves the package's recipes and registers the
+     * matching tool, returning its disposer. Absent (or a non-declarative package)
+     * keeps the earlier behavior: implementations publish nothing.
+     */
+    registerDeclarative?(contribution: {
+        readonly extensionId: string;
+        readonly name: string;
+        readonly contractId?: string;
+    }): () => void;
+    /**
+     * Register the STANDARD-named contract tool for a MODULE implementation
+     * whose contract the host knows a standard name for (TASK-121).
+     *
+     * A module package that declares ONLY implementations (no `tools[]` — the
+     * MiniLM pair's shape) serves the standard contract directly: the host maps
+     * the contract id to its standard tool name (text.embed -> text_embed) and
+     * registers the tool with the contract's own schemas. Returns a disposer
+     * when it registered, or undefined when the contract is not a standard one
+     * (the declarative branch below then handles it).
+     */
+    registerContractImplementation?(contribution: {
+        readonly extensionId: string;
+        readonly contractId: string;
+        readonly implementationId: string;
+    }): (() => void) | undefined;
+}
+/** Raised when a contribution cannot be published. */
+export declare class ContributionError extends Error {
+    readonly name = "ContributionError";
+    readonly code: 'name-collision' | 'unsupported-kind' | 'unknown-extension';
+    constructor(code: ContributionError['code'], message: string);
+}
+/**
+ * The published contributions, keyed by handle id.
+ *
+ * A Map rather than a field on the handle, so an extension that receives a handle cannot
+ * reach the disposer or another extension's entry through it.
+ */
+export interface RegistrarOptions {
+    readonly registry: HostRegistrySurface;
+    /**
+     * The extensions the host has ACTIVATED.
+     *
+     * A contribution from an extension not in this set is refused: publishing is a privilege
+     * of activation, and without this check any code holding the registrar could register a
+     * tool under an extension that was never installed.
+     */
+    readonly activated: ReadonlySet<string>;
+    /** Called when a contribution is refused, so the reason is recorded rather than lost. */
+    readonly onRefused?: (contribution: Contribution, error: ContributionError) => void;
+}
+/**
+ * Create the registrar the lifecycle publishes through.
+ * @param options - the registry surface and the activated set.
+ * @returns the registrar.
+ */
+export declare function createContributionRegistrar(options: RegistrarOptions): ContributionRegistrar;
+//# sourceMappingURL=extension-registrar.d.ts.map

package/lib/extension-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-registrar.d.ts","sourceRoot":"","sources":["../src/extension-registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAA;AAE7F,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,IAAI,CAAA;IAC/C,gDAAgD;IAChD,aAAa,CAAC,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,IAAI,CAAA;IAC7F;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,CAAC,YAAY,EAAE;QACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAC7B,GAAG,MAAM,IAAI,CAAA;IACd;;;;;;;;;;OAUG;IACH,8BAA8B,CAAC,CAAC,YAAY,EAAE;QAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;KAClC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CAC7B;AAED,sDAAsD;AACtD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAsB;IAC5C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,mBAAmB,CAAA;gBAC9D,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAI7D;AAUD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACvC,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;CACpF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,gBAAgB,GAAG,qBAAqB,CA2G5F"}