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

package/lib/server-lifecycle.js

@@ -0,0 +1,269 @@
+/**
+ * Server and plugin lifecycle (RUN-01, RUN-02, RUN-05, RUN-06, RUN-07).
+ *
+ * Almost every rule here is about what must NOT happen:
+ *
+ * - **Do not announce readiness before it is true** (RUN-06). A listener that reports
+ *   ready before its bind or its initialisation succeeded sends a client to a port
+ *   that is not answering. Readiness is therefore a STATE derived from both, not a flag
+ *   set by whoever got there first.
+ * - **Do not resolve a port conflict by force or by stealth** (RUN-06). Taking the port
+ *   from another process, or silently moving to a different one, both break a client
+ *   that was told where to connect. The conflict is reported.
+ * - **Do not let a failed start take the host with it** (RUN-06). The MCP endpoint is
+ *   one feature of a much larger host; a port clash must leave the rest running.
+ * - **Do not kill work you do not own** (RUN-07). A model process serving another
+ *   still-authorized owner is not this lifecycle's to terminate.
+ * - **Do not prepare anything at startup** (RUN-05). Nothing downloads because a plugin
+ *   loaded or a client listed tools.
+ *
+ * @module @try-works/dsh-model-as-tool/server-lifecycle
+ */
+/** The documented grace period for cleanup (RUN-07). */
+export const DEFAULT_GRACE_MS = 5000;
+/**
+ * Manages one MCP listener's lifecycle.
+ *
+ * Deliberately separate from the DSH plugin's own lifecycle: RUN-01 requires disabling
+ * the SERVER to stop its listener and owned work without disabling unrelated DSH tools,
+ * so the two must be independently stoppable.
+ */
+export class ServerLifecycle {
+    #state = 'stopped';
+    #port = null;
+    #closeListener = null;
+    #work = new Map();
+    #host;
+    #graceMs;
+    /** Set once shutdown begins, so new work is refused from that moment. */
+    #acceptingWork = true;
+    constructor(host, options = {}) {
+        this.#host = host;
+        this.#graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
+    }
+    /** The current state. */
+    get state() {
+        return this.#state;
+    }
+    /** The bound port, once one exists. */
+    get port() {
+        return this.#port;
+    }
+    /**
+     * Whether the endpoint is serving (RUN-06).
+     *
+     * True only after BOTH bind and initialise succeeded. A caller asking "can I connect"
+     * gets one answer, and it is not derived from a flag somebody set early.
+     */
+    get ready() {
+        return this.#state === 'ready';
+    }
+    /** Work currently owned, for diagnostics. */
+    get owned() {
+        return [...this.#work.values()];
+    }
+    /**
+     * Start the listener.
+     *
+     * @returns nothing on success, or the failure — never a thrown exception, because
+     *   RUN-06 requires a failed start not to crash the unrelated host.
+     */
+    async start() {
+        if (this.#state === 'ready' || this.#state === 'starting') {
+            return {
+                ok: false,
+                failure: {
+                    code: 'ALREADY_STARTED',
+                    message: `the server is already ${this.#state}`,
+                    remedy: 'Call stop() before starting again.',
+                },
+            };
+        }
+        this.#state = 'starting';
+        try {
+            const listener = await this.#host.bind();
+            this.#port = listener.port;
+            this.#closeListener = listener.close;
+        }
+        catch (error) {
+            const code = error.code;
+            this.#state = 'failed';
+            if (code === 'EADDRINUSE') {
+                // Reported, NOT resolved. Taking the port from another process or silently
+                // moving to a different one both break a client told where to connect.
+                return {
+                    ok: false,
+                    failure: {
+                        code: 'PORT_IN_USE',
+                        message: `port ${String(error.message)} is already in use`,
+                        remedy: 'Choose a different port in the configuration, or stop the process holding it. This server will not take it by force or move silently.',
+                    },
+                };
+            }
+            return {
+                ok: false,
+                failure: {
+                    code: 'BIND_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                    remedy: 'Check that the bind address is a loopback address and that the port is permitted.',
+                },
+            };
+        }
+        try {
+            await this.#host.initialise();
+        }
+        catch (error) {
+            this.#state = 'failed';
+            // The listener bound but cannot serve, so it is CLOSED rather than left open:
+            // an open port that answers nothing is worse than no port.
+            await this.#closeListener?.().catch(() => undefined);
+            this.#closeListener = null;
+            this.#port = null;
+            return {
+                ok: false,
+                failure: {
+                    code: 'INIT_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                    remedy: 'Check the server diagnostics; the host itself is unaffected.',
+                },
+            };
+        }
+        // Only now. Readiness after BOTH succeed, and never before.
+        this.#state = 'ready';
+        this.#host.onReady(this.#port);
+        return { ok: true, port: this.#port };
+    }
+    /**
+     * Register work this lifecycle owns (RUN-07).
+     *
+     * Refused once shutdown has begun, so a call racing a stop cannot slip into the
+     * cleanup window and be left running.
+     * @param work - the work to own.
+     * @returns whether it was accepted.
+     */
+    adopt(work) {
+        if (!this.#acceptingWork)
+            return false;
+        this.#work.set(work.id, work);
+        return true;
+    }
+    /** Release work that finished on its own. */
+    release(id) {
+        this.#work.delete(id);
+    }
+    /**
+     * Stop the listener and everything it owns (RUN-07).
+     *
+     * The order is the requirement's: refuse new work, cancel owned foreground
+     * invocations, wait within the grace period, terminate what remains, close the
+     * transport and release the port. Work belonging to another owner is LEFT ALONE.
+     * @param options - `ownedBy` selects the owner whose work may be stopped.
+     * @returns the report.
+     */
+    async stop(options = {}) {
+        // 1. Refuse new work FIRST, so nothing is adopted during cleanup.
+        this.#acceptingWork = false;
+        if (this.#state === 'stopped') {
+            return { cancelled: [], terminated: [], untouched: [], portReleased: true, withinGrace: true };
+        }
+        this.#state = 'stopping';
+        const mine = [];
+        const untouched = [];
+        for (const work of this.#work.values()) {
+            // RUN-07: never kill a model process serving another still-authorized owner.
+            if (options.ownedBy !== undefined && work.owner !== options.ownedBy) {
+                untouched.push(work.id);
+                continue;
+            }
+            mine.push(work);
+        }
+        // 2. Cancel owned foreground invocations, and wait for them WITHIN the grace
+        // period. Racing each cancel against one shared deadline is what makes the grace
+        // period mean something: a cancel that never resolves must not hold shutdown open
+        // forever, and it must not be reported as stopped either.
+        const deadline = Date.now() + this.#graceMs;
+        const cancelled = [];
+        const terminated = [];
+        const outcomes = await Promise.all(mine.map(async (work) => {
+            const remaining = Math.max(0, deadline - Date.now());
+            const settled = await Promise.race([
+                Promise.resolve(work.cancel()).then(() => true).catch(() => false),
+                new Promise(resolve => setTimeout(() => resolve(false), remaining)),
+            ]);
+            return { work, settled };
+        }));
+        for (const { work, settled } of outcomes) {
+            if (settled)
+                cancelled.push(work.id);
+        }
+        const withinGrace = outcomes.every(outcome => outcome.settled);
+        // 3. Terminate whatever outlived the grace period.
+        for (const { work, settled } of outcomes) {
+            if (settled)
+                continue;
+            try {
+                work.terminate?.();
+                terminated.push(work.id);
+            }
+            catch {
+                // A terminate that throws is logged rather than fatal: shutdown must complete
+                // even when one piece of work refuses to die.
+                this.#host.log(`work ${work.id} could not be terminated`);
+            }
+        }
+        this.#work.clear();
+        // 4. Close the transport and release the port.
+        let portReleased = false;
+        try {
+            await this.#closeListener?.();
+            portReleased = true;
+        }
+        catch {
+            this.#host.log('the listener could not be closed cleanly');
+        }
+        this.#closeListener = null;
+        this.#port = null;
+        this.#state = 'stopped';
+        this.#acceptingWork = true;
+        return { cancelled, terminated, untouched, portReleased, withinGrace };
+    }
+}
+/** The only startup policy this implementation permits (RUN-05). */
+export const READ_ONLY_STARTUP = {
+    preparesModels: false,
+    resolvesPackages: false,
+    discoveryIsReadOnly: true,
+};
+/**
+ * Whether a startup action is permitted (RUN-05).
+ *
+ * @param action - what the startup wants to do.
+ * @returns whether it may.
+ */
+export function startupPermits(action) {
+    switch (action) {
+        // Restoring an explicitly approved activation and inspecting local state are the
+        // two things startup MAY do.
+        case 'restore-active':
+        case 'inspect-assets':
+        case 'read-manifests':
+            return true;
+        // Preparation and resolution are refused, because RUN-05 is explicit that nothing
+        // downloads because a plugin loaded or a client listed tools.
+        case 'prepare-model':
+        case 'resolve-package':
+        case 'download-weights':
+            return false;
+    }
+}
+/**
+ * Whether disabling the MCP server must also disable unrelated DSH tools (RUN-01).
+ *
+ * It must not. The server and the plugin are independently stoppable, which is why the
+ * lifecycle is a separate object from the plugin's own registration state.
+ * @returns always false.
+ */
+export function disablingServerDisablesOtherTools() {
+    return false;
+}
+//# sourceMappingURL=server-lifecycle.js.map

package/lib/types.d.ts

@@ -65,6 +65,27 @@ export interface ModelCatalogEntry {
     readonly name: string;
     readonly summary: string;
     readonly capability: string;
+    /**
+     * The standard contract this model implements, or null when none exists yet.
+     *
+     * This is what makes tool identity independent of model identity (BASE-02): the
+     * contract decides the tool name a caller sees, so a second model implementing
+     * the same contract joins the existing tool instead of creating a duplicate. A
+     * model with no contract keeps a per-model tool under its own name.
+     */
+    readonly contract: string | null;
+    /**
+     * The extension package that implements this model (BASE-09).
+     *
+     * A binding held as DATA, not a switch on the model name. The host loads
+     * whatever package this names through the PUBLIC extension API, so a first-party
+     * package takes the same route as a third-party one and adding a vendor means
+     * publishing a package plus adding this field — with no host change.
+     */
+    readonly provider?: {
+        readonly extension: string;
+        readonly modelId: string;
+    };
     readonly input: ModelInput;
     readonly output: string;
     readonly languages: number | null;

package/lib/types.d.ts.map

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

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/lang-detect.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `text.language_detect` — the language-identification contract (TOOL-03).
+ *
+ * TOOL-03 requires three things a naive wrapper loses: ambiguity must survive to
+ * the caller, empty input has a defined answer rather than an exception, and the
+ * score's MEANING is declared. It also forbids a specific mistake worth naming in
+ * the schema: a text language detector is not evidence about the language spoken
+ * in audio it never processed, so the contract says so instead of leaving a
+ * caller to infer capability from a similar-looking tool.
+ *
+ * @module @try-works/tool-mode-contracts/contracts/lang-detect
+ */
+import type { ToolContract } from '../registry.ts';
+/** The `text.language_detect` contract at version 1.0.0. */
+export declare const langDetect: ToolContract;
+//# sourceMappingURL=lang-detect.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/lang-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lang-detect.d.ts","sourceRoot":"","sources":["../../src/contracts/lang-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,4DAA4D;AAC5D,eAAO,MAAM,UAAU,EAAE,YA8ExB,CAAA"}

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/lang-detect.js

@@ -0,0 +1,85 @@
+/**
+ * `text.language_detect` — the language-identification contract (TOOL-03).
+ *
+ * TOOL-03 requires three things a naive wrapper loses: ambiguity must survive to
+ * the caller, empty input has a defined answer rather than an exception, and the
+ * score's MEANING is declared. It also forbids a specific mistake worth naming in
+ * the schema: a text language detector is not evidence about the language spoken
+ * in audio it never processed, so the contract says so instead of leaving a
+ * caller to infer capability from a similar-looking tool.
+ *
+ * @module @try-works/tool-mode-contracts/contracts/lang-detect
+ */
+import { withMeta } from "../meta.js";
+/** The `text.language_detect` contract at version 1.0.0. */
+export const langDetect = {
+    contract: 'text.language_detect',
+    version: '1.0.0',
+    toolName: 'lang_detect',
+    description: 'Identify the language of a short piece of text. Returns the best language, a reliability '
+        + 'verdict and ranked alternatives, because short text is often genuinely ambiguous between '
+        + 'related languages and collapsing that to one answer would overstate the result.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['text'],
+        properties: {
+            text: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 4096,
+                description: 'The text to identify. Only the leading portion is examined.',
+            },
+            top: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 20,
+                default: 3,
+                description: 'How many ranked alternatives to return.',
+            },
+        },
+    },
+    outputSchema: withMeta({
+        language: { type: ['string', 'null'], description: 'Best candidate, or null when input had no language signal.' },
+        reliability: {
+            type: 'string',
+            enum: ['confident', 'likely', 'tentative', 'unknown'],
+            description: 'Vendor-reported verdict. Not a calibrated probability.',
+        },
+        tooCloseToCall: {
+            type: 'boolean',
+            description: 'True when the leading candidates are within the implementation\'s declared tie margin.',
+        },
+        candidates: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['language', 'probability'],
+                properties: {
+                    language: { type: 'string' },
+                    probability: { type: 'number', minimum: 0, maximum: 1 },
+                },
+            },
+        },
+    }, ['reliability', 'tooCloseToCall', 'candidates']),
+    semantics: {
+        scoreKind: 'vendor-reported-probability',
+        calibrated: false,
+        ambiguityPreserved: true,
+        emptyInputMeaning: 'null-language-with-empty-candidates',
+        appliesTo: 'written-text-only',
+    },
+    limits: {
+        maxInputCharacters: 4096,
+        examinedCharacters: 512,
+        maxCandidates: 20,
+    },
+    unsupported: [
+        'Spoken language: this reads written text only. It is not evidence about the language spoken in audio it has not processed (TOOL-03).',
+        'Translation or transliteration.',
+        'Confident single answers for one or two words: those are frequently ambiguous and are reported as such.',
+        'Documents beyond the examined prefix: only the leading characters are considered.',
+    ],
+};
+//# sourceMappingURL=lang-detect.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/stt-transcribe.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `stt.transcribe` — the canonical transcription contract (TOOL-01).
+ *
+ * This contract is model-free on purpose. Any conforming implementation binds to
+ * it, so a caller addresses `stt_transcribe` once and the host decides which
+ * model runs (BASE-02). Adding a second transcription model must not add a
+ * second tool.
+ *
+ * The semantics block is the part a schema cannot express and the part the spec
+ * insists on (DECL-01, TOOL-01): whether this transcribes or translates, what
+ * the timestamps mean, and what an empty result means.
+ *
+ * @module @try-works/tool-mode-contracts/contracts/stt-transcribe
+ */
+import type { ToolContract } from '../registry.ts';
+/** Accepted audio container/codec combinations for the bounded decoder. */
+export declare const STT_ADMITTED_FORMATS: readonly ["wav-pcm16"];
+/** The `stt.transcribe` contract at version 1.0.0. */
+export declare const sttTranscribe: ToolContract;
+//# sourceMappingURL=stt-transcribe.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/stt-transcribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stt-transcribe.d.ts","sourceRoot":"","sources":["../../src/contracts/stt-transcribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,wBAAyB,CAAA;AAE1D,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,YAqG3B,CAAA"}

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/stt-transcribe.js

@@ -0,0 +1,112 @@
+/**
+ * `stt.transcribe` — the canonical transcription contract (TOOL-01).
+ *
+ * This contract is model-free on purpose. Any conforming implementation binds to
+ * it, so a caller addresses `stt_transcribe` once and the host decides which
+ * model runs (BASE-02). Adding a second transcription model must not add a
+ * second tool.
+ *
+ * The semantics block is the part a schema cannot express and the part the spec
+ * insists on (DECL-01, TOOL-01): whether this transcribes or translates, what
+ * the timestamps mean, and what an empty result means.
+ *
+ * @module @try-works/tool-mode-contracts/contracts/stt-transcribe
+ */
+import { withMeta } from "../meta.js";
+/** Accepted audio container/codec combinations for the bounded decoder. */
+export const STT_ADMITTED_FORMATS = ['wav-pcm16'];
+/** The `stt.transcribe` contract at version 1.0.0. */
+export const sttTranscribe = {
+    contract: 'stt.transcribe',
+    version: '1.0.0',
+    toolName: 'stt_transcribe',
+    description: 'Transcribe a local audio recording into text with optional word timestamps. '
+        + 'Runs on device by default; the caller selects no model. Accepts 16 kHz mono PCM16 WAV '
+        + 'directly, and other encodings only through a tested decoder. Reports partial coverage '
+        + 'rather than presenting an incomplete clip as fully transcribed.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['audio'],
+        properties: {
+            audio: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string', minLength: 1, description: 'Absolute path to the recording.' },
+                    sampleRateHz: {
+                        type: 'integer',
+                        minimum: 8000,
+                        maximum: 48000,
+                        description: 'Declared sample rate; inspected against the file header, not trusted.',
+                    },
+                    channels: { type: 'integer', minimum: 1, maximum: 2 },
+                },
+            },
+            language: {
+                type: 'string',
+                minLength: 2,
+                description: 'Requested language as a BCP-47/ISO 639 code. An unsupported request is an error, never a silent fallback.',
+            },
+            timestamps: {
+                type: 'string',
+                enum: ['none', 'word'],
+                default: 'none',
+                description: 'Word timestamps when requested; an implementation that cannot supply them must error rather than omit them.',
+            },
+        },
+    },
+    outputSchema: withMeta({
+        text: { type: 'string' },
+        coverage: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['complete', 'transcribedSeconds'],
+            properties: {
+                complete: { type: 'boolean' },
+                transcribedSeconds: { type: 'number', minimum: 0 },
+                totalSeconds: { type: ['number', 'null'], minimum: 0 },
+                reason: { type: ['string', 'null'] },
+            },
+        },
+        words: {
+            type: ['array', 'null'],
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['text', 'start', 'end'],
+                properties: {
+                    text: { type: 'string' },
+                    start: { type: 'number', minimum: 0, description: 'Seconds from the start of the audio.' },
+                    end: { type: 'number', minimum: 0 },
+                },
+            },
+        },
+        language: { type: ['string', 'null'], description: 'The language actually recognized, when the implementation reports it.' },
+    }, ['text', 'coverage']),
+    semantics: {
+        operation: 'transcription',
+        translation: false,
+        timestampUnit: 'seconds',
+        timestampReference: 'start-of-audio',
+        emptyResultMeaning: 'valid-empty-transcript',
+        partialResultMeaning: 'coverage.complete is false; the transcript is incomplete, not wrong',
+        languageMismatch: 'error',
+        unsupportedTimestampRequest: 'error',
+    },
+    limits: {
+        maxAudioSeconds: 3600,
+        maxAudioBytes: 512 * 1024 * 1024,
+        admittedSampleRateHz: 16000,
+        admittedChannels: 1,
+    },
+    unsupported: [
+        'Encoding without a tested decoder: only wav-pcm16 is admitted directly; assume nothing from the file extension.',
+        'Translation: this contract transcribes, it does not translate.',
+        'Diarization or speaker attribution: separate capability.',
+        'Timestamps when the selected implementation cannot produce them: reported as an error.',
+        'Live/streaming audio: the input is a completed local file.',
+    ],
+};
+//# sourceMappingURL=stt-transcribe.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/dsh.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Projection of a contract into DSH's parameter DSL (DECL-01).
+ *
+ * DECL-01 requires that DSH registration, MCP projection and Code Mode types all
+ * come from one source. The contract's JSON Schema is that source; this module is
+ * the DSH-specific projection of it.
+ *
+ * It replaces the old registrar behaviour that inferred the required input from
+ * parameter ORDER (BASE-04). Requiredness now comes from the schema's `required`
+ * array, so a contract cannot silently change meaning when a property is
+ * reordered.
+ *
+ * @module @try-works/tool-mode-contracts/dsh
+ */
+import type { ToolContract } from './registry.ts';
+/** One DSH parameter property: a JSON-Schema subset plus `required`. */
+type DshProperty = Record<string, unknown> & {
+    required?: true;
+};
+/** The implicit-open-object parameter map DSH expects. */
+export type DshParameters = Record<string, DshProperty>;
+/** The result of projecting a contract into DSH's narrower DSL. */
+export interface DshProjection {
+    /** What the model-facing parameter schema advertises. */
+    readonly parameters: DshParameters;
+    /**
+     * Contract keywords the parameter schema cannot advertise, in `path.keyword`
+     * form. They remain enforced at runtime against the full contract schema.
+     */
+    readonly runtimeEnforced: readonly string[];
+}
+/** Raised when a contract uses a schema shape the DSH DSL cannot express. */
+export declare class ProjectionError extends Error {
+    readonly name = "ProjectionError";
+    readonly unsupported: readonly string[];
+    constructor(contract: string, unsupported: readonly string[]);
+}
+/**
+ * Project a contract's input schema into DSH parameters.
+ *
+ * DSH's DSL is narrower than JSON Schema — it has no `minLength`, `minimum` or
+ * `pattern` at any nesting level — so the projection is deliberately lossy in what
+ * it ADVERTISES while remaining complete in what it ENFORCES. BASE-04 forbids
+ * silently discarding a constraint, so every keyword left out is returned in
+ * {@link DshProjection.runtimeEnforced} and is checked by `assertValidInput`
+ * against the untouched contract.
+ * @param contract - the contract to project.
+ * @returns the parameter map plus the keywords enforced only at runtime.
+ */
+export declare function projectToDsh(contract: ToolContract): DshProjection;
+/**
+ * Project a contract's input schema into DSH parameters.
+ * @param contract - the contract to project.
+ * @returns the parameter map.
+ * @throws ProjectionError when the schema is internally inconsistent.
+ */
+export declare function toDshParameters(contract: ToolContract): DshParameters;
+/**
+ * Cross-field constraints the DSH parameter DSL cannot express (BASE-04).
+ *
+ * Each returns a violation message, or undefined when the arguments are
+ * acceptable. They run after schema validation, so each may assume its fields
+ * are present and correctly typed.
+ */
+export type CrossFieldRule = (args: Record<string, unknown>) => string | undefined;
+/** The cross-field rules that apply to a given contract. */
+export declare function crossFieldRules(contract: ToolContract): CrossFieldRule[];
+/**
+ * Project an arbitrary JSON Schema into the subset DSH can advertise (DECL-02).
+ *
+ * Written for the OUTPUT schema, which needs the same treatment the input schema
+ * already gets. Using the contract's raw output schema would crash registration on the
+ * first keyword the DSL cannot express — the failure that produced `runtimeEnforced` in
+ * the first place — and using an unconstrained `{type: "object", additionalProperties:
+ * true}` instead, which is what this replaced, publishes a tool whose result shape is
+ * declared to be anything at all.
+ * @param schema - the schema to project.
+ * @returns the projected schema plus the keywords left to runtime enforcement.
+ */
+export declare function projectSchemaToDsh(schema: Readonly<Record<string, unknown>>): DshProjection;
+export {};
+//# sourceMappingURL=dsh.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/dsh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh.d.ts","sourceRoot":"","sources":["../src/dsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,wEAAwE;AACxE,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhE,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAEvD,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5C;AAED,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAoB;IAC1C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;gBAC3B,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE;CAO7D;AAyFD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,CAuBlE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,CAErE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAA;AAElF,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,cAAc,EAAE,CAqCxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,CAsB3F"}