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

package/lib/publication.js

@@ -0,0 +1,181 @@
+/**
+ * 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-tool-mode/publication
+ */
+const CALLABLE_READINESS = new Set([
+    'prepared-cold',
+    'loading',
+    'ready',
+    'busy',
+]);
+/**
+ * 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 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'
+                    : CALLABLE_READINESS.has(implementation.readiness)
+                        ? `model is ${implementation.readiness}; 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 (!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({
+                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-store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * File-backed invocation-receipt store (EXT-35, recommendation slice 2).
+ *
+ * The host used to keep receipts only in a bounded in-memory ring, so a restart
+ * forgot every receipt. This store persists them next to the configured state
+ * file, bounded and atomically written, and it QUARANTINES malformed data rather
+ * than silently pretending the store was empty.
+ *
+ * Receipts are provenance, not content: the record shape is host-authored and
+ * never carries a request body, token, or full skill text (see receipt.ts).
+ *
+ * @module @try-works/dsh-tool-mode/receipt-store
+ */
+import { type InvocationReceipt } from './receipt.ts';
+/** The on-disk document version, so a future shape can refuse incompatible files. */
+export declare const RECEIPT_STORE_VERSION = 1;
+/** Where the receipt store lives for a given state file. */
+export declare function receiptStorePathFor(stateFile: string): string;
+/** One malformed store that was moved aside instead of being trusted. */
+export interface ReceiptQuarantine {
+    /** Where the offending bytes were moved. */
+    readonly quarantinePath: string;
+    /** Why the document was refused. Never contains receipt content. */
+    readonly reason: string;
+}
+/** What a receipt store exposes. */
+export interface ReceiptStore {
+    /** The file path, or a synthetic path for the memory store. */
+    readonly path: string;
+    /** Where malformed data was moved, when this instance quarantined a file. */
+    readonly quarantinePath?: string | undefined;
+    /** The persisted receipts, oldest first, at most the configured limit. */
+    readonly records: readonly InvocationReceipt[];
+    /** Append one receipt, enforce the bound, and persist it. */
+    append(receipt: InvocationReceipt): void;
+}
+/** Store construction options. */
+export interface ReceiptStoreOptions {
+    /** Retention bound; defaults to MAX_RETAINED_RECEIPTS. */
+    readonly limit?: number;
+    /** Called once for a malformed document, after it is moved aside. */
+    readonly onQuarantine?: (quarantine: ReceiptQuarantine) => void;
+}
+/** A file-backed store; the in-memory ring stays the host's read cache. */
+export declare function createFileReceiptStore(path: string, options?: ReceiptStoreOptions): ReceiptStore;
+/** The memory store used when persistence is disabled; same contract, no file. */
+export declare function createMemoryReceiptStore(options?: ReceiptStoreOptions): ReceiptStore;
+/**
+ * The highest receipt counter already used by `receipts`.
+ *
+ * Receipt ids are `rcpt_` plus a zero-padded base-36 counter. A new host continues
+ * from this floor so an id is never reused after a restart.
+ * @param receipts - the persisted receipts.
+ * @returns the highest counter, or 0 when none parse.
+ */
+export declare function receiptCounterFloor(receipts: readonly InvocationReceipt[]): number;
+//# sourceMappingURL=receipt-store.d.ts.map

package/lib/receipt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../src/receipt-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAE5E,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAC9C,6DAA6D;IAC7D,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACzC;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAChE;AA6CD,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAuCpG;AAED,kFAAkF;AAClF,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAYxF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAQlF"}

package/lib/receipt-store.js

@@ -0,0 +1,143 @@
+/**
+ * File-backed invocation-receipt store (EXT-35, recommendation slice 2).
+ *
+ * The host used to keep receipts only in a bounded in-memory ring, so a restart
+ * forgot every receipt. This store persists them next to the configured state
+ * file, bounded and atomically written, and it QUARANTINES malformed data rather
+ * than silently pretending the store was empty.
+ *
+ * Receipts are provenance, not content: the record shape is host-authored and
+ * never carries a request body, token, or full skill text (see receipt.ts).
+ *
+ * @module @try-works/dsh-tool-mode/receipt-store
+ */
+/*
+ * This module IS the I/O boundary for a hand-editable file: parsing `unknown`
+ * JSON is its job, and the shape checks below are the parser. The generic
+ * anti-slop rules assume a typed caller, so they are disabled only for this
+ * parser, and any mismatch quarantines the file instead of trusting it.
+ */
+/* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof, anti-slop/no-unsafe-dictionary-type, anti-slop/require-safety-comment-for-type-assertion */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { MAX_RETAINED_RECEIPTS } from "./receipt.js";
+/** The on-disk document version, so a future shape can refuse incompatible files. */
+export const RECEIPT_STORE_VERSION = 1;
+/** Where the receipt store lives for a given state file. */
+export function receiptStorePathFor(stateFile) {
+    return `${stateFile}.receipts.json`;
+}
+/** A receipt is shaped by the host, but a file may be hand-edited or truncated. */
+function isReceipt(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record['receiptId'] === 'string'
+        && record['receiptId'].length > 0
+        && typeof record['contract'] === 'string'
+        && typeof record['implementationId'] === 'string'
+        && typeof record['extension'] === 'string'
+        && typeof record['modelIdentity'] === 'string'
+        && typeof record['activationGeneration'] === 'number'
+        && Array.isArray(record['warnings']);
+}
+/** Parse one document, distinguishing "absent" from "malformed". */
+function parseDocument(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { ok: false, reason: `not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { ok: false, reason: 'the document is not a JSON object' };
+    const document = parsed;
+    if (document.version !== RECEIPT_STORE_VERSION) {
+        return { ok: false, reason: `unsupported receipt store version ${String(document.version)}` };
+    }
+    if (!Array.isArray(document.receipts))
+        return { ok: false, reason: 'receipts is not an array' };
+    const invalid = document.receipts.find(receipt => !isReceipt(receipt));
+    if (invalid !== undefined)
+        return { ok: false, reason: 'the store contains a malformed receipt' };
+    return { ok: true, receipts: document.receipts };
+}
+/** Keep the newest `limit` receipts, never exceeding it. */
+function bounded(receipts, limit) {
+    return receipts.length > limit ? receipts.slice(receipts.length - limit) : receipts;
+}
+/** A file-backed store; the in-memory ring stays the host's read cache. */
+export function createFileReceiptStore(path, options = {}) {
+    const limit = options.limit ?? MAX_RETAINED_RECEIPTS;
+    let records = [];
+    let quarantinePath;
+    if (existsSync(path)) {
+        const text = readFileSync(path, 'utf8');
+        const parsed = parseDocument(text);
+        if (parsed.ok) {
+            records = bounded([...parsed.receipts], limit);
+        }
+        else {
+            // QUARANTINE, never "start empty": overwriting the bytes would destroy the
+            // only evidence of what the store used to hold.
+            quarantinePath = `${path}.quarantined-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+            renameSync(path, quarantinePath);
+            options.onQuarantine?.({ quarantinePath, reason: parsed.reason });
+        }
+    }
+    const persist = () => {
+        mkdirSync(dirname(path), { recursive: true });
+        const temporary = `${path}.tmp-${process.pid.toString(36)}-${randomBytes(6).toString('hex')}`;
+        writeFileSync(temporary, `${JSON.stringify({ version: RECEIPT_STORE_VERSION, receipts: records }, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    };
+    return {
+        path,
+        get quarantinePath() {
+            return quarantinePath;
+        },
+        get records() {
+            return records;
+        },
+        append(receipt) {
+            records = bounded([...records, receipt], limit);
+            persist();
+        },
+    };
+}
+/** The memory store used when persistence is disabled; same contract, no file. */
+export function createMemoryReceiptStore(options = {}) {
+    const limit = options.limit ?? MAX_RETAINED_RECEIPTS;
+    let records = [];
+    return {
+        path: '(memory)',
+        get records() {
+            return records;
+        },
+        append(receipt) {
+            records = bounded([...records, receipt], limit);
+        },
+    };
+}
+/**
+ * The highest receipt counter already used by `receipts`.
+ *
+ * Receipt ids are `rcpt_` plus a zero-padded base-36 counter. A new host continues
+ * from this floor so an id is never reused after a restart.
+ * @param receipts - the persisted receipts.
+ * @returns the highest counter, or 0 when none parse.
+ */
+export function receiptCounterFloor(receipts) {
+    let floor = 0;
+    for (const receipt of receipts) {
+        if (!receipt.receiptId.startsWith('rcpt_'))
+            continue;
+        const value = Number.parseInt(receipt.receiptId.slice('rcpt_'.length), 36);
+        if (Number.isSafeInteger(value) && value > floor)
+            floor = value;
+    }
+    return floor;
+}
+//# sourceMappingURL=receipt-store.js.map

package/lib/receipt.d.ts

@@ -0,0 +1,231 @@
+/**
+ * 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 type { ExecutionLocation } from '@try-works/tool-mode-contracts';
+/** How many invocation receipts are retained (EXT-35), in memory and on disk. */
+export declare const MAX_RETAINED_RECEIPTS = 200;
+/** 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[];
+    /** Which provenance lane produced this receipt (OBS-01). */
+    readonly kind?: 'invocation' | 'nested' | 'auxiliary' | 'external';
+    /** The composition receipt a nested call belongs to. */
+    readonly parentReceiptId?: string | null;
+    /** Terminal outcome, when the producing lane knows it. */
+    readonly outcome?: 'ok' | 'failed' | 'cancelled' | 'policy-denied' | 'timed-out';
+    /** Token usage, or the honest unknown (never zero) for a lane that cannot measure it. */
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    } | 'unknown';
+    /** Monetary cost, or the honest unknown. */
+    readonly cost?: {
+        readonly amount: number;
+        readonly currency: string;
+    } | 'unknown';
+}
+/** 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[];
+    readonly kind?: InvocationReceipt['kind'];
+    readonly parentReceiptId?: string | null;
+    readonly outcome?: InvocationReceipt['outcome'];
+    readonly usage?: InvocationReceipt['usage'];
+    readonly cost?: InvocationReceipt['cost'];
+}): 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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"}