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

package/lib/authority.js

@@ -0,0 +1,194 @@
+/**
+ * Caller authority: the grant a tool invocation runs under (SEC-03, SEC-06).
+ *
+ * The governing rule is BASE-05: an external request cannot supply or forge these
+ * authorities. Everything here is constructed by the HOST from operator
+ * configuration, never from a request body, a `clientInfo.name`, a requested tool
+ * list, or a path a caller supplied. A caller's arguments are then checked
+ * AGAINST the grant; they never expand it.
+ *
+ * Path handling is deliberately paranoid. SEC-06 requires resolving Windows drive
+ * letters, separators, Unicode, junctions and symlinks safely, rejecting escapes,
+ * unsupported UNC/device paths and unauthorized roots, and refusing when
+ * authorization cannot be established. The resolver therefore returns the
+ * CANONICAL path for the caller to open, rather than validating a string and
+ * letting a later open re-resolve it — that gap is the classic check-then-open
+ * race, and a symlink swapped between the two steps would win it.
+ *
+ * @module @try-works/dsh-model-as-tool/authority
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, sep } from 'node:path';
+/** A refused invocation. Carries a recovery hint, not just a refusal. */
+export class AuthorityError extends Error {
+    name = 'AuthorityError';
+    code;
+    /** Actionable next step for the caller or operator. */
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}
+/** Conservative defaults: a grant that declares nothing permits almost nothing. */
+export const DEFAULT_LIMITS = {
+    maxInputBytes: 64 * 1024 * 1024,
+    maxAudioSeconds: 3600,
+    maxResultBytes: 8 * 1024 * 1024,
+};
+/** Whether this process is on a case-insensitive filesystem. */
+const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin';
+/**
+ * Canonicalize a root for containment comparison.
+ *
+ * A root that does not exist is still admitted, because an operator may declare a
+ * root before creating it; it simply can never contain anything until it exists,
+ * which fails closed.
+ * @param root - the declared root.
+ * @returns the canonical root, or undefined when it cannot be resolved yet.
+ */
+function canonicalizeRoot(root) {
+    if (!isAbsolute(root))
+        return undefined;
+    try {
+        return realpathSync.native(root);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a grant from operator configuration.
+ *
+ * This is the only constructor: a request cannot reach it, and an approved root
+ * that is not absolute or not resolvable is dropped rather than trusted.
+ * @param input - the operator's declaration.
+ * @returns the canonicalized grant.
+ */
+export function createGrant(input) {
+    const roots = [];
+    for (const root of input.approvedRoots) {
+        const canonical = canonicalizeRoot(root);
+        // A root that cannot be canonicalized is dropped, not guessed at. Dropping
+        // fails closed; keeping an unresolved string would fail open.
+        if (canonical !== undefined)
+            roots.push(canonical);
+    }
+    return {
+        grantId: input.grantId,
+        allowedTools: [...input.allowedTools],
+        approvedRoots: roots,
+        remoteDestinations: [...(input.remoteDestinations ?? [])],
+        hostedCode: input.hostedCode ?? false,
+        recordingPolicy: input.recordingPolicy ?? 'none',
+        limits: { ...DEFAULT_LIMITS, ...input.limits },
+    };
+}
+/** Compare two paths for equality under this platform's case rules. */
+function samePath(a, b) {
+    return CASE_INSENSITIVE ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+/** Whether `child` is `root` itself or lies beneath it, on a separator boundary. */
+function isWithin(child, root) {
+    if (samePath(child, root))
+        return true;
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return CASE_INSENSITIVE
+        ? child.toLowerCase().startsWith(prefix.toLowerCase())
+        : child.startsWith(prefix);
+}
+/**
+ * Reject path shapes v1 does not admit, before any filesystem call.
+ * @param candidate - the caller-supplied path.
+ * @throws AuthorityError with `PATH_UNSUPPORTED` or `PATH_NOT_ABSOLUTE`.
+ */
+function assertAdmissibleShape(candidate) {
+    // Windows device namespaces bypass normal path handling entirely, and a UNC
+    // path reaches another host that no approved root can describe.
+    if (candidate.startsWith('\\\\') || candidate.startsWith('//')) {
+        throw new AuthorityError('PATH_UNSUPPORTED', 'UNC and Windows device paths are not admitted', 'Use an absolute path on a local drive that lies under an approved root.');
+    }
+    if (candidate.includes('\0')) {
+        throw new AuthorityError('PATH_UNSUPPORTED', 'the path contains a NUL byte', 'Pass the path as a plain string without embedded control characters.');
+    }
+    if (!isAbsolute(candidate)) {
+        throw new AuthorityError('PATH_NOT_ABSOLUTE', 'relative paths are not admitted; v1 authorizes absolute paths only', 'Resolve the path to an absolute path under an approved root before calling.');
+    }
+}
+/**
+ * Authorize one caller-supplied path against a grant (SEC-06).
+ *
+ * Returns the CANONICAL path, which the caller must open. Validating the original
+ * string and opening it later would leave a window in which a symlink could be
+ * swapped; resolving once and returning the result closes it.
+ * @param grant - the caller's grant.
+ * @param candidate - the caller-supplied path.
+ * @returns the canonical, authorized path.
+ * @throws AuthorityError when the path is inadmissible, missing, or outside the grant.
+ */
+export function authorizePath(grant, candidate) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+        throw new AuthorityError('PATH_NOT_ABSOLUTE', 'a path is required', 'Supply an absolute path under an approved root.');
+    }
+    assertAdmissibleShape(candidate);
+    let canonical;
+    try {
+        // Resolves junctions and symlinks, so containment is checked against what the
+        // path actually IS rather than what it spells.
+        canonical = realpathSync.native(candidate);
+    }
+    catch {
+        throw new AuthorityError('PATH_NOT_FOUND', 'the path does not exist, so it cannot be authorized', 'Check the path, or ask the operator to add its root to the grant.');
+    }
+    for (const root of grant.approvedRoots) {
+        if (isWithin(canonical, root))
+            return canonical;
+    }
+    // The message names the grant, not the allowed roots: enumerating a caller's
+    // permitted directories would disclose the operator's configuration.
+    throw new AuthorityError('PATH_OUTSIDE_GRANT', 'the path resolves outside every root approved for this caller', 'Ask the operator to add the containing root to this grant.');
+}
+/**
+ * Authorize a tool name against a grant (SEC-03).
+ * @param grant - the caller's grant.
+ * @param toolName - the requested tool.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export function authorizeTool(grant, toolName) {
+    if (!grant.allowedTools.includes(toolName)) {
+        throw new AuthorityError('TOOL_NOT_GRANTED', `tool "${toolName}" is not granted to this caller`, 'Request access from the operator; a requested tool list does not extend a grant.');
+    }
+}
+/**
+ * Authorize a remote destination against a grant (SEC-10).
+ *
+ * No silent local-to-remote fallback: if a destination was not explicitly
+ * approved, the call is refused rather than downgraded or upgraded.
+ * @param grant - the caller's grant.
+ * @param destination - the destination origin.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export function authorizeDestination(grant, destination) {
+    if (!grant.remoteDestinations.includes(destination)) {
+        throw new AuthorityError('TOOL_NOT_GRANTED', `destination "${destination}" is not authorized for this caller`, 'A remote destination requires explicit authorization; there is no silent fallback.');
+    }
+}
+/**
+ * Build the invocation authority for one call.
+ *
+ * The result is constructed by the host; a request body has no path to it.
+ * @param grant - the caller's grant.
+ * @param callerKind - how the host classified the caller.
+ * @returns the authority handed to the implementation.
+ */
+export function createInvocationAuthority(grant, callerKind) {
+    return {
+        grantId: grant.grantId,
+        callerKind,
+        limits: grant.limits,
+        recordingPolicy: grant.recordingPolicy,
+        resolvePath: candidate => authorizePath(grant, candidate),
+    };
+}
+//# sourceMappingURL=authority.js.map

package/lib/bindings.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Contract-driven registration: one tool per contract, not one per model.
+ *
+ * This is the host half of BASE-02. The contract decides the tool's name, schema
+ * and description; the implementation behind it is host configuration. A second
+ * model implementing `stt.transcribe` therefore joins the existing
+ * `stt_transcribe` tool rather than appearing as a competing duplicate — which is
+ * the behaviour the previous per-model registrar could not express.
+ *
+ * The host also owns provenance (DECL-03): `meta` is stamped here, from host
+ * state, so an implementation cannot claim another package's identity.
+ *
+ * @module @try-works/dsh-model-as-tool/bindings
+ */
+import { type ExecutionLocation, type ToolContract, type ToolMeta } from '@try-works/tool-mode-contracts';
+import type { ModelCatalogEntry, ModelRoute } from './types.ts';
+import { type InvocationReceipt } from './receipt.ts';
+import { type InvocationAuthority, type ToolGrant } from './authority.ts';
+import type { ModelAdapter } from './adapters/index.ts';
+/** Host identity stamped into every result. */
+export interface HostIdentity {
+    /** The host package name. */
+    readonly extension: string;
+    /** The host package version. */
+    readonly extensionVersion: string;
+    /** Activation generation, incremented when the tool surface changes. */
+    readonly activationGeneration: number;
+    /** Receipt id factory; injectable so tests are deterministic. */
+    readonly nextReceiptId: () => string;
+    /**
+     * The grant this tool surface runs under (SEC-03).
+     *
+     * Built by the host from operator configuration. A caller's request cannot
+     * reach it, which is what makes the authority trustworthy (BASE-05).
+     */
+    readonly grant: ToolGrant;
+    /** How the host classified this caller. */
+    readonly callerKind: InvocationAuthority['callerKind'];
+    /**
+     * Where an invocation receipt is delivered (EXT-35).
+     *
+     * Optional so a host without a receipt store still works; when present it sees one
+     * receipt per SUCCESSFUL call, which is what makes the provenance recoverable
+     * after the fact rather than only during the call.
+     */
+    readonly recordReceipt?: (receipt: InvocationReceipt) => void;
+}
+/** One contract with the implementation chosen to serve it. */
+export interface ContractBinding {
+    /** The contract that defines the tool. */
+    readonly contract: ToolContract;
+    /** The catalog entry selected to execute it. */
+    readonly implementation: ModelCatalogEntry;
+    /** The adapter that invokes that model. */
+    readonly adapter: ModelAdapter;
+    /** The route the capability resolver proved, used for `executionLocation`. */
+    readonly route: ModelRoute;
+    /** Other runnable implementations of the same contract, for reporting. */
+    readonly alternatives: readonly string[];
+}
+/**
+ * Translate a resolver route into the caller-facing execution location (SPEC §6).
+ *
+ * "Local" is deliberately not one value: a bridge is another machine, and a
+ * caller reasoning about data boundaries needs to know which.
+ * @param route - the resolved route.
+ * @returns the declared execution location.
+ */
+export declare function executionLocationOf(route: ModelRoute): ExecutionLocation;
+/**
+ * Build the `meta` envelope for one execution.
+ *
+ * Every field comes from host state or the contract, never from the model's
+ * output, which is what makes the provenance trustworthy (DECL-03).
+ * @param binding - the contract and implementation that are executing.
+ * @param host - the host identity to stamp.
+ * @param warnings - non-fatal conditions observed during this call.
+ * @returns the envelope.
+ */
+export declare function buildMeta(binding: Pick<ContractBinding, 'contract' | 'implementation' | 'route'>, host: HostIdentity, warnings?: readonly string[]): ToolMeta;
+/**
+ * Build the EXT-35 receipt for one call.
+ *
+ * Separate from {@link buildMeta} because it answers a different question: the
+ * envelope says what the caller received, while the receipt says what RAN and from
+ * which bytes. The extra provenance — the extension package, its content digest,
+ * the model and recipe identity — is what makes a receipt usable after the fact,
+ * when the version alone no longer identifies the code.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity and the receipt factory.
+ * @param meta - the envelope already stamped, for the receipt identity.
+ * @returns the invocation receipt.
+ */
+export declare function buildReceipt(binding: Pick<ContractBinding, 'contract' | 'implementation' | 'route'>, host: HostIdentity, meta: Pick<ToolMeta, 'receiptId'>, warnings?: readonly string[]): InvocationReceipt;
+/**
+ * Register one contract as a single DSH tool.
+ *
+ * The tool body validates arguments against the contract, applies the cross-field
+ * rules the DSH DSL cannot express, invokes the selected implementation, then
+ * validates the RESULT before returning it. A violation surfaces as a tool
+ * failure rather than as malformed data reaching a caller (AT-11).
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity to stamp into results.
+ * @returns the registered tool name and the registry disposer.
+ */
+export declare function registerContractTool(ctx: {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+}, binding: ContractBinding, host: HostIdentity): {
+    toolName: string;
+    dispose: () => void;
+};
+//# sourceMappingURL=bindings.d.ts.map

package/lib/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,gCAAgC,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,qBAAqB,CAAA;AAElE,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,wEAAwE;IACxE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAA;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IACtD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAC9D;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,iBAAiB,CAAA;IAC1C,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,CAaxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,gBAAgB,GAAG,OAAO,CAAC,EACvE,IAAI,EAAE,YAAY,EAClB,QAAQ,GAAE,SAAS,MAAM,EAAO,GAC/B,QAAQ,CAYV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,gBAAgB,GAAG,OAAO,CAAC,EACvE,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,EACjC,QAAQ,GAAE,SAAS,MAAM,EAAO,GAC/B,iBAAiB,CAoBnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE;IAAE,KAAK,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;KAAE,CAAA;CAAE,EAC7D,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GACjB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAoG3C"}

package/lib/bindings.js

@@ -0,0 +1,239 @@
+/**
+ * Contract-driven registration: one tool per contract, not one per model.
+ *
+ * This is the host half of BASE-02. The contract decides the tool's name, schema
+ * and description; the implementation behind it is host configuration. A second
+ * model implementing `stt.transcribe` therefore joins the existing
+ * `stt_transcribe` tool rather than appearing as a competing duplicate — which is
+ * the behaviour the previous per-model registrar could not express.
+ *
+ * The host also owns provenance (DECL-03): `meta` is stamped here, from host
+ * state, so an implementation cannot claim another package's identity.
+ *
+ * @module @try-works/dsh-model-as-tool/bindings
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { assertValidContract, assertValidInput, assertValidOutput, crossFieldRules, toDshParameters, } from '@try-works/tool-mode-contracts';
+import { toContractPayload, toNativeArgs } from "./contract-payload.js";
+import { buildInvocationReceipt } from "./receipt.js";
+import { authorizeTool, createInvocationAuthority, } from "./authority.js";
+/**
+ * Translate a resolver route into the caller-facing execution location (SPEC §6).
+ *
+ * "Local" is deliberately not one value: a bridge is another machine, and a
+ * caller reasoning about data boundaries needs to know which.
+ * @param route - the resolved route.
+ * @returns the declared execution location.
+ */
+export function executionLocationOf(route) {
+    switch (route) {
+        case 'npm-native':
+        case 'npm-onnxruntime':
+            return 'host';
+        case 'cli':
+            return 'host';
+        case 'remote':
+            return 'team-server';
+        /* v8 ignore next -- closed union; a new route must fail compilation here. */
+        default:
+            return 'host';
+    }
+}
+/**
+ * Build the `meta` envelope for one execution.
+ *
+ * Every field comes from host state or the contract, never from the model's
+ * output, which is what makes the provenance trustworthy (DECL-03).
+ * @param binding - the contract and implementation that are executing.
+ * @param host - the host identity to stamp.
+ * @param warnings - non-fatal conditions observed during this call.
+ * @returns the envelope.
+ */
+export function buildMeta(binding, host, warnings = []) {
+    return {
+        contract: binding.contract.contract,
+        contractVersion: binding.contract.version,
+        implementationId: binding.implementation.id,
+        extension: host.extension,
+        extensionVersion: host.extensionVersion,
+        activationGeneration: host.activationGeneration,
+        executionLocation: executionLocationOf(binding.route),
+        receiptId: host.nextReceiptId(),
+        warnings: [...warnings],
+    };
+}
+/**
+ * Build the EXT-35 receipt for one call.
+ *
+ * Separate from {@link buildMeta} because it answers a different question: the
+ * envelope says what the caller received, while the receipt says what RAN and from
+ * which bytes. The extra provenance — the extension package, its content digest,
+ * the model and recipe identity — is what makes a receipt usable after the fact,
+ * when the version alone no longer identifies the code.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity and the receipt factory.
+ * @param meta - the envelope already stamped, for the receipt identity.
+ * @returns the invocation receipt.
+ */
+export function buildReceipt(binding, host, meta, warnings = []) {
+    return buildInvocationReceipt({
+        receiptId: meta.receiptId,
+        contract: binding.contract.contract,
+        contractVersion: binding.contract.version,
+        implementationId: binding.implementation.id,
+        extension: binding.implementation.provider?.extension
+            ?? host.extension,
+        extensionVersion: host.extensionVersion,
+        // The catalog carries no digest, so it is reported as unknown rather than
+        // invented. A receipt that guesses at provenance is worse than one that admits
+        // it does not have it.
+        extensionContentDigest: null,
+        dependencyLockDigest: null,
+        modelIdentity: binding.implementation.provider?.modelId ?? binding.implementation.id,
+        recipeVersion: null,
+        activationGeneration: host.activationGeneration,
+        executionLocation: executionLocationOf(binding.route),
+        warnings,
+    });
+}
+/**
+ * Register one contract as a single DSH tool.
+ *
+ * The tool body validates arguments against the contract, applies the cross-field
+ * rules the DSH DSL cannot express, invokes the selected implementation, then
+ * validates the RESULT before returning it. A violation surfaces as a tool
+ * failure rather than as malformed data reaching a caller (AT-11).
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity to stamp into results.
+ * @returns the registered tool name and the registry disposer.
+ */
+export function registerContractTool(ctx, binding, host) {
+    const { contract, adapter, implementation } = binding;
+    // Registration and argument validation must agree, so the contract is checked
+    // here rather than trusted: a definition that cannot compile would otherwise
+    // fail only when a caller happened to hit the broken branch.
+    assertValidContract(contract);
+    const rules = crossFieldRules(contract);
+    const definition = defineTool({
+        name: contract.toolName,
+        description: contract.description,
+        // `toDshParameters` returns the projected JSON-Schema subset; the registry's
+        // DSL type is structurally narrower, and `ProjectionError` has already
+        // refused any keyword the DSL cannot express.
+        parameters: toDshParameters(contract),
+        output: {
+            /**
+             * An open object schema, and DECL-02 names this as INADEQUATE.
+             *
+             * The requirement says in as many words that an unconstrained
+             * `{type: "object", additionalProperties: true}` is not an adequate implementation
+             * of an ordinary leaf tool's contract. It is right, and this repository cannot yet
+             * do better: the contract's real output schema CANNOT be projected into DSH's
+             * value-schema DSL. Attempting it produced four distinct rejections at
+             * registration, recorded here because the next person will try the same thing:
+             *
+             *   1. `schema.required is not supported by the value schema DSL`
+             *   2. `schema.properties.candidates.items.required is not supported` - so required
+             *      is unsupported at EVERY depth, not merely at the root
+             *   3. `schema.properties.words.items is not supported` - `items` is in the
+             *      documented supported set but its support does not extend to an array nested
+             *      inside an object, which is what every output schema has
+             *   4. `schema.properties.reliability.enum must be a non-empty array of scalar
+             *      values` - and separate attempts to express the union type as `oneOf` were
+             *      rejected too, with `oneOf must be an array of at least two value schemas`
+             *
+             * Stripping each keyword in turn does converge, but it converges on a schema that
+             * advertises almost nothing while APPEARING to be a real declaration - which is
+             * worse than this open object, because a client would trust it. The contract
+             * itself is unchanged and complete: `assertValidOutput` enforces the real schema at
+             * runtime against the untouched contract, so results ARE validated. What is
+             * missing is the ADVERTISEMENT.
+             */
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const record = value;
+                return [{ type: 'text', text: renderForModel(contract, record) }];
+            },
+        },
+        async execute(args, exec) {
+            const record = args;
+            assertValidInput(contract, record);
+            for (const rule of rules) {
+                const violation = rule(record);
+                if (violation !== undefined) {
+                    throw new Error(`${contract.toolName}: ${violation}`);
+                }
+            }
+            // SEC-03: the grant is consulted before any work happens, so an ungranted
+            // tool is refused before inference rather than after it.
+            authorizeTool(host.grant, contract.toolName);
+            const authority = createInvocationAuthority(host.grant, host.callerKind);
+            // The contract's caller-facing arguments are translated into the adapter's
+            // native vocabulary before invocation; the reverse translation runs on the
+            // result. Both are explicit, so a name change on either side is a compile-
+            // or test-time failure rather than a runtime mystery.
+            const nativeArgs = toNativeArgs(contract.contract, record);
+            const native = await adapter.invoke({ args: nativeArgs, signal: exec.signal, authority });
+            // The implementation's native result is translated into the contract's
+            // payload before validation: the contract is the authority, so a mismatch is
+            // resolved here rather than by loosening the schema.
+            const payload = toContractPayload(contract.contract, native, record);
+            // `ToolMeta` is a plain interface without an index signature, so it is not
+            // structurally a `JsonValue`; the value is losslessly JSON either way, and
+            // `assertValidOutput` is the real check.
+            const meta = buildMeta(binding, host);
+            const value = { ...payload, meta };
+            assertValidOutput(contract, value);
+            // EXT-35: the receipt is emitted once the call SUCCEEDED. A receipt for a
+            // call that failed validation would claim provenance for a result nobody
+            // received, so the sink sees only calls that actually completed.
+            host.recordReceipt?.(buildReceipt(binding, host, meta));
+            return value;
+        },
+        presentCall(callArgs) {
+            const primary = Object.values(callArgs)[0];
+            return {
+                card: 'generic',
+                title: contract.toolName,
+                kind: 'read',
+                ...typeof primary === 'string' ? { rawInput: primary } : {},
+            };
+        },
+    });
+    void implementation;
+    return { toolName: contract.toolName, dispose: ctx.tools.register(definition) };
+}
+/**
+ * Render a contract result for the model.
+ *
+ * The canonical value is the source of truth; this only chooses the presentation.
+ * It never invents a field the contract did not declare.
+ * @param contract - the contract that produced the value.
+ * @param value - the validated canonical value.
+ * @returns a short text projection.
+ */
+function renderForModel(contract, value) {
+    if (contract.contract === 'text.language_detect') {
+        const language = value.language;
+        const candidates = Array.isArray(value.candidates) ? value.candidates : [];
+        const detail = candidates
+            .filter((candidate) => typeof candidate === 'object' && candidate !== null
+            && typeof candidate.language === 'string')
+            .map(candidate => `${candidate.language} ${(candidate.probability * 100).toFixed(1)}%`)
+            .join(', ');
+        const tooClose = value.tooCloseToCall === true ? ' (too close to call)' : '';
+        return `Detected language: ${String(language)}${tooClose}`
+            + (detail.length > 0 ? `\nCandidates: ${detail}` : '');
+    }
+    if (contract.contract === 'stt.transcribe') {
+        const text = typeof value.text === 'string' ? value.text : '';
+        const coverage = value.coverage;
+        const partial = coverage?.complete === false
+            ? `\n[warnings] partial transcript: ${String(coverage.transcribedSeconds ?? 0)}s covered\n`
+            : '';
+        return text.length > 0 ? `${text}${partial}` : `(no speech recognized)${partial}`;
+    }
+    return JSON.stringify(value, null, 2);
+}
+//# sourceMappingURL=bindings.js.map

package/lib/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAA0D,MAAM,YAAY,CAAA;AAE3G,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,QAEhC,CAAA;AAWD,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,kBAAiB;CACxC;AA8CD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAqGhG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAA6B,GAAG,iBAAiB,EAAE,CA6BpF;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAElG"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAA0D,MAAM,YAAY,CAAA;AAE3G,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,QAEhC,CAAA;AAWD,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,kBAAiB;CACxC;AAyGD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAuGhG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAA6B,GAAG,iBAAiB,EAAE,CA6BpF;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAElG"}

package/lib/catalog.js

@@ -62,6 +62,61 @@ function parseParam(raw, scope, key) {
     }
     throw new CatalogError(`${scope} tool.params.${key} must be a description string or a parameter object`);
 }
+/**
+ * Validate the optional `contract` binding.
+ *
+ * A model without a contract is legitimate — it keeps a per-model tool — but a
+ * malformed contract identity would bind a tool to a name no caller can address,
+ * so it fails at load rather than at registration.
+ * @param value - the raw field.
+ * @param scope - entry description for error messages.
+ * @param source - document description for error messages.
+ * @returns the contract id, or null when unbound.
+ */
+/**
+ * Parse a model's extension provider binding (BASE-09).
+ *
+ * The binding names the package that implements the model. It is validated here
+ * rather than trusted, because it decides which package's code the host will
+ * import: a malformed binding must fail the catalog load rather than surface later
+ * as an import of something unintended.
+ * @param raw - the raw `provider` field.
+ * @param source - the catalog source, for error messages.
+ * @returns the binding field, or an empty object when absent.
+ */
+function parseProvider(raw, source) {
+    if (raw === undefined || raw === null)
+        return {};
+    const value = raw;
+    const extension = value.extension;
+    const modelId = value.modelId;
+    if (typeof extension !== 'string' || extension.length === 0) {
+        throw new Error(`${source}: provider.extension must be a non-empty package name`);
+    }
+    if (typeof modelId !== 'string' || modelId.length === 0) {
+        throw new Error(`${source}: provider.modelId must be a non-empty string`);
+    }
+    // A relative path is admitted so a first-party package can be exercised from a
+    // checkout; anything else must look like a package specifier.
+    const packageLike = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(extension);
+    const relativeLike = extension.startsWith('./') || extension.startsWith('../');
+    if (!packageLike && !relativeLike) {
+        throw new Error(`${source}: provider.extension ${JSON.stringify(extension)} is neither a package specifier nor a relative path`);
+    }
+    return { provider: { extension, modelId } };
+}
+function parseContract(value, scope, source) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string') {
+        throw new CatalogError(`${source}: ${scope} field "contract" must be a contract id or null`);
+    }
+    if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(value)) {
+        throw new CatalogError(`${source}: ${scope} field "contract" ${JSON.stringify(value)} must be a dotted lower-case `
+            + 'contract identity (for example "stt.transcribe")');
+    }
+    return value;
+}
 /**
  * Parse and validate one catalog entry. Validation is strict on purpose: every
  * downstream decision (which tool to register, whether it can run, what the
@@ -139,6 +194,8 @@ export function parseCatalogEntry(raw, source, index) {
         name: requireString(entry, 'name', source),
         summary: requireString(entry, 'summary', source),
         capability: requireString(entry, 'capability', source),
+        contract: parseContract(entry.contract, scope, source),
+        ...parseProvider(entry.provider, source),
         input: input,
         output: requireString(entry, 'output', source),
         languages: nullableNumber('languages'),