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

package/lib/publication.js

@@ -0,0 +1,173 @@
+/**
+ * Coherent publication from one versioned generation (EXT-24).
+ *
+ * EXT-24 forbids two observable states: an available tool WITHOUT its executable
+ * binding, and a new schema served by an old handler. The way to avoid both is to
+ * build the whole surface first, check it for internal consistency, and only then
+ * make it visible — staging plus a single switch, which is what the requirement
+ * asks for rather than an invented transactional registry API.
+ *
+ * The rules encoded here, each with a reason:
+ *
+ * - A tool is advertised only when a real implementation binding exists. A schema
+ *   alone is a promise nothing can keep, and EXT-24 states that no contract is
+ *   automatically callable merely because its schema is installed.
+ * - An ACTIVE package whose model is unprepared publishes readiness information and
+ *   a preparation skill, but NOT a working inference tool. Advertising a callable
+ *   tool that will fail on first use is worse than advertising nothing, because the
+ *   caller has no way to tell the difference until it fails.
+ * - A usage skill appears only when every tool it requires is visible. A skill that
+ *   instructs an agent to call a tool that is not there produces a confident
+ *   failure.
+ * - Every skill carries its owning extension, so it can be withdrawn with that
+ *   package rather than outliving it.
+ *
+ * @module @try-works/dsh-model-as-tool/publication
+ */
+/**
+ * Build a coherent surface from the candidates available now.
+ *
+ * Pure: it decides what MAY be published, and the caller makes the result visible.
+ * Keeping the decision separate from the switch is what allows a surface to be
+ * rejected before anything observes it.
+ * @param options - the candidates and the generation they belong to.
+ * @returns the complete surface, including what was withheld and why.
+ * @throws Error when the candidates are internally inconsistent in a way that
+ *   cannot be resolved by withholding, such as two tools sharing a name.
+ */
+export function buildSurface(options) {
+    const tools = [];
+    const readiness = [];
+    const withheld = [];
+    // A duplicate tool name cannot be resolved by dropping one: the caller asked for
+    // a specific name and would get a different implementation than the catalog says.
+    const seen = new Set();
+    for (const candidate of options.tools) {
+        if (seen.has(candidate.name)) {
+            throw new Error(`two contracts publish the tool name ${JSON.stringify(candidate.name)}; `
+                + 'a name identifies one tool, so this cannot be resolved by withholding');
+        }
+        seen.add(candidate.name);
+    }
+    for (const candidate of options.tools) {
+        const runnable = candidate.implementations.filter(impl => impl.runnable);
+        for (const implementation of candidate.implementations) {
+            readiness.push({
+                extensionId: implementation.extensionId,
+                modelId: implementation.modelId,
+                readiness: implementation.readiness,
+                // Callable requires BOTH that the host can run it and that it is ready.
+                callable: implementation.runnable && implementation.readiness === 'ready',
+                reason: !implementation.runnable
+                    ? 'this model cannot run on this host'
+                    : implementation.readiness === 'ready'
+                        ? 'prepared and callable'
+                        : `model is ${implementation.readiness}; the tool is not advertised as working`,
+            });
+        }
+        const selected = candidate.implementations.find(impl => impl.modelId === candidate.selectedModelId);
+        if (selected === undefined || !selected.runnable) {
+            withheld.push({
+                code: 'no-implementation',
+                subject: candidate.name,
+                extensionId: selected?.extensionId ?? candidate.implementations[0]?.extensionId ?? 'unknown',
+                message: 'no runnable implementation is bound, so the tool is not published',
+            });
+            continue;
+        }
+        if (selected.readiness === 'failed') {
+            withheld.push({
+                code: 'model-failed',
+                subject: candidate.name,
+                extensionId: selected.extensionId,
+                message: 'the selected model deployment has failed and will not become ready by waiting',
+            });
+            continue;
+        }
+        if (selected.readiness !== 'ready') {
+            // EXT-24: an active package with an unprepared model may publish readiness
+            // and preparation guidance, but MUST NOT advertise working inference.
+            withheld.push({
+                code: 'needs-preparation',
+                subject: candidate.name,
+                extensionId: selected.extensionId,
+                message: `the selected model is ${selected.readiness}; readiness is published instead of a callable tool`,
+            });
+            continue;
+        }
+        tools.push({
+            name: candidate.name,
+            contractId: candidate.contractId,
+            extensionId: selected.extensionId,
+            modelId: selected.modelId,
+            readiness: selected.readiness,
+            alternatives: runnable.filter(impl => impl.modelId !== selected.modelId).map(impl => impl.modelId),
+        });
+    }
+    const visible = new Set(tools.map(tool => tool.name));
+    const skills = [];
+    for (const candidate of options.skills) {
+        const purpose = candidate.purpose ?? 'usage';
+        const required = candidate.requiresTools ?? [];
+        if (purpose === 'usage') {
+            const missing = required.filter(name => !visible.has(name));
+            if (missing.length > 0) {
+                // A usage skill whose tool is absent would instruct an agent to call
+                // something that is not there, producing a confident failure.
+                withheld.push({
+                    code: 'unregistered-contribution',
+                    subject: candidate.name,
+                    extensionId: candidate.extensionId,
+                    message: `the required tool(s) ${missing.join(', ')} are not visible, so the usage skill is withheld`,
+                });
+                continue;
+            }
+        }
+        skills.push({ name: candidate.name, extensionId: candidate.extensionId, purpose, requiresTools: required });
+    }
+    return { generation: options.generation, tools, skills, readiness, withheld };
+}
+/**
+ * The published surface, swapped only as a whole (EXT-24).
+ *
+ * `publish` refuses a surface that would retire a tool without retiring the skill
+ * that teaches it, which is the "new schema with the old handler" failure seen from
+ * the other side.
+ */
+export class PublicationSurface {
+    #current;
+    #onSwap;
+    constructor(options = {}) {
+        this.#current = { generation: options.generation ?? 1, tools: [], skills: [], readiness: [], withheld: [] };
+        this.#onSwap = options.onSwap;
+    }
+    /** The generation currently visible. */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Replace the visible surface.
+     *
+     * The callback receives the whole change at once, so a consumer can update its
+     * declarations without ever seeing an intermediate state.
+     * @param next - the surface to make visible.
+     */
+    publish(next) {
+        const previous = this.#current;
+        this.#current = next;
+        this.#onSwap?.(next, previous);
+    }
+    /**
+     * Skills that must be withdrawn because their owning extension is gone.
+     *
+     * EXT-24 requires the host to track skill provenance and remove a skill with the
+     * package or tool that owns it, rather than leaving orphaned guidance behind.
+     * @param liveExtensionIds - the extensions still installed and active.
+     * @returns the skills that should no longer be visible.
+     */
+    orphanedSkills(liveExtensionIds) {
+        const live = new Set(liveExtensionIds);
+        return this.#current.skills.filter(skill => !live.has(skill.extensionId));
+    }
+}
+//# sourceMappingURL=publication.js.map

package/lib/receipt.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Invocation receipts and lifecycle records (EXT-35).
+ *
+ * EXT-35 asks for two different things, recorded SEPARATELY, and the separation is
+ * the point:
+ *
+ * - An **invocation receipt** says what ran: the extension, its version and content
+ *   digest, the model/recipe identity, and the activation generation. It travels
+ *   with the result.
+ * - A **lifecycle record** says who changed the installation: install, activate,
+ *   deactivate, update and uninstall outcomes together with the approving
+ *   principal. It does not travel with a result, because it describes an operator
+ *   action rather than a call.
+ *
+ * Mixing them would mean a caller reading a receipt learns about operator actions
+ * it has no business seeing, and an audit trail becomes indistinguishable from
+ * execution metadata.
+ *
+ * The metadata-only rule is enforced by CONSTRUCTION rather than by remembering to
+ * be careful. Nothing here accepts a request body, a token, or a full skill text,
+ * and a path is reduced before it can enter a receipt at all — so a future caller
+ * cannot leak one by passing it in.
+ *
+ * @module @try-works/dsh-model-as-tool/receipt
+ */
+import type { ExecutionLocation } from '@try-works/tool-mode-contracts';
+/** Provenance attached to one invocation. All fields are host-authored. */
+export interface InvocationReceipt {
+    /** Opaque receipt identity, unique per call. */
+    readonly receiptId: string;
+    /** The contract that was invoked. */
+    readonly contract: string;
+    /** The contract version, so a receipt is interpretable after a schema change. */
+    readonly contractVersion: string;
+    /** The implementation selected by the host. */
+    readonly implementationId: string;
+    /** The extension package that provided it. */
+    readonly extension: string;
+    /** The extension package version. */
+    readonly extensionVersion: string;
+    /**
+     * The installed content digest of the extension.
+     *
+     * Recorded because a version alone does not identify bytes: a package can be
+     * replaced at the same version, and a receipt that only names the version could
+     * not distinguish the two runs.
+     */
+    readonly extensionContentDigest: string | null;
+    /** The resolved dependency-lock digest, when the store recorded one. */
+    readonly dependencyLockDigest: string | null;
+    /** The model or recipe identity that actually ran. */
+    readonly modelIdentity: string;
+    /** The recipe version, which pins preprocessing and postprocessing. */
+    readonly recipeVersion: string | null;
+    /** The catalog generation this invocation was served from. */
+    readonly activationGeneration: number;
+    /**
+     * Where inference happened.
+     *
+     * The shared vocabulary from the contracts package, reused rather than restated:
+     * a second definition would drift, and a receipt whose location field disagreed
+     * with its own envelope's would be worse than one without the field.
+     */
+    readonly executionLocation: ExecutionLocation;
+    /** Non-fatal notes, already free of caller content. */
+    readonly warnings: readonly string[];
+}
+/** The lifecycle operations EXT-35 requires recorded. */
+export type LifecycleOperation = 'install' | 'activate' | 'deactivate' | 'update' | 'uninstall' | 'prepare';
+/** The outcome of a lifecycle operation. */
+export type LifecycleOutcome = 'succeeded' | 'failed' | 'refused' | 'rolled-back';
+/** Who approved an operator action. */
+export type ApprovingPrincipal = 
+/** The interactive operator at the console. */
+{
+    readonly kind: 'operator';
+    readonly identity: string;
+}
+/** A management grant presented by an external client. */
+ | {
+    readonly kind: 'client-grant';
+    readonly grantId: string;
+}
+/** An automated policy, named so it can be audited. */
+ | {
+    readonly kind: 'policy';
+    readonly policyId: string;
+};
+/** One operator action, recorded apart from execution metadata. */
+export interface LifecycleRecord {
+    /** What was attempted. */
+    readonly operation: LifecycleOperation;
+    /** The extension it concerned. */
+    readonly extensionId: string;
+    /** The version, when the operation concerned one. */
+    readonly version: string | null;
+    /** The content digest, when known. */
+    readonly contentDigest: string | null;
+    /** The profile, for the profile-scoped operations. */
+    readonly profile: string | null;
+    /** What happened. */
+    readonly outcome: LifecycleOutcome;
+    /** Why it did not succeed, when it did not. */
+    readonly reason: string | null;
+    /** Who approved it. Never inferred from the request. */
+    readonly approvedBy: ApprovingPrincipal;
+    /** When it happened, ISO 8601. */
+    readonly at: string;
+}
+/** Raised when a value cannot be admitted to a receipt. */
+export declare class ReceiptRedactionError extends Error {
+    readonly name = "ReceiptRedactionError";
+}
+/**
+ * Reduce a caller-supplied path to something safe to record.
+ *
+ * EXT-35 forbids unrestricted file paths in default receipts, and the reason is
+ * that a path discloses the operator's layout: directory names, a username, a
+ * project name. The basename is enough to correlate a receipt with a call, and a
+ * short digest makes two references to the same path comparable without revealing
+ * where it is.
+ * @param path - the caller-supplied path.
+ * @returns the basename plus a short digest, or null.
+ */
+export declare function redactPath(path: string | undefined): string | null;
+/**
+ * Redact anything token-shaped from a free-text note.
+ *
+ * Notes are authored by the host, but a note that embedded a value read from the
+ * environment would leak it. This is a guard against that, not a substitute for
+ * not putting secrets in notes.
+ * @param text - the note.
+ * @returns the note with credential-shaped spans removed.
+ */
+export declare function redactText(text: string): string;
+/**
+ * Build the invocation receipt for one call.
+ *
+ * Takes only host-resolved inputs. There is no parameter for a request body, a
+ * token or a skill text, so those cannot reach a receipt through this function at
+ * all — which is a stronger guarantee than remembering to omit them.
+ * @param input - the resolved provenance.
+ * @returns the receipt.
+ */
+export declare function buildInvocationReceipt(input: {
+    readonly receiptId: string;
+    readonly contract: string;
+    readonly contractVersion: string;
+    readonly implementationId: string;
+    readonly extension: string;
+    readonly extensionVersion: string;
+    readonly extensionContentDigest?: string | null;
+    readonly dependencyLockDigest?: string | null;
+    readonly modelIdentity: string;
+    readonly recipeVersion?: string | null;
+    readonly activationGeneration: number;
+    readonly executionLocation: InvocationReceipt['executionLocation'];
+    readonly warnings?: readonly string[];
+}): InvocationReceipt;
+/**
+ * Record one operator action, separately from execution metadata.
+ * @param input - the action, its outcome and its approving principal.
+ * @returns the lifecycle record.
+ */
+export declare function buildLifecycleRecord(input: {
+    readonly operation: LifecycleOperation;
+    readonly extensionId: string;
+    readonly version?: string | null;
+    readonly contentDigest?: string | null;
+    readonly profile?: string | null;
+    readonly outcome: LifecycleOutcome;
+    readonly reason?: string | null;
+    readonly approvedBy: ApprovingPrincipal;
+    readonly at?: string;
+}): LifecycleRecord;
+/**
+ * The bounded-logging policy an extension's diagnostics run under (EXT-35).
+ *
+ * Extension logging is bounded and host-policy controlled, and extension-declared
+ * telemetry or network behaviour must be disclosed rather than assumed. This
+ * applies the policy; it does not infer one.
+ */
+export interface ExtensionLogPolicy {
+    /** Maximum records retained per extension. */
+    readonly maxRecords: number;
+    /** Levels admitted. A disabled level is dropped, not rewritten. */
+    readonly levels: readonly ('debug' | 'info' | 'warn' | 'error')[];
+    /** Whether the extension declared telemetry, which the operator must approve. */
+    readonly telemetryApproved: boolean;
+    /** Origins the extension declared, which must all be approved. */
+    readonly approvedOrigins: readonly string[];
+}
+/** The default policy: quiet, metadata-only, and telemetry off unless approved. */
+export declare const DEFAULT_LOG_POLICY: ExtensionLogPolicy;
+/**
+ * Apply a logging policy to one extension record.
+ *
+ * A dropped record is dropped rather than summarised, because a summarised
+ * diagnostic is a diagnostic an operator will misread.
+ * @param policy - the policy in force.
+ * @param record - the proposed record.
+ * @returns whether to retain it.
+ */
+export declare function admitsLogRecord(policy: ExtensionLogPolicy, record: {
+    readonly level: 'debug' | 'info' | 'warn' | 'error';
+    readonly declaredOrigin?: string;
+}): boolean;
+//# sourceMappingURL=receipt.d.ts.map

package/lib/receipt.d.ts.map

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

package/lib/receipt.js

@@ -0,0 +1,150 @@
+/**
+ * Invocation receipts and lifecycle records (EXT-35).
+ *
+ * EXT-35 asks for two different things, recorded SEPARATELY, and the separation is
+ * the point:
+ *
+ * - An **invocation receipt** says what ran: the extension, its version and content
+ *   digest, the model/recipe identity, and the activation generation. It travels
+ *   with the result.
+ * - A **lifecycle record** says who changed the installation: install, activate,
+ *   deactivate, update and uninstall outcomes together with the approving
+ *   principal. It does not travel with a result, because it describes an operator
+ *   action rather than a call.
+ *
+ * Mixing them would mean a caller reading a receipt learns about operator actions
+ * it has no business seeing, and an audit trail becomes indistinguishable from
+ * execution metadata.
+ *
+ * The metadata-only rule is enforced by CONSTRUCTION rather than by remembering to
+ * be careful. Nothing here accepts a request body, a token, or a full skill text,
+ * and a path is reduced before it can enter a receipt at all — so a future caller
+ * cannot leak one by passing it in.
+ *
+ * @module @try-works/dsh-model-as-tool/receipt
+ */
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
+/** Raised when a value cannot be admitted to a receipt. */
+export class ReceiptRedactionError extends Error {
+    name = 'ReceiptRedactionError';
+}
+/**
+ * Reduce a caller-supplied path to something safe to record.
+ *
+ * EXT-35 forbids unrestricted file paths in default receipts, and the reason is
+ * that a path discloses the operator's layout: directory names, a username, a
+ * project name. The basename is enough to correlate a receipt with a call, and a
+ * short digest makes two references to the same path comparable without revealing
+ * where it is.
+ * @param path - the caller-supplied path.
+ * @returns the basename plus a short digest, or null.
+ */
+export function redactPath(path) {
+    if (typeof path !== 'string' || path.length === 0)
+        return null;
+    const digest = createHash('sha256').update(path).digest('hex').slice(0, 8);
+    // `basename` on either separator: a receipt must not leak a Windows path shape
+    // merely because the host runs on Windows.
+    const leaf = basename(path.replace(/\\/g, '/'));
+    return `${leaf}#${digest}`;
+}
+/**
+ * Redact anything token-shaped from a free-text note.
+ *
+ * Notes are authored by the host, but a note that embedded a value read from the
+ * environment would leak it. This is a guard against that, not a substitute for
+ * not putting secrets in notes.
+ * @param text - the note.
+ * @returns the note with credential-shaped spans removed.
+ */
+export function redactText(text) {
+    return text
+        .replace(/\b(?:npm_|ghp_|gho_|ghs_|sk-|xox[baprs]-)[A-Za-z0-9_-]{8,}/g, '<redacted>')
+        .replace(/\bBearer\s+[A-Za-z0-9._-]{8,}/gi, 'Bearer <redacted>')
+        .replace(/\b[A-Fa-f0-9]{40,}\b/g, '<redacted>')
+        .replace(/[A-Za-z]:\\[^\s"']*/g, '<path>')
+        .replace(/(?<![\w.])\/(?:[\w.-]+\/)+[\w.-]+/g, '<path>');
+}
+/**
+ * Build the invocation receipt for one call.
+ *
+ * Takes only host-resolved inputs. There is no parameter for a request body, a
+ * token or a skill text, so those cannot reach a receipt through this function at
+ * all — which is a stronger guarantee than remembering to omit them.
+ * @param input - the resolved provenance.
+ * @returns the receipt.
+ */
+export function buildInvocationReceipt(input) {
+    if (input.receiptId.length === 0) {
+        throw new ReceiptRedactionError('a receipt needs an identity; an unidentifiable receipt is not an audit trail');
+    }
+    return {
+        receiptId: input.receiptId,
+        contract: input.contract,
+        contractVersion: input.contractVersion,
+        implementationId: input.implementationId,
+        extension: input.extension,
+        extensionVersion: input.extensionVersion,
+        extensionContentDigest: input.extensionContentDigest ?? null,
+        dependencyLockDigest: input.dependencyLockDigest ?? null,
+        modelIdentity: input.modelIdentity,
+        recipeVersion: input.recipeVersion ?? null,
+        activationGeneration: input.activationGeneration,
+        executionLocation: input.executionLocation,
+        // Every note passes through the redactor, so a host-authored note that happened
+        // to embed a token or a path cannot leak one.
+        warnings: (input.warnings ?? []).map(redactText),
+    };
+}
+/**
+ * Record one operator action, separately from execution metadata.
+ * @param input - the action, its outcome and its approving principal.
+ * @returns the lifecycle record.
+ */
+export function buildLifecycleRecord(input) {
+    if (input.approvedBy.kind === 'operator' && input.approvedBy.identity.length === 0) {
+        // An approval with no principal cannot be audited, which defeats the record.
+        throw new ReceiptRedactionError('an operator approval needs an identity');
+    }
+    return {
+        operation: input.operation,
+        extensionId: input.extensionId,
+        version: input.version ?? null,
+        contentDigest: input.contentDigest ?? null,
+        profile: input.profile ?? null,
+        outcome: input.outcome,
+        // A failed operation with no reason is the record an operator cannot act on.
+        reason: input.reason === undefined || input.reason === null ? null : redactText(input.reason),
+        approvedBy: input.approvedBy,
+        at: input.at ?? new Date().toISOString(),
+    };
+}
+/** The default policy: quiet, metadata-only, and telemetry off unless approved. */
+export const DEFAULT_LOG_POLICY = {
+    maxRecords: 500,
+    levels: ['warn', 'error'],
+    telemetryApproved: false,
+    approvedOrigins: [],
+};
+/**
+ * Apply a logging policy to one extension record.
+ *
+ * A dropped record is dropped rather than summarised, because a summarised
+ * diagnostic is a diagnostic an operator will misread.
+ * @param policy - the policy in force.
+ * @param record - the proposed record.
+ * @returns whether to retain it.
+ */
+export function admitsLogRecord(policy, record) {
+    if (!policy.levels.includes(record.level))
+        return false;
+    if (record.declaredOrigin !== undefined) {
+        // An undeclared network origin is refused rather than recorded and forgotten:
+        // EXT-35 requires the behaviour to be disclosed and approved, not logged.
+        if (!policy.approvedOrigins.includes(record.declaredOrigin))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=receipt.js.map

package/lib/registrar.d.ts

@@ -40,6 +40,19 @@ export declare function buildParameters(entry: ModelCatalogEntry): ParameterSche
  * @param value - the canonical value the adapter returned.
  * @returns the model-facing content blocks.
  */
+/**
+ * Render a canonical value as model-facing content blocks.
+ *
+ * Keyed on the CONTRACT, never on the model id. A model-specific presentation
+ * branch is a model-specific postprocessing recipe living in the host, which
+ * EXT-01 forbids — and it would also mean a second implementation of the same
+ * contract rendered differently, contradicting the point of having a contract.
+ * Anything unrecognised falls through to the canonical JSON, so a new contract
+ * degrades to readable data rather than to nothing.
+ * @param entry - the catalog entry, for its contract binding.
+ * @param value - the canonical value the adapter returned.
+ * @returns the model-facing content blocks.
+ */
 export declare function renderResult(entry: ModelCatalogEntry, value: Record<string, unknown>): {
     type: 'text';
     text: string;

package/lib/registrar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../src/registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA0C,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACzG,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAY7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CA0BlC;AAcD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE;IAAE,KAAK,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;KAAE,CAAA;CAAE,EAC7D,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,YAAY,GACpB,mBAAmB,CA6BrB"}
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../src/registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA0C,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACzG,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAY7E;AAED;;;;;;;;;;GAUG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CA8BlC;AAcD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE;IAAE,KAAK,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;KAAE,CAAA;CAAE,EAC7D,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,YAAY,GACpB,mBAAmB,CA6BrB"}

package/lib/registrar.js

@@ -62,22 +62,39 @@ export function buildParameters(entry) {
  * @param value - the canonical value the adapter returned.
  * @returns the model-facing content blocks.
  */
+/**
+ * Render a canonical value as model-facing content blocks.
+ *
+ * Keyed on the CONTRACT, never on the model id. A model-specific presentation
+ * branch is a model-specific postprocessing recipe living in the host, which
+ * EXT-01 forbids — and it would also mean a second implementation of the same
+ * contract rendered differently, contradicting the point of having a contract.
+ * Anything unrecognised falls through to the canonical JSON, so a new contract
+ * degrades to readable data rather than to nothing.
+ * @param entry - the catalog entry, for its contract binding.
+ * @param value - the canonical value the adapter returned.
+ * @returns the model-facing content blocks.
+ */
 export function renderResult(entry, value) {
-    if (entry.id === 'tongue' && typeof value.language === 'string') {
+    if (entry.contract === 'text.language_detect' && typeof value.language === 'string') {
         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.isTooCloseToCall === true ? ' (too close to call)' : '';
+        // Both spellings are accepted: an implementation reports its own vocabulary and
+        // the host translates, so this reads whichever one reached here.
+        const tooClose = value.tooCloseToCall === true || value.isTooCloseToCall === true
+            ? ' (too close to call)'
+            : '';
         return [{
                 type: 'text',
                 text: `Detected language: ${value.language}${tooClose}`
                     + (detail.length > 0 ? `\nCandidates: ${detail}` : ''),
             }];
     }
-    if (entry.id === 'voz' && typeof value.text === 'string') {
+    if (entry.contract === 'stt.transcribe' && typeof value.text === 'string') {
         const wordCount = typeof value.wordCount === 'number' ? value.wordCount : 0;
         return [{
                 type: 'text',