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

package/lib/receipt.js

@@ -0,0 +1,165 @@
+/**
+ * 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-tool-mode/receipt
+ */
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
+/** How many invocation receipts are retained (EXT-35), in memory and on disk. */
+export const MAX_RETAINED_RECEIPTS = 200;
+/** 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>')
+        // 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>');
+}
+/**
+ * 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),
+        kind: input.kind ?? 'invocation',
+        parentReceiptId: input.parentReceiptId ?? null,
+        ...input.outcome === undefined ? {} : { outcome: input.outcome },
+        ...input.usage === undefined ? {} : { usage: input.usage },
+        ...input.cost === undefined ? {} : { cost: input.cost },
+    };
+}
+/**
+ * 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

@@ -0,0 +1,75 @@
+/**
+ * The registrar: turns each runnable catalog model into a DSH tool.
+ *
+ * The registrar owns the translation from the catalog's declarative tool spec
+ * into a `defineTool` definition, including the parameter schema, the canonical
+ * output contract and the model-facing rendering. Registration goes through
+ * `ctx.tools.register`, whose returned disposer is the only unregister API, so
+ * the plugin can add or drop a model's tool at runtime as capability changes.
+ *
+ * @module @try-works/dsh-tool-mode/registrar
+ */
+import { type ParameterSchemaSpec } from '@deepseek-ai/dsh-tools';
+import type { ModelCatalogEntry } from './types.ts';
+import type { ModelAdapter } from './adapters/index.ts';
+/** The tool spec a catalog entry declares, resolved into a registration. */
+export interface RegisteredModelTool {
+    readonly modelId: string;
+    readonly toolName: string;
+    readonly dispose: () => void;
+}
+/**
+ * Build the parameter schema for one model's tool.
+ *
+ * Every catalog parameter is advertised as OPTIONAL here: the catalog has no
+ * explicit requiredness metadata, and inferring it from parameter order was a
+ * model-specific assumption BASE-04 forbids. The adapter validates the model's
+ * primary input as a required non-empty value, so an omitted argument is still
+ * refused — just by the adapter's rule rather than by an inferred schema flag.
+ * Types come from the catalog declaration, so a numeric or list parameter reaches
+ * the model as the type it actually is rather than as a string it re-parses.
+ * @param entry - the catalog entry.
+ * @returns the DSH parameter schema spec.
+ */
+export declare function buildParameters(entry: ModelCatalogEntry): ParameterSchemaSpec;
+/**
+ * Render the tool result for the model.
+ *
+ * The canonical value is the source of truth; this projection only chooses how
+ * to present it. Tongue's shaped result gets a sentence the model can act on
+ * directly, while everything else falls back to stable JSON so no information
+ * is lost to a lossy humanization.
+ * @param entry - the catalog 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 declare function renderResult(entry: ModelCatalogEntry, value: Record<string, unknown>): {
+    type: 'text';
+    text: string;
+}[];
+/**
+ * Register one model's tool on the calling context.
+ * @param ctx - the context whose tool registry receives the definition; its scope decides visibility.
+ * @param entry - the catalog entry to expose.
+ * @param adapter - the adapter that invokes the model.
+ * @returns the model id, the tool name, and the disposer returned by the registry.
+ */
+export declare function registerModelTool(ctx: {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+}, entry: ModelCatalogEntry, adapter: ModelAdapter): RegisteredModelTool;
+//# sourceMappingURL=registrar.d.ts.map

package/lib/registrar.d.ts.map

@@ -0,0 +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;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAQ7E;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

@@ -0,0 +1,152 @@
+/**
+ * The registrar: turns each runnable catalog model into a DSH tool.
+ *
+ * The registrar owns the translation from the catalog's declarative tool spec
+ * into a `defineTool` definition, including the parameter schema, the canonical
+ * output contract and the model-facing rendering. Registration goes through
+ * `ctx.tools.register`, whose returned disposer is the only unregister API, so
+ * the plugin can add or drop a model's tool at runtime as capability changes.
+ *
+ * @module @try-works/dsh-tool-mode/registrar
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+/**
+ * Compile one declared parameter into the registry's parameter spec.
+ * @param type - the declared JSON-level type.
+ * @param description - the model-facing description.
+ * @param required - whether the parameter must be supplied.
+ * @returns the parameter property spec.
+ */
+function parameterSpec(type, description, required) {
+    const base = type === 'string[]'
+        ? { type: 'array', items: { type: 'string' } }
+        : { type };
+    return {
+        ...base,
+        description,
+        ...required ? { required: true } : {},
+    };
+}
+/**
+ * Build the parameter schema for one model's tool.
+ *
+ * Every catalog parameter is advertised as OPTIONAL here: the catalog has no
+ * explicit requiredness metadata, and inferring it from parameter order was a
+ * model-specific assumption BASE-04 forbids. The adapter validates the model's
+ * primary input as a required non-empty value, so an omitted argument is still
+ * refused — just by the adapter's rule rather than by an inferred schema flag.
+ * Types come from the catalog declaration, so a numeric or list parameter reaches
+ * the model as the type it actually is rather than as a string it re-parses.
+ * @param entry - the catalog entry.
+ * @returns the DSH parameter schema spec.
+ */
+export function buildParameters(entry) {
+    const params = entry.tool.params;
+    const schema = {};
+    for (const [name, param] of Object.entries(params)) {
+        if (param === undefined)
+            continue;
+        schema[name] = parameterSpec(param.type ?? 'string', param.description, false);
+    }
+    return schema;
+}
+/**
+ * Render the tool result for the model.
+ *
+ * The canonical value is the source of truth; this projection only chooses how
+ * to present it. Tongue's shaped result gets a sentence the model can act on
+ * directly, while everything else falls back to stable JSON so no information
+ * is lost to a lossy humanization.
+ * @param entry - the catalog 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.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(', ');
+        // 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.contract === 'stt.transcribe' && typeof value.text === 'string') {
+        const wordCount = typeof value.wordCount === 'number' ? value.wordCount : 0;
+        return [{
+                type: 'text',
+                text: value.text.length > 0
+                    ? value.text
+                    : `(no speech recognized; ${wordCount} words)`,
+            }];
+    }
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+/** The JSON-Schema type of the canonical value a model tool returns. */
+function outputSchemaFor(entry) {
+    // One open object schema for every model: the adapters return model-specific
+    // fields, and the registry validates the declared shape without forbidding a
+    // field a future adapter adds.
+    void entry;
+    return { type: 'object', additionalProperties: true };
+}
+/**
+ * Register one model's tool on the calling context.
+ * @param ctx - the context whose tool registry receives the definition; its scope decides visibility.
+ * @param entry - the catalog entry to expose.
+ * @param adapter - the adapter that invokes the model.
+ * @returns the model id, the tool name, and the disposer returned by the registry.
+ */
+export function registerModelTool(ctx, entry, adapter) {
+    const definition = defineTool({
+        name: entry.tool.name,
+        description: entry.tool.description,
+        parameters: buildParameters(entry),
+        output: {
+            schema: outputSchemaFor(entry),
+            render: (_args, value) => renderResult(entry, value),
+        },
+        async execute(args, exec) {
+            const value = await adapter.invoke({
+                args: args,
+                signal: exec.signal,
+            });
+            return value;
+        },
+        presentCall(args) {
+            const primary = Object.values(args)[0];
+            const preview = typeof primary === 'string' ? primary : undefined;
+            return {
+                card: 'generic',
+                title: `${entry.name}${entry.input === 'text' ? '' : ` (${entry.input})`}`,
+                kind: 'read',
+                ...preview !== undefined && entry.input === 'text' ? { rawInput: preview } : {},
+            };
+        },
+    });
+    const dispose = ctx.tools.register(definition);
+    return { modelId: entry.id, toolName: entry.tool.name, dispose };
+}
+//# sourceMappingURL=registrar.js.map

package/lib/resource-governance.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Resource governance (RES-01, RES-04, RES-06, RES-09).
+ *
+ * Three distinctions here are easy to collapse and expensive to get wrong.
+ *
+ * **Readiness is not residency** (RES-04). The state vocabulary has eight members,
+ * and they answer two DIFFERENT questions: `unavailable` and `needs-preparation` say
+ * a call is not possible at all, while `prepared-cold`, `loading`, `ready` and `busy`
+ * say it is possible and merely describe how the call will be admitted. Treating
+ * `prepared-cold` as uncallable withdraws a tool that works, and — worse — makes the
+ * tool surface change on every warm/cold transition, which RES-04 explicitly forbids
+ * because an agent's view of its tools must not flicker with a cache.
+ *
+ * **A budget is a rejection, not a truncation** (RES-01, RES-09). Over-budget input
+ * is refused WITH THE ACTUAL LIMITS, because a caller that cannot see the limit
+ * cannot choose a smaller input. Silently trimming source data is the failure both
+ * requirements name.
+ *
+ * **Cancellation is a claim about behaviour** (RES-06). Where a backend cannot be
+ * interrupted, saying "cancelled" while its work continues is worse than admitting
+ * the work is still running, so the outcome says which of the two happened.
+ *
+ * @module @try-works/dsh-tool-mode/resource-governance
+ */
+/**
+ * The eight readiness/residency states (RES-04).
+ *
+ * Named `Readiness` rather than `Residency` because it holds both dimensions; the
+ * two derived functions below are what separate them.
+ */
+export type Readiness = 
+/** No compatible implementation exists on this host. */
+'unavailable'
+/** Compatible, but its assets have not been prepared. */
+ | 'needs-preparation'
+/** Preparation is under way. */
+ | 'preparing'
+/** Prepared and not loaded: a call will load first. */
+ | 'prepared-cold'
+/** Currently loading. */
+ | 'loading'
+/** Loaded and idle. */
+ | 'ready'
+/** Loaded and serving; further calls queue. */
+ | 'busy'
+/** Preparation or loading failed. */
+ | 'failed';
+/**
+ * Whether a call is possible in this state (RES-04).
+ *
+ * Determined by compatibility, authorization and PREPARATION — never by residency.
+ * @param state - the current state.
+ * @returns whether the tool can be called.
+ */
+export declare function isCallable(state: Readiness): boolean;
+/**
+ * Whether assets are prepared (RES-04).
+ * @param state - the current state.
+ * @returns whether preparation has completed.
+ */
+export declare function isPrepared(state: Readiness): boolean;
+/** How a call is admitted in a given state (RES-04). */
+export type Admission = 
+/** Runs now. */
+'immediate'
+/** Will load first, so it takes longer. */
+ | 'loads-first'
+/** Waits for the current call to finish. */
+ | 'queued';
+/**
+ * How residency affects admission (RES-04).
+ *
+ * This is the half that residency legitimately controls: not WHETHER a tool exists,
+ * but what a call to it costs.
+ * @param state - the current state.
+ * @returns the admission behaviour, or undefined when no call is possible.
+ */
+export declare function admissionOf(state: Readiness): Admission | undefined;
+/**
+ * Whether a tool DESCRIPTION may vary with this state (RES-04).
+ *
+ * Always false. RES-04 forbids changing agent tool descriptions on every warm/cold
+ * transition, so this exists to be asserted rather than to be consulted: a caller
+ * that branches on residency when building a description has found a bug.
+ * @returns always false.
+ */
+export declare function descriptionMayVaryWithResidency(): boolean;
+/** A budgeted resource (RES-09). */
+export type BudgetKind = 'sourceBytes' | 'decodedPixels' | 'audioSamples' | 'videoSeconds' | 'videoFrames' | 'processorTokens' | 'batch' | 'outputVectors';
+/** Limits for one input class. `null` means the constraint does not apply. */
+export type Budget = Partial<Record<BudgetKind, number | null>>;
+/**
+ * The product defaults the requirement names verbatim (RES-09).
+ *
+ * These are PRODUCT limits, not guarantees that every input within them fits: the
+ * requirement says model context limits may force lower admission, so a successful
+ * check here is necessary and not sufficient.
+ */
+export declare const DEFAULT_BUDGETS: Readonly<Record<'image' | 'video' | 'audio' | 'text', Budget>>;
+/** A measured input. */
+export type Measurement = Partial<Record<BudgetKind, number>>;
+/** The outcome of admitting an input. */
+export type AdmissionDecision = {
+    readonly admitted: true;
+} | {
+    readonly admitted: false;
+    /** Every exceeded budget, with the actual limit. */
+    readonly exceeded: readonly {
+        readonly kind: BudgetKind;
+        readonly measured: number;
+        readonly limit: number;
+    }[];
+};
+/**
+ * Decide whether an input fits its budget (RES-01, RES-09).
+ *
+ * Over-budget input is REJECTED with the actual limits. It is never truncated and
+ * never sampled down, because the caller cannot otherwise tell that what it supplied
+ * is not what was processed.
+ * @param measurement - what the input actually is.
+ * @param budget - the limits in force.
+ * @returns the decision, naming every exceeded budget.
+ */
+export declare function admit(measurement: Measurement, budget: Budget): AdmissionDecision;
+/**
+ * Render a rejection the caller can act on (RES-01).
+ *
+ * The requirement says to reject with ACTUAL LIMITS: a caller told only "too large"
+ * cannot choose a smaller input.
+ * @param decision - a rejection.
+ * @returns the message.
+ */
+export declare function describeRejection(decision: Extract<AdmissionDecision, {
+    admitted: false;
+}>): string;
+/** An explicit sampling instruction (RES-09). */
+export interface SamplingPlan {
+    /** What was sampled, in the caller's terms. */
+    readonly instruction: string;
+    /** The budget that forced sampling, when one did. */
+    readonly forcedBy: BudgetKind | null;
+}
+/** What was actually processed, returned so coverage is never implied. */
+export interface Coverage {
+    /** Whether every unit of the source was processed. */
+    readonly complete: boolean;
+    /** Units processed. */
+    readonly processed: number;
+    /** Units in the source. */
+    readonly total: number;
+    /** The sampling that was applied, when any was. */
+    readonly sampling: SamplingPlan | null;
+    /** Why coverage is incomplete. */
+    readonly reason: string | null;
+}
+/**
+ * Build the coverage report for an input that had to be sampled (RES-09).
+ *
+ * Sampling is only legitimate when it is EXPLICIT and its coverage is REPORTED. An
+ * implementation that quietly processed 32 of 900 frames and reported success has
+ * told the caller something false about the input it supplied.
+ * @param processed - units processed.
+ * @param total - units in the source.
+ * @param sampling - the instruction applied, when one was.
+ * @returns the coverage report.
+ */
+export declare function coverageOf(processed: number, total: number, sampling: SamplingPlan | null): Coverage;
+/** How a cancellation actually ended (RES-06). */
+export type CancellationOutcome = 
+/** The work stopped and released its resources. */
+{
+    readonly stopped: true;
+}
+/**
+ * The work could not be interrupted. It continues to completion, and its result
+ * is discarded rather than delivered.
+ */
+ | {
+    readonly stopped: false;
+    readonly reason: string;
+};
+/**
+ * Describe a cancellation honestly (RES-06).
+ *
+ * RES-06 forbids claiming cancellation while uncontrolled work continues
+ * indefinitely. Where a backend cannot be interrupted safely, the honest report is
+ * that it is still running and its result will be discarded — which is also why the
+ * requirement prefers isolating such a backend in an owned worker.
+ * @param interruptible - whether the backend can be interrupted safely.
+ * @param subject - what is being cancelled, for the message.
+ * @returns the outcome to report.
+ */
+export declare function cancellationOutcome(interruptible: boolean, subject: string): CancellationOutcome;
+/**
+ * Whether a decompression bomb must be rejected before allocation (RES-09).
+ *
+ * The check is on the DECLARED expanded size, before any allocation: a check that
+ * runs after decompression has already lost.
+ * @param declaredBytes - the expansion the container declares.
+ * @param limit - the budget for this input class.
+ * @returns whether to reject.
+ */
+export declare function isExpansionBomb(declaredBytes: number, limit: number): boolean;
+//# sourceMappingURL=resource-governance.d.ts.map

package/lib/resource-governance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governance.d.ts","sourceRoot":"","sources":["../src/resource-governance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS;AACnB,wDAAwD;AACtD,aAAa;AACf,yDAAyD;GACvD,mBAAmB;AACrB,gCAAgC;GAC9B,WAAW;AACb,uDAAuD;GACrD,eAAe;AACjB,yBAAyB;GACvB,SAAS;AACX,uBAAuB;GACrB,OAAO;AACT,+CAA+C;GAC7C,MAAM;AACR,qCAAqC;GACnC,QAAQ,CAAA;AAoBZ;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED,wDAAwD;AACxD,MAAM,MAAM,SAAS;AACnB,gBAAgB;AACd,WAAW;AACb,2CAA2C;GACzC,aAAa;AACf,4CAA4C;GAC1C,QAAQ,CAAA;AAEZ;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAUnE;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,IAAI,OAAO,CAEzD;AAED,oCAAoC;AACpC,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,eAAe,GACf,cAAc,GACd,cAAc,GACd,aAAa,GACb,iBAAiB,GACjB,OAAO,GACP,eAAe,CAAA;AAEnB,8EAA8E;AAC9E,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,EAAE,MAAM,CAAC,CAkB1F,CAAA;AAED,wBAAwB;AACxB,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;AAE7D,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC3B;IACA,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KACvB,EAAE,CAAA;CACJ,CAAA;AAEH;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAYjF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,iBAAiB,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAC,GAAG,MAAM,CAInG;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAA;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,QAAQ,CAgBpG;AAED,kDAAkD;AAClD,MAAM,MAAM,mBAAmB;AAC7B,mDAAmD;AACjD;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE;AAC5B;;;GAGG;GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAExD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAOhG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7E"}