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

package/lib/ptc-runtime.js

@@ -0,0 +1,191 @@
+/**
+ * PTC runtime integration: a guarded mount and the ONE authorized tool pipeline.
+ *
+ * The directive is explicit that this is repository work, not a missing upstream product:
+ *
+ *   "Use the existing `@deepseek-ai/dsh-ptc-runtime` interface and a compatible
+ *    `@deepseek-ai/dsh-ptc-runtime-node` backend. Compose its filesystem, subprocess,
+ *    sandbox, and policy dependencies. **Do not call `ctx.ptcRuntime` without mounting a
+ *    provider and then report the missing service as an unavailable upstream product.**"
+ *
+ *   "Native DSH PTC and external `tool_mode_run` must use the SAME authorized tool
+ *    pipeline."
+ *
+ * Two facts shape the mount, both discovered by reading the DSH source rather than guessed:
+ *
+ * 1. **The base bundle already mounts a provider.** `packages/bundle/base/cordis.patch.yml`
+ *    registers `@deepseek-ai/dsh-ptc-runtime-node`, so an UNGUARDED `ctx.plugin(...)`
+ *    throws `service "ptcRuntime" has been registered at <...>`. The guard is mandatory in
+ *    both outcomes, so it is not conditional on which host this finds.
+ * 2. **The composed services are the inject list**, not something the plugin supplies:
+ *    `static inject = ['fs','subprocess','sandbox','sandboxPolicy']`. Mounting them here
+ *    would hit the same duplicate-service throw.
+ *
+ * Everything that touches Cordis or DSH is INJECTED, so the guard logic and the authorized
+ * pipeline are testable without a live runtime.
+ *
+ * @module @try-works/dsh-model-as-tool/ptc-runtime
+ */
+import { authorizeProgramTools, describeRejections, } from "./ptc-authority.js";
+/** The service key the abstract runtime registers itself under. */
+export const PTC_SERVICE = 'ptcRuntime';
+/**
+ * Mount the Node PTC backend, but only when nothing already provides the service.
+ *
+ * @param ctx - the host context.
+ * @param backend - the backend plugin, or `undefined` when it could not be resolved.
+ * @param config - backend configuration.
+ * @returns what happened.
+ */
+export async function mountPtcRuntimeIfAbsent(ctx, backend, config = {}) {
+    /**
+     * THE GUARD. Checked first, because the base bundle mounts a provider and an unguarded
+     * `ctx.plugin` throws rather than being idempotent.
+     */
+    if (ctx.get(PTC_SERVICE) !== undefined) {
+        return { mounted: false, reason: 'already-provided', service: PTC_SERVICE };
+    }
+    if (backend === undefined || backend === null) {
+        /**
+         * Reported as a REASON, not an exception: a deployment without the backend can still
+         * run native tools, and failing the whole plugin load would remove working
+         * functionality because an optional one is absent.
+         */
+        return { mounted: false, reason: 'backend-unavailable', service: PTC_SERVICE };
+    }
+    await ctx.plugin(backend, config);
+    return { mounted: true, service: PTC_SERVICE };
+}
+/** The default budgets, mirroring the backend's own documented defaults. */
+export const PTC_DEFAULT_BUDGETS = {
+    timeoutMs: 120_000,
+    maxTimeoutMs: 600_000,
+    maxOutputBytes: 64 * 1024 * 1024,
+    maxOldGenerationSizeMb: 512,
+};
+/**
+ * Build the namespace a program may call (CODE-03, SEC-03).
+ *
+ * Refuses the WHOLE request when any name is unattainable, so a program never runs against
+ * a smaller namespace than it declares.
+ *
+ * @param request - what to bind.
+ * @returns the namespace, or the refusal message.
+ */
+export function buildToolBindings(request) {
+    const decision = authorizeProgramTools({ requested: request.requested }, request.authority, request.resolve);
+    if (!decision.ok) {
+        return { ok: false, message: describeRejections(decision.rejections) };
+    }
+    const global = request.global ?? 'tools';
+    /**
+     * The namespace global obeys the same portability rule the backend enforces, so an
+     * invalid one is refused here with a clear reason rather than by the runtime later.
+     */
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(global)) {
+        return {
+            ok: false,
+            message: `the binding namespace "${global}" is not a language-portable identifier; `
+                + 'the same namespace list must work against every backend',
+        };
+    }
+    return { ok: true, namespace: { global, functions: decision.bindings } };
+}
+/**
+ * The budgets a run is admitted with (RES-10).
+ *
+ * A requested budget is clamped to the ceiling rather than refused: a caller asking for
+ * longer than policy allows gets policy's figure, which is the direction that cannot be
+ * widened by asking.
+ * @param requestedMs - what the caller asked for, if anything.
+ * @returns the admitted budget.
+ */
+export function admitTimeout(requestedMs) {
+    if (requestedMs === null) {
+        // `null` means "no deadline". That is a request to REMOVE a limit, so it is clamped to
+        // the ceiling rather than honoured — otherwise a caller could opt out of budgeting.
+        return PTC_DEFAULT_BUDGETS.maxTimeoutMs;
+    }
+    if (requestedMs === undefined)
+        return PTC_DEFAULT_BUDGETS.timeoutMs;
+    if (!Number.isFinite(requestedMs) || requestedMs <= 0)
+        return PTC_DEFAULT_BUDGETS.timeoutMs;
+    return Math.min(requestedMs, PTC_DEFAULT_BUDGETS.maxTimeoutMs);
+}
+/**
+ * Whether the confinement acceptance tests have passed on this deployment
+ * (CODE-09).
+ *
+ * This is the SINGLE release-gate flip point. It is a module-level flag with a
+ * TEST-ONLY setter so the acceptance test that eventually passes can open the
+ * gate for its own proof — the "export APPEARS when the gate opens" case must be
+ * executable before the gate opens in production, not exercised there for the
+ * first time. Production builds leave it false.
+ */
+let confinementEvidence = false;
+/** The current confinement evidence (CODE-09). */
+export function confinementDemonstrated() {
+    return confinementEvidence;
+}
+/**
+ * The environment marker that arms the test seam (CODE-09).
+ *
+ * The setter below SHIPS in the built artifact (there is no separate test
+ * bundle), so it must be inert in every normal process. It therefore refuses to
+ * move the gate unless the OPERATOR started this process with an explicit
+ * marker — which is itself an operator action, so opening the gate always costs
+ * an operator decision and never happens by config, by import or by accident.
+ * The acceptance test sets the marker; production never does.
+ */
+const CONFINEMENT_SEAM_ENV = 'DSH_PTC_CONFINEMENT_SEAM';
+const CONFINEMENT_SEAM_TOKEN = 'open-for-acceptance-test';
+/**
+ * Set the confinement evidence (TEST SEAM, CODE-09).
+ *
+ * The setter is the seam the acceptance test uses. It is inert — throws without
+ * moving anything — unless the process carries the explicit environment marker,
+ * so the built artifact cannot have the gate opened by code that merely imports
+ * it. A production build never sets the marker.
+ * @param value - the evidence state to adopt.
+ */
+export function setConfinementDemonstratedForTest(value) {
+    if (process.env[CONFINEMENT_SEAM_ENV] !== CONFINEMENT_SEAM_TOKEN) {
+        throw new Error('the confinement evidence is a release gate; the acceptance-test seam is '
+            + 'closed in this process because the operator marker is absent');
+    }
+    confinementEvidence = value;
+}
+/**
+ * Whether generated-code execution may be exposed to callers (CODE-08, CODE-10).
+ *
+ * Exposure is the CONJUNCTION of two independent facts, and neither can stand in
+ * for the other:
+ *
+ * - CODE-09: the specification's confinement tests must have passed. They have
+ *   not run here, so this half is false — no configuration can open it.
+ * - CODE-10: the OPERATOR must have granted hosted code execution, which is a
+ *   separate consent from ordinary model-tool access. The caller passes the
+ *   operator's grant in, so the gate has a real input rather than being a literal.
+ *
+ * A host with the grant flipped but no confinement evidence stays closed; a host
+ * with confinement evidence but no operator grant stays closed too.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns whether a caller may be served.
+ */
+export function mayExposeToClients(operatorGranted) {
+    return operatorGranted && confinementDemonstrated();
+}
+/**
+ * Describe why generated-code execution is withheld, naming WHICH fact is unmet.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns the reason callers are given.
+ */
+export function exposureWithheldReason(operatorGranted) {
+    if (!operatorGranted) {
+        return 'generated-code execution is disabled: the operator has not granted hosted '
+            + 'code execution (CODE-10); it is a separate consent from model-tool access';
+    }
+    return 'generated-code execution is withheld until the confinement tests pass; '
+        + 'the runtime is mounted and usable in-process, and no production client is served it';
+}
+//# sourceMappingURL=ptc-runtime.js.map

package/lib/publication.d.ts

@@ -24,6 +24,7 @@
  *
  * @module @try-works/dsh-model-as-tool/publication
  */
+import type { ModelReadiness } from '@try-works/tool-mode-extension-sdk';
 /** Why a candidate contribution did not reach the published surface. */
 export interface WithheldContribution {
     /** Stable reason code. */
@@ -42,7 +43,7 @@ export interface ImplementationCandidate {
     /** The catalog model backing it. */
     readonly modelId: string;
     /** Whether the model is prepared and callable right now. */
-    readonly readiness: 'unprepared' | 'preparing' | 'ready' | 'failed';
+    readonly readiness: ModelReadiness;
     /** Whether the model can run on this host at all. */
     readonly runnable: boolean;
 }

package/lib/publication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AASxE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EACT,mBAAmB,GACnB,mBAAmB,GACnB,2BAA2B,GAC3B,cAAc,CAAA;IAClB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,SAAS,uBAAuB,EAAE,CAAA;CAC7D;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,CAAA;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAA;IACxD,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED,yBAAyB;AACzB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAA;IACzC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAA;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;CACnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;CAC3C,GAAG,iBAAiB,CAoGpB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB;;gBAIjB,OAAO,GAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAA;KAAO;IAK5I,wCAAwC;IACxC,IAAI,OAAO,IAAI,iBAAiB,CAE/B;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAMtC;;;;;;;OAOG;IACH,cAAc,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,cAAc,EAAE;CAI/E"}

package/lib/publication.js

@@ -24,6 +24,12 @@
  *
  * @module @try-works/dsh-model-as-tool/publication
  */
+const CALLABLE_READINESS = new Set([
+    'prepared-cold',
+    'loading',
+    'ready',
+    'busy',
+]);
 /**
  * Build a coherent surface from the candidates available now.
  *
@@ -56,12 +62,14 @@ export function buildSurface(options) {
                 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',
+                // Callable requires BOTH that the host can run it and that preparation
+                // says a call is possible. Residency states such as prepared-cold/loading
+                // affect admission, not publication (RES-04).
+                callable: implementation.runnable && CALLABLE_READINESS.has(implementation.readiness),
                 reason: !implementation.runnable
                     ? 'this model cannot run on this host'
-                    : implementation.readiness === 'ready'
-                        ? 'prepared and callable'
+                    : CALLABLE_READINESS.has(implementation.readiness)
+                        ? `model is ${implementation.readiness}; prepared and callable`
                         : `model is ${implementation.readiness}; the tool is not advertised as working`,
             });
         }
@@ -84,7 +92,7 @@ export function buildSurface(options) {
             });
             continue;
         }
-        if (selected.readiness !== 'ready') {
+        if (!CALLABLE_READINESS.has(selected.readiness)) {
             // EXT-24: an active package with an unprepared model may publish readiness
             // and preparation guidance, but MUST NOT advertise working inference.
             withheld.push({

package/lib/receipt.d.ts.map

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

package/lib/receipt.js

@@ -63,6 +63,14 @@ export function redactText(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>')
+        // SEC-01: a generated secret is exactly 32 base64url bytes (43 characters). A
+        // note that ever embedded one is redacted here, even though nothing in the
+        // receipt pipeline takes a secret as input. The boundaries are NON-WORD
+        // lookarounds, not \b: a base64url secret may begin or end with '-' (or '_'),
+        // which are word characters — a \b-bounded pattern misses such a secret when
+        // it abuts another word character, and the reviewer demonstrated real
+        // crypto-random secrets with a leading '-' surviving redaction.
+        .replace(/(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g, '<redacted>')
         .replace(/[A-Za-z]:\\[^\s"']*/g, '<path>')
         .replace(/(?<![\w.])\/(?:[\w.-]+\/)+[\w.-]+/g, '<path>');
 }

package/lib/title-proposal.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Title and description proposal (TOOL-06), with the language-evidence rule from
+ * TOOL-03.
+ *
+ * TOOL-06 is mostly a list of things a title generator must NOT do, and the sharpest of
+ * them is this: **a refusal or an incomplete generation must not become a valid empty
+ * title.** That failure is easy to ship and hard to notice, because the shape of the
+ * response is correct — `{ title: "" }` looks like a result — and a caller writing it
+ * into a document produces an empty heading rather than an error.
+ *
+ * The other rules here are enforced rather than described:
+ *
+ * - **No invented facts.** A number in a proposed title that does not appear in the
+ *   source is a claim the source does not support. This is checkable, so it is checked.
+ * - **No changed source meaning.** Enforced through the same provenance check plus a
+ *   refusal to accept a title with no overlap with the source.
+ * - **No calling another tool.** Structural: the response shape carries no tool-call
+ *   field, so there is nothing to dispatch.
+ * - **Maximum lengths in the schema**, which the contract states and this enforces.
+ *
+ * @module @try-works/dsh-model-as-tool/title-proposal
+ */
+/** The lengths the contract states (TOOL-06). */
+export interface TitleLimits {
+    /** Maximum characters in a title. */
+    readonly maxTitleChars: number;
+    /** Maximum characters in a description. */
+    readonly maxDescriptionChars: number;
+    /** Maximum repair attempts permitted. Zero when repairs are disabled. */
+    readonly maxRepairs: number;
+}
+/**
+ * The evaluated defaults for a section title (TOOL-06).
+ *
+ * Stated in the contract rather than chosen per call, because "define maximum
+ * title/description lengths in the schema and evaluated recipe" means a caller cannot
+ * widen them by asking.
+ */
+export declare const SECTION_TITLE_LIMITS: TitleLimits;
+/**
+ * The contract limits for one configuration's CODE-11 repair ceiling.
+ *
+ * The title/description lengths stay contract-stated; the repair ceiling is
+ * the operator's configured number (an integer 0..8, default 1). An invalid
+ * ceiling is a REFUSAL, never a silent clamp — the recorded lineage must show
+ * the budget the operator actually approved.
+ * @param repairCeiling - the configured ceiling; absent means the default 1.
+ * @returns the limits the repair decision and lineage honor.
+ */
+export declare function titleLimitsFor(repairCeiling?: number): TitleLimits;
+/** What a title is being proposed for. */
+export type TitleKind = 'section' | 'page' | 'document';
+/** The raw response a text model produced (TOOL-06). */
+export interface RawTitleResponse {
+    /** The title text, when the model produced one. */
+    readonly title?: string;
+    /** The description text, when the model produced one. */
+    readonly description?: string;
+    /**
+     * Set when the model refused.
+     *
+     * Distinguishing a refusal from an empty generation is what stops the first becoming
+     * a valid empty title.
+     */
+    readonly refused?: boolean;
+    /** Why it refused, when it did. */
+    readonly refusalReason?: string;
+    /**
+     * Set when generation was cut short.
+     *
+     * A truncated generation is not a short one; reporting it as a title claims a
+     * complete answer from an incomplete one.
+     */
+    readonly incomplete?: boolean;
+}
+/** How a proposal ended. */
+export type TitleOutcome = 
+/** A usable title. */
+{
+    readonly kind: 'proposed';
+    readonly title: string;
+    readonly description: string;
+    /** How many repair attempts were consumed, for the accounting TOOL-06 asks for. */
+    readonly repairs: number;
+}
+/**
+ * The model refused.
+ *
+ * An ERROR for the caller, never an empty title.
+ */
+ | {
+    readonly kind: 'refused';
+    readonly reason: string;
+}
+/** The generation was cut short. An error, never a short title. */
+ | {
+    readonly kind: 'incomplete';
+    readonly reason: string;
+}
+/** The response could not be used as a title. */
+ | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+}
+/** The response failed validation against a rule below. */
+ | {
+    readonly kind: 'rejected';
+    readonly reason: string;
+};
+/**
+ * Accept or refuse a title proposal (TOOL-06).
+ *
+ * @param response - the model's raw response.
+ * @param source - the text the title was proposed for, used for provenance.
+ * @param limits - the lengths the contract states.
+ * @returns the outcome, which is an error rather than an empty title whenever the
+ *   response was not a usable one.
+ */
+export declare function acceptTitle(response: RawTitleResponse, source: string, limits?: TitleLimits): TitleOutcome;
+/**
+ * Whether a repair attempt may run (TOOL-06).
+ *
+ * The requirement says to COUNT repair attempts when they are enabled, so the count is
+ * returned rather than kept internally — an uncounted retry is how a budget silently
+ * becomes unbounded.
+ * @param limits - the contract's limits.
+ * @param repairsSoFar - repairs already consumed.
+ * @param previous - what the previous attempt produced.
+ * @returns whether to repair, and how many repairs would then be consumed.
+ */
+export declare function mayRepairTitle(limits: TitleLimits, repairsSoFar: number, previous: TitleOutcome): {
+    readonly repair: boolean;
+    readonly repairs: number;
+    readonly reason?: string;
+};
+/**
+ * One repair-lineage entry (CODE-11): the traceable per-attempt record the
+ * budget lineage owes — which repair, the budget before and after the
+ * decision, and the outcome the decision produced. A COUNT alone cannot show
+ * WHERE a budget was spent; the lineage does.
+ */
+export interface RepairLineageEntry {
+    /** One-based repair attempt index. */
+    readonly repairIndex: number;
+    /** The repair budget before the decision. */
+    readonly budgetBefore: number;
+    /** The repair budget after the decision (one lower when a repair ran). */
+    readonly budgetAfter: number;
+    /** What the previous attempt produced, so the lineage names WHY. */
+    readonly previousKind: string;
+    /** The decision outcome for this attempt. */
+    readonly outcome: 'repaired' | 'exhausted' | 'not-needed';
+}
+/**
+ * Record one repair decision into the lineage (CODE-11, pure and testable).
+ * @param lineage - the lineage so far (mutated in place, then returned).
+ * @param decision - the `mayRepairTitle` decision for this attempt.
+ * @param previousKind - the previous outcome kind.
+ * @param budgetBefore - the budget the decision was made against.
+ * @returns the updated lineage.
+ */
+export declare function recordRepairLineage(lineage: RepairLineageEntry[], decision: {
+    readonly repair: boolean;
+    readonly repairs: number;
+}, previousKind: string, budgetBefore: number): RepairLineageEntry[];
+/**
+ * Whether a tool may call another tool to fulfil this contract (TOOL-06).
+ *
+ * It may not: "do not call another tool". Returns false so the prohibition is asserted,
+ * and the response shape carries no tool-call field for one to be dispatched from.
+ * @returns always false.
+ */
+export declare function mayCallAnotherTool(): boolean;
+/** What a language result actually examined (TOOL-03). */
+export type LanguageEvidence = 'text' | 'audio';
+/**
+ * Whether a language result may be cited as evidence for a medium (TOOL-03).
+ *
+ * A text detector's result is evidence about the TEXT it processed and nothing else.
+ * The requirement forbids using it as evidence of the language SPOKEN in audio it has
+ * not processed, and the refusal is per-medium rather than per-result because the result
+ * itself is sound — only its use as audio evidence is not.
+ * @param examined - what the result examined.
+ * @param claimed - the medium being claimed.
+ * @returns whether the claim is supported.
+ */
+export declare function supportsLanguageClaim(examined: LanguageEvidence, claimed: LanguageEvidence): boolean;
+/**
+ * Describe what a language result is evidence for (TOOL-03).
+ * @param examined - what the result examined.
+ * @returns a description that does not overstate the result.
+ */
+export declare function describeLanguageEvidence(examined: LanguageEvidence): string;
+//# sourceMappingURL=title-proposal.d.ts.map

package/lib/title-proposal.d.ts.map

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