theorum 0.1.15 → 1.1.3

package/esm/src/observability/trace-record.js

@@ -6,45 +6,67 @@
  *
  * @module
  */
+import { OMIT_CANARY } from '../guardrails/canary.js';
 import { isAbortError, publicError } from '../guardrails/error.js';
-import { redactSensitiveOnly, sanitizeText, sanitizeTurnRequest } from '../guardrails/sanitize.js';
-import { OMIT_CANARY } from '../kernel/engine/boundary.js';
+import { projectGuardrailEvent } from '../guardrails/hits.js';
+import { redactSensitiveOnly, sanitizeText, sanitizeTurnRequestForTrace, } from '../guardrails/sanitize.js';
 import { sha256 } from '../kernel/engine/hash.js';
+import { resolveObservabilityPolicy } from './resolve-policy.js';
 import { attachResolved, attachTape, attachUsage } from './trace-attach.js';
-import { completedInteraction } from './trace-usage.js';
+import { completedInteraction, stopKindFromEvents } from './trace-usage.js';
 const TRACE_VERSION = 2;
 const TITLE_MAX = 80;
 function hashBlobs(blobs) {
     if (!blobs) {
         return Promise.resolve([]);
     }
-    return Promise.all(blobs.map(async (blob) => ({
-        mimeType: blob.mimeType,
-        sha256: await sha256(blob.data),
-    })));
+    return Promise.all(blobs.map(async (blob) => 'uri' in blob
+        ? { mimeType: blob.mimeType, uri: blob.uri }
+        : { mimeType: blob.mimeType, sha256: await sha256(blob.data) }));
 }
-async function snapshotEvent(event) {
+function scrubStoredText(text, scrub) {
+    if (scrub.sensitive && scrub.injection) {
+        return sanitizeText(text);
+    }
+    if (scrub.sensitive) {
+        return redactSensitiveOnly(text);
+    }
+    if (scrub.injection) {
+        return sanitizeText(text, { sanitizeInput: true, redactSensitive: false });
+    }
+    return text;
+}
+async function snapshotEvent(event, include, scrub) {
     const row = { type: event.type };
     if (event.text) {
-        row.text = redactSensitiveOnly(event.text);
+        row.text = scrubStoredText(event.text, scrub);
     }
     if (event.error) {
         row.error = event.error;
     }
     if (event.errorInternal) {
-        row.errorInternal = redactSensitiveOnly(event.errorInternal);
+        row.errorInternal = scrubStoredText(event.errorInternal, scrub);
     }
     if (event.structured !== undefined) {
         row.structured = event.structured;
     }
     if (event.tool) {
-        const { name, arguments: args, result } = event.tool;
+        const { name, arguments: args, output, phase, failure } = event.tool;
         row.tool = { name, arguments: args };
-        if (result) {
+        if (output !== undefined && phase === 'complete') {
+            const data = typeof output === 'object' && output !== null
+                ? output
+                : { value: output };
+            row.tool.result = {
+                status: 'ok',
+                ...(typeof data.finding === 'string' ? { finding: data.finding } : {}),
+                data,
+            };
+        }
+        else if (phase === 'error' && failure) {
             row.tool.result = {
-                status: result.status,
-                ...(result.finding ? { finding: result.finding } : {}),
-                ...(result.data ? { data: result.data } : {}),
+                status: 'error',
+                finding: failure.message,
             };
         }
     }
@@ -57,18 +79,16 @@ async function snapshotEvent(event) {
     if (event.grounding) {
         row.grounding = event.grounding;
     }
-    if (event.evidence) {
+    if (include.evidenceRaw && event.evidence) {
         row.evidence = event.evidence;
     }
+    if (event.guardrail) {
+        row.guardrail = projectGuardrailEvent(event.guardrail, include.guardrailMatchPreview);
+    }
     return row;
 }
 function requestForTrace(req) {
-    try {
-        return sanitizeTurnRequest(req);
-    }
-    catch {
-        return { profile: req.profile, input: {} };
-    }
+    return sanitizeTurnRequestForTrace(req);
 }
 function internalError(err) {
     if (typeof err === 'string') {
@@ -89,56 +109,93 @@ function titleFrom(text) {
     }
     return trimmed.slice(0, TITLE_MAX);
 }
-function attachFailure(record, thrown, lastErr, canary) {
+function attachFailure(record, thrown, lastErr, canary, scrub) {
     if (!record.ok) {
         record.error = publicError(thrown ?? lastErr?.error);
         const inside = internalError(thrown) ?? lastErr?.errorInternal ?? lastErr?.error;
         if (inside) {
-            record.errorInternal = inside;
+            record.errorInternal = scrubStoredText(inside, scrub);
         }
     }
-    if (canary && JSON.stringify(record).includes(canary)) {
+    if (scrub.canary && canary && JSON.stringify(record).includes(canary)) {
         record.errorInternal = OMIT_CANARY;
     }
 }
+function eventsForTrace(events, include) {
+    if (include.guardrailDecisions) {
+        return events;
+    }
+    return events.filter((event) => event.type !== 'guardrail');
+}
+function asResolvedPolicy(value) {
+    if (value &&
+        typeof value === 'object' &&
+        'record' in value &&
+        typeof value.record === 'boolean') {
+        return value;
+    }
+    return resolveObservabilityPolicy(value);
+}
 async function buildRecord(args) {
-    const { req, events, started, model, bucket, thrown, gemini, canary, system, generation } = args;
-    const safe = args.sanitizedReq ?? requestForTrace(req);
+    const { req, events, started, model, keySlot, thrown, upstreamLog, canary, system, generation } = args;
+    const protocol = args.protocol;
+    const policy = asResolvedPolicy(args.observability);
+    const { include, scrub } = policy;
+    const traced = args.sanitizedReq ? { request: args.sanitizedReq } : requestForTrace(req);
+    const safe = traced.request;
     const input = safe.input ?? {};
-    const snapped = await Promise.all(events.map((event) => snapshotEvent(event)));
+    const traceEvents = eventsForTrace(events, include);
+    const snapped = await Promise.all(traceEvents.map((event) => snapshotEvent(event, include, scrub)));
     const lastErr = [...snapped].reverse().find((row) => row.type === 'error');
-    const done = completedInteraction(gemini);
-    const status = done?.status;
     const aborted = isAbortError(thrown);
-    const ok = !(thrown || lastErr) && status !== 'cancelled' && !aborted;
+    const stopKind = stopKindFromEvents(events);
+    const done = completedInteraction(upstreamLog);
+    const interactionStatus = done?.status;
+    const cancelled = aborted ||
+        stopKind === 'cancelled' ||
+        (protocol === 'geminiInteractions' && interactionStatus === 'cancelled');
+    const ok = !(thrown || lastErr) && !cancelled;
     const record = {
         v: TRACE_VERSION,
         id: crypto.randomUUID(),
         ts: started,
         ms: Date.now() - started,
         streamed: true,
-        cancelled: status === 'cancelled' || aborted,
+        cancelled,
         previousInteractionId: safe.previousInteractionId ?? null,
         store: safe.store ?? null,
         profile: safe.profile,
         input: {
-            text: input.text,
+            text: input.text !== undefined ? scrubStoredText(input.text, scrub) : undefined,
             role: input.role,
-            slots: input.slots,
+            slots: input.slots
+                ? Object.fromEntries(Object.entries(input.slots).map(([key, value]) => [key, scrubStoredText(value, scrub)]))
+                : undefined,
             attachments: await hashBlobs(input.attachments),
             voice: await hashBlobs(input.voice),
         },
         events: snapped,
         ok,
     };
-    const title = titleFrom(input.text);
+    const title = titleFrom(record.input.text);
     if (title) {
         record.title = title;
     }
-    await attachTape(record, { gemini, canary, system, generation });
-    attachUsage(record, gemini, done);
-    attachResolved(record, { safe, model, bucket, generation });
-    attachFailure(record, thrown, lastErr, canary);
+    const tapeCanary = scrub.canary ? canary : undefined;
+    await attachTape(record, {
+        upstream: upstreamLog,
+        canary: tapeCanary,
+        system,
+        generation,
+        protocol,
+        include,
+    });
+    attachUsage(record, upstreamLog, done, events, include);
+    attachResolved(record, { safe, model, keySlot, generation });
+    attachFailure(record, thrown, lastErr, canary, scrub);
+    if (traced.sanitizeError && !record.errorInternal) {
+        record.errorInternal = scrubStoredText(`request sanitize for trace failed: ${traced.sanitizeError}`, scrub);
+    }
     return record;
 }
 export { buildRecord };

package/esm/src/observability/trace-sink.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Trace sink contract.
+ *
+ * Type-only so hosts that consume kernel types under a non-Deno TypeScript
+ * program (browser bundles, Workers) never pull the JSONL file sink and its
+ * `Deno` calls into their type graph. Implementations live in `trace.ts`.
+ *
+ * @module
+ */
+import type { TraceRecord } from './trace-record.js';
+/** Minimal async destination for completed turn trace records. */
+export interface TraceSink {
+    write: (record: TraceRecord) => Promise<void>;
+    /**
+     * Optional host hook when `writeTrace` catches record-build or write failures.
+     * Must not throw; tracing never fails the turn.
+     */
+    onError?: (err: unknown) => void;
+}

package/esm/src/observability/trace-sink.js

@@ -0,0 +1,10 @@
+/**
+ * Trace sink contract.
+ *
+ * Type-only so hosts that consume kernel types under a non-Deno TypeScript
+ * program (browser bundles, Workers) never pull the JSONL file sink and its
+ * `Deno` calls into their type graph. Implementations live in `trace.ts`.
+ *
+ * @module
+ */
+export {};

package/esm/src/observability/trace-usage.d.ts

@@ -1,3 +1,10 @@
-declare function completedInteraction(gemini: unknown): Record<string, unknown> | undefined;
-declare function httpStatus(gemini: unknown): unknown;
-export { completedInteraction, httpStatus };
+import type { TurnEvent, TurnTokens } from '../kernel/types.js';
+declare function completedInteraction(upstream: unknown): Record<string, unknown> | undefined;
+/** Extract the terminal stop kind from the TurnEvent stream (protocol-agnostic). */
+declare function stopKindFromEvents(events: TurnEvent[]): string | undefined;
+/** Extract the last tokens snapshot from the TurnEvent stream. */
+declare function tokensFromEvents(events: TurnEvent[]): TurnTokens | undefined;
+/** Extract finish_reason from OpenAI-compat upstream tap rows. */
+declare function openAiFinishReason(upstream: unknown): string | undefined;
+declare function httpStatus(upstream: unknown): unknown;
+export { completedInteraction, httpStatus, openAiFinishReason, stopKindFromEvents, tokensFromEvents, };

package/esm/src/observability/trace-usage.js

@@ -2,31 +2,84 @@ import { asRecord } from '../kernel/engine/record.js';
 function eventName(row) {
     return String(row.event_type ?? row.eventType ?? '');
 }
-function completedInteraction(gemini) {
-    if (!Array.isArray(gemini)) {
-        return undefined;
+function upstreamRows(upstream) {
+    if (!Array.isArray(upstream)) {
+        return [];
     }
-    for (let i = gemini.length - 1; i >= 0; i -= 1) {
-        const row = asRecord(gemini[i]);
-        if (row) {
-            const name = eventName(row);
-            if (name === 'interaction.completed' || name === 'interaction.complete') {
-                return asRecord(row.interaction) ?? row;
-            }
+    return upstream
+        .map((item) => asRecord(item))
+        .filter((row) => row != null);
+}
+function lastUpstreamRow(upstream, pred) {
+    const rows = upstreamRows(upstream);
+    for (let i = rows.length - 1; i >= 0; i -= 1) {
+        if (pred(rows[i])) {
+            return rows[i];
+        }
+    }
+    return undefined;
+}
+function firstUpstreamRow(upstream, pred) {
+    for (const row of upstreamRows(upstream)) {
+        if (pred(row)) {
+            return row;
         }
     }
     return undefined;
 }
-function httpStatus(gemini) {
-    if (!Array.isArray(gemini)) {
+function completedInteraction(upstream) {
+    const row = lastUpstreamRow(upstream, (r) => {
+        const name = eventName(r);
+        return name === 'interaction.completed' || name === 'interaction.complete';
+    });
+    return row ? (asRecord(row.interaction) ?? row) : undefined;
+}
+/** Extract the terminal stop kind from the TurnEvent stream (protocol-agnostic). */
+function stopKindFromEvents(events) {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const ev = events[i];
+        if (ev?.type === 'done' && ev.stop) {
+            return ev.stop.kind;
+        }
+    }
+    return undefined;
+}
+/** Extract the last tokens snapshot from the TurnEvent stream. */
+function tokensFromEvents(events) {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const ev = events[i];
+        if (ev?.type === 'tokens' && ev.tokens) {
+            return ev.tokens;
+        }
+    }
+    return undefined;
+}
+/** Extract finish_reason from OpenAI-compat upstream tap rows. */
+function openAiFinishReason(upstream) {
+    const row = lastUpstreamRow(upstream, (r) => {
+        const choices = r.choices;
+        if (!Array.isArray(choices)) {
+            return false;
+        }
+        return choices.some((choice) => asRecord(choice)?.finish_reason != null);
+    });
+    if (!row) {
+        return undefined;
+    }
+    const choices = row.choices;
+    if (!Array.isArray(choices)) {
         return undefined;
     }
-    for (const item of gemini) {
-        const row = asRecord(item);
-        if (row && eventName(row) === 'http_response') {
-            return row.status;
+    for (const choice of choices) {
+        const c = asRecord(choice);
+        if (c?.finish_reason != null) {
+            return String(c.finish_reason);
         }
     }
     return undefined;
 }
-export { completedInteraction, httpStatus };
+function httpStatus(upstream) {
+    const row = firstUpstreamRow(upstream, (r) => eventName(r) === 'http_response');
+    return row?.status;
+}
+export { completedInteraction, httpStatus, openAiFinishReason, stopKindFromEvents, tokensFromEvents, };

package/esm/src/observability/trace.d.ts

@@ -1,16 +1,27 @@
 import type { TraceRecord } from './trace-record.js';
-/** Minimal async destination for completed turn trace records. */
-interface TraceSink {
-    write: (record: TraceRecord) => Promise<void>;
+import type { TraceSink } from './trace-sink.js';
+/** Options for daily rotating JSONL sinks. */
+interface JsonlSinkOptions {
+    retainForDays?: number;
+    rotateAfterMiB?: number;
+    now?: () => number;
 }
-/** Write a trace record without allowing trace failures to fail the turn. */
+/**
+ * Write a trace record without allowing trace failures to fail the turn.
+ * Build/write errors are forwarded to `sink.onError` when provided.
+ */
 declare function writeTrace(sink: TraceSink, record: Promise<TraceRecord>): Promise<void>;
 /** Trace sink that drops records. */
 declare function noopSink(): TraceSink;
 /** Trace sink that appends records to a caller-owned array. */
 declare function memorySink(into: TraceRecord[]): TraceSink;
-/** Trace sink that writes daily rotating JSONL files under a host-selected directory. */
-declare function jsonlSink(dir: string, now?: () => number): TraceSink;
+/**
+ * Trace sink that writes daily rotating JSONL files under a host-selected directory.
+ *
+ * @param dir - Absolute host-chosen directory
+ * @param optionsOrNow - Retention/rotate options, or a `now` clock (legacy)
+ */
+declare function jsonlSink(dir: string, optionsOrNow?: JsonlSinkOptions | (() => number)): TraceSink;
 /** Resolve a trace directory while refusing relative paths or paths inside the clone. */
 declare function resolveTraceDir(args: {
     dir?: string;
@@ -19,5 +30,5 @@ declare function resolveTraceDir(args: {
 }): string | undefined;
 /** Build a JSONL sink from a host-supplied directory or return a noop sink. */
 declare function sinkFromDir(dir?: string, fallbackDir?: string): TraceSink;
-export type { TraceSink };
+export type { JsonlSinkOptions };
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace };

package/esm/src/observability/trace.js

@@ -2,30 +2,37 @@
  * Trace sink primitives for THEORUM.
  *
  * Tracing is host-injected: the kernel can write to a provided sink, a memory
- * sink, a JSONL directory, or a noop sink. It does not read environment
- * variables or own a database destination.
+ * sink, a JSONL directory, or a noop sink. Profiles declare policy via
+ * `observability`; hosts register named destinations. THEORUM does not read
+ * environment variables or own a database destination.
  *
  * @module
  */
 import * as dntShim from "../../_dnt.shims.js";
-const RETAIN_DAYS = 14;
+const DEFAULT_RETAIN_DAYS = 14;
 const HOURS_PER_DAY = 24;
 const MIN_PER_HOUR = 60;
 const SEC_PER_MIN = 60;
 const MS_PER_SEC = 1000;
-const RETAIN_MS = RETAIN_DAYS * HOURS_PER_DAY * MIN_PER_HOUR * SEC_PER_MIN * MS_PER_SEC;
 const KIB = 1024;
 const MIB = KIB * KIB;
-const ROTATE_MIB = 32;
-const ROTATE_BYTES = ROTATE_MIB * MIB;
+const DEFAULT_ROTATE_MIB = 32;
 const FILE_DAY = /^turns-(\d{4}-\d{2}-\d{2})(?:-\d+)?\.jsonl$/;
-/** Write a trace record without allowing trace failures to fail the turn. */
+/**
+ * Write a trace record without allowing trace failures to fail the turn.
+ * Build/write errors are forwarded to `sink.onError` when provided.
+ */
 async function writeTrace(sink, record) {
     try {
         await sink.write(await record);
     }
-    catch {
-        // Tracing must not fail the turn.
+    catch (err) {
+        try {
+            sink.onError?.(err);
+        }
+        catch {
+            // Host onError must not fail the turn.
+        }
     }
 }
 /** Trace sink that drops records. */
@@ -47,8 +54,9 @@ function dayStamp(ms) {
 function fileDay(name) {
     return FILE_DAY.exec(name)?.[1];
 }
-async function pruneTraces(dir, now) {
-    const cutoff = now - RETAIN_MS;
+async function pruneTraces(dir, now, retainForDays) {
+    const retainMs = retainForDays * HOURS_PER_DAY * MIN_PER_HOUR * SEC_PER_MIN * MS_PER_SEC;
+    const cutoff = now - retainMs;
     for await (const entry of dntShim.Deno.readDir(dir)) {
         const day = fileDay(entry.name);
         if (day && Date.parse(`${day}T00:00:00.000Z`) < cutoff) {
@@ -56,12 +64,12 @@ async function pruneTraces(dir, now) {
         }
     }
 }
-async function pickFile(dir, now) {
+async function pickFile(dir, now, rotateBytes) {
     const day = dayStamp(now);
     const base = `${dir}/turns-${day}.jsonl`;
     try {
         const info = await dntShim.Deno.stat(base);
-        if ((info.size ?? 0) < ROTATE_BYTES) {
+        if ((info.size ?? 0) < rotateBytes) {
             return base;
         }
     }
@@ -70,14 +78,23 @@ async function pickFile(dir, now) {
     }
     return `${dir}/turns-${day}-${now}.jsonl`;
 }
-/** Trace sink that writes daily rotating JSONL files under a host-selected directory. */
-function jsonlSink(dir, now = Date.now) {
+/**
+ * Trace sink that writes daily rotating JSONL files under a host-selected directory.
+ *
+ * @param dir - Absolute host-chosen directory
+ * @param optionsOrNow - Retention/rotate options, or a `now` clock (legacy)
+ */
+function jsonlSink(dir, optionsOrNow) {
+    const options = typeof optionsOrNow === 'function' ? { now: optionsOrNow } : (optionsOrNow ?? {});
+    const now = options.now ?? Date.now;
+    const retainForDays = options.retainForDays ?? DEFAULT_RETAIN_DAYS;
+    const rotateBytes = (options.rotateAfterMiB ?? DEFAULT_ROTATE_MIB) * MIB;
     return {
         write: async (record) => {
             const at = now();
             await dntShim.Deno.mkdir(dir, { recursive: true });
-            await pruneTraces(dir, at);
-            const path = await pickFile(dir, at);
+            await pruneTraces(dir, at, retainForDays);
+            const path = await pickFile(dir, at, rotateBytes);
             await dntShim.Deno.writeTextFile(path, `${JSON.stringify(record)}\n`, { append: true });
         },
     };

package/esm/src/observability/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Profile observability vocabulary — destination, scrub, and include policy.
+ *
+ * This module is the single source of truth for observability profile types. It
+ * must not import from `src/kernel/`: the kernel type-imports
+ * `ProfileObservabilitySpec` for `ProfileCommon.observability`, and that edge
+ * stays one-directional.
+ *
+ * @module
+ */
+import type { TraceSink } from './trace-sink.js';
+/** Which payloads land in each TraceRecord. Omitted keys use resolved defaults. */
+export interface TraceIncludeSpec {
+    /** Scrubbed provider HTTP/SSE rows. Default: true. */
+    upstreamLog?: boolean;
+    /** Scrubbed outbound request body. Default: false. */
+    outboundWire?: boolean;
+    /** Verbatim provider step JSON (`events[].evidence.raw`). Default: false. */
+    evidenceRaw?: boolean;
+    /** Token / usage fields. Default: true. */
+    usage?: boolean;
+    /**
+     * Persist `{ type: 'guardrail' }` decisions into the TraceRecord. Default: true.
+     */
+    guardrailDecisions?: boolean;
+    /**
+     * Keep `GuardrailHit.match` (exact matched substring, capped) on guardrail
+     * events in the live stream and TraceRecord. Default: false — debugging only;
+     * treat like server logs when enabled.
+     */
+    guardrailMatchPreview?: boolean;
+}
+/**
+ * Scrubbing of what is written — independent of turn-path `profile.guardrails`.
+ * Defaults are safe for a host-confidential store.
+ */
+export interface TraceScrubSpec {
+    /** Strip credentials / PII spans in stored text. Default: true. */
+    sensitive?: boolean;
+    /** Strip injection spans in the stored request copy. Default: true. */
+    injection?: boolean;
+    /** Never persist the canary token. Default: true. */
+    canary?: boolean;
+}
+/**
+ * Profile observability — what to record, and where.
+ *
+ * Omit the whole block → no tracing (noop). Prefer `writeTo: '<registered-id>'`
+ * in shared profiles; pass a TraceSink only for tests / custom exporters.
+ */
+export interface ProfileObservabilitySpec {
+    /**
+     * Destination for completed turn records.
+     *
+     * - `false` — explicitly off
+     * - `string` — host-registered destination id (`registerTraceDestination`)
+     * - `TraceSink` — inline writer (tests, OTEL bridge, etc.)
+     *
+     * `runTurn(..., sink)` still overrides this for one call.
+     */
+    writeTo?: false | string | TraceSink;
+    /**
+     * Fraction of turns to record, 0–1 inclusive.
+     * Omitted → 1 (every turn). `0` means record none.
+     */
+    sampleRate?: number;
+    /** Which payloads land in each TraceRecord. */
+    include?: TraceIncludeSpec;
+    /**
+     * Scrubbing of stored records — independent of turn-path guardrails.
+     * Defaults stay on even when `guardrails.redactSensitive` is false.
+     */
+    scrub?: TraceScrubSpec;
+    /** JSONL retention days when the resolved destination is JSONL. Default: 14. */
+    retainForDays?: number;
+    /** JSONL rotate threshold in MiB when the resolved destination is JSONL. Default: 32. */
+    rotateAfterMiB?: number;
+    /**
+     * Called when record build or destination write fails.
+     * Must not throw; tracing never fails the turn.
+     */
+    onWriteError?: (err: unknown) => void;
+}
+/** Resolved include flags after defaults. */
+export interface ResolvedTraceInclude {
+    upstreamLog: boolean;
+    outboundWire: boolean;
+    evidenceRaw: boolean;
+    usage: boolean;
+    guardrailDecisions: boolean;
+    guardrailMatchPreview: boolean;
+}
+/** Resolved scrub flags after defaults. */
+export interface ResolvedTraceScrub {
+    sensitive: boolean;
+    injection: boolean;
+    canary: boolean;
+}
+/**
+ * Observability policy with defaults applied.
+ * Every path resolves through `resolveObservabilityPolicy`.
+ */
+export interface ResolvedObservabilityPolicy {
+    /** False when omitted, `writeTo: false`, or sampleRate drops the turn. */
+    record: boolean;
+    writeTo: false | string | TraceSink | undefined;
+    sampleRate: number;
+    include: ResolvedTraceInclude;
+    scrub: ResolvedTraceScrub;
+    retainForDays: number;
+    rotateAfterMiB: number;
+    onWriteError?: (err: unknown) => void;
+}

package/esm/src/observability/types.js

@@ -0,0 +1,11 @@
+/**
+ * Profile observability vocabulary — destination, scrub, and include policy.
+ *
+ * This module is the single source of truth for observability profile types. It
+ * must not import from `src/kernel/`: the kernel type-imports
+ * `ProfileObservabilitySpec` for `ProfileCommon.observability`, and that edge
+ * stays one-directional.
+ *
+ * @module
+ */
+export {};

package/esm/src/presets/google/speech-voices.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Google Gemini TTS voice names for `speech.voice`.
+ *
+ * Standalone preset vocabulary — no kernel registry imports so docs UIs can
+ * import this file without pulling provider wiring.
+ *
+ * @module
+ */
+/** Common Gemini TTS voice names. */
+export declare const GOOGLE_SPEECH_VOICES: readonly ["Zephyr", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Aoede", "Callirrhoe", "Autonoe", "Enceladus", "Iapetus", "Umbriel", "Algieba", "Despina", "Erinome", "Algenib", "Rasalgethi", "Laomedeia", "Achernar", "Alnilam", "Schedar", "Gacrux", "Pulcherrima", "Achird", "Zubenelgenubi", "Vindemiatrix", "Sadachbia", "Sadaltager", "Sulafat"];
+export type GoogleSpeechVoice = (typeof GOOGLE_SPEECH_VOICES)[number];