theorum 1.0.0 → 1.1.3

package/esm/src/observability/destinations.js

@@ -0,0 +1,67 @@
+/**
+ * Host-registered trace destinations for profile `observability.writeTo` ids.
+ *
+ * THEORUM does not invent filesystem roots. Hosts register a named destination
+ * once per process; profiles reference it by id.
+ *
+ * @module
+ */
+import { TheorumError } from '../guardrails/error.js';
+const destinations = new Map();
+/** Build a JSONL destination descriptor for `registerTraceDestination`. */
+function jsonlDestination(dir) {
+    const trimmed = dir.trim();
+    if (!trimmed) {
+        throw new TheorumError('jsonlDestination requires a non-empty directory');
+    }
+    return { kind: 'jsonl', dir: trimmed };
+}
+function isJsonlTraceDestination(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'kind' in value &&
+        value.kind === 'jsonl' &&
+        typeof value.dir === 'string');
+}
+function isTraceSink(value) {
+    return (typeof value === 'object' && value !== null && typeof value.write === 'function');
+}
+/** Register a named destination for profile `observability.writeTo`. */
+function registerTraceDestination(id, destination) {
+    const key = id.trim();
+    if (!key) {
+        throw new TheorumError('registerTraceDestination requires a non-empty id');
+    }
+    if (isJsonlTraceDestination(destination)) {
+        if (!destination.dir.trim()) {
+            throw new TheorumError(`Trace destination '${key}' jsonl dir must be non-empty`);
+        }
+        destinations.set(key, { kind: 'jsonl', dir: destination.dir.trim() });
+        return;
+    }
+    if (!isTraceSink(destination)) {
+        throw new TheorumError(`Trace destination '${key}' must be a TraceSink or jsonl destination`);
+    }
+    destinations.set(key, destination);
+}
+/** Look up a registered destination; undefined when missing. */
+function getTraceDestination(id) {
+    return destinations.get(id);
+}
+/** Require a registered destination or throw. */
+function requireTraceDestination(id) {
+    const found = getTraceDestination(id);
+    if (!found) {
+        throw new TheorumError(`Trace destination '${id}' is not registered`);
+    }
+    return found;
+}
+/** List registered destination ids (stable sort). */
+function listTraceDestinationIds() {
+    return [...destinations.keys()].sort();
+}
+/** Clear the destination registry (tests). */
+function clearTraceDestinations() {
+    destinations.clear();
+}
+export { clearTraceDestinations, getTraceDestination, isJsonlTraceDestination, isTraceSink, jsonlDestination, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, };

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

@@ -1,12 +1,19 @@
 /**
- * Trace sinks and trace record helpers for THEORUM.
+ * Trace sinks, destination registry, and profile observability policy.
  *
  * THEORUM does not own a database or environment variable. Host applications
- * choose a sink and pass it into `runTurn`, or use the noop sink for tests.
+ * register named destinations, declare `profile.observability`, and/or pass a
+ * sink into `runTurn`.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
-export type { TraceSink } from './trace.js';
+export type { JsonlTraceDestination, TraceDestination, } from './destinations.js';
+export { clearTraceDestinations, getTraceDestination, isJsonlTraceDestination, isTraceSink, jsonlDestination, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, } from './destinations.js';
+export { resolveTraceWriter } from './policy.js';
+export { resolveObservabilityPolicy } from './resolve-policy.js';
+export type { JsonlSinkOptions } from './trace.js';
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './trace.js';
 export type { TraceRecord } from './trace-record.js';
+export type { TraceSink } from './trace-sink.js';
+export type { ProfileObservabilitySpec, ResolvedObservabilityPolicy, ResolvedTraceInclude, ResolvedTraceScrub, TraceIncludeSpec, TraceScrubSpec, } from './types.js';

package/esm/src/observability/mod.js

@@ -1,10 +1,14 @@
 /**
- * Trace sinks and trace record helpers for THEORUM.
+ * Trace sinks, destination registry, and profile observability policy.
  *
  * THEORUM does not own a database or environment variable. Host applications
- * choose a sink and pass it into `runTurn`, or use the noop sink for tests.
+ * register named destinations, declare `profile.observability`, and/or pass a
+ * sink into `runTurn`.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export { clearTraceDestinations, getTraceDestination, isJsonlTraceDestination, isTraceSink, jsonlDestination, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, } from './destinations.js';
+export { resolveTraceWriter } from './policy.js';
+export { resolveObservabilityPolicy } from './resolve-policy.js';
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './trace.js';

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

@@ -0,0 +1,27 @@
+/**
+ * Trace writer resolution — a resolved observability policy becomes a sink.
+ *
+ * Policy defaults live in `resolve-policy.ts` (pure); this module owns the
+ * writer precedence and needs the sink implementations.
+ *
+ * @module
+ */
+import type { TraceSink } from './trace-sink.js';
+import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
+/**
+ * Resolve the TraceSink for one turn.
+ *
+ * Precedence: explicit `override` (runTurn third arg) → profile `writeTo` → noop.
+ * An explicit override always records (sampleRate does not apply) so tests and
+ * one-off capture are deterministic.
+ */
+declare function resolveTraceWriter(args: {
+    override?: TraceSink;
+    observability?: ProfileObservabilitySpec;
+    /** Injectable for deterministic sampleRate tests. */
+    random?: () => number;
+}): {
+    sink: TraceSink;
+    policy: ResolvedObservabilityPolicy;
+};
+export { resolveTraceWriter };

package/esm/src/observability/policy.js

@@ -0,0 +1,80 @@
+/**
+ * Trace writer resolution — a resolved observability policy becomes a sink.
+ *
+ * Policy defaults live in `resolve-policy.ts` (pure); this module owns the
+ * writer precedence and needs the sink implementations.
+ *
+ * @module
+ */
+import { TheorumError } from '../guardrails/error.js';
+import { isJsonlTraceDestination, isTraceSink, requireTraceDestination } from './destinations.js';
+import { resolveObservabilityPolicy } from './resolve-policy.js';
+import { jsonlSink, noopSink } from './trace.js';
+function bindOnWriteError(sink, onWriteError) {
+    if (!onWriteError && !sink.onError) {
+        return sink;
+    }
+    return {
+        write: (record) => sink.write(record),
+        onError: sink.onError ?? onWriteError,
+    };
+}
+function withSampleRate(sink, sampleRate, random) {
+    if (sampleRate >= 1) {
+        return sink;
+    }
+    if (sampleRate <= 0) {
+        return noopSink();
+    }
+    return {
+        write: async (record) => {
+            if (random() < sampleRate) {
+                await sink.write(record);
+            }
+        },
+        onError: sink.onError,
+    };
+}
+function sinkFromWriteTo(writeTo, policy) {
+    if (writeTo === undefined || writeTo === false) {
+        return noopSink();
+    }
+    if (typeof writeTo !== 'string') {
+        return bindOnWriteError(writeTo, policy.onWriteError);
+    }
+    const destination = requireTraceDestination(writeTo);
+    if (isJsonlTraceDestination(destination)) {
+        return bindOnWriteError(jsonlSink(destination.dir, {
+            retainForDays: policy.retainForDays,
+            rotateAfterMiB: policy.rotateAfterMiB,
+        }), policy.onWriteError);
+    }
+    if (!isTraceSink(destination)) {
+        throw new TheorumError(`Trace destination '${writeTo}' is not a usable writer`);
+    }
+    return bindOnWriteError(destination, policy.onWriteError);
+}
+/**
+ * Resolve the TraceSink for one turn.
+ *
+ * Precedence: explicit `override` (runTurn third arg) → profile `writeTo` → noop.
+ * An explicit override always records (sampleRate does not apply) so tests and
+ * one-off capture are deterministic.
+ */
+function resolveTraceWriter(args) {
+    const policy = resolveObservabilityPolicy(args.observability);
+    if (args.override) {
+        return {
+            policy,
+            sink: bindOnWriteError(args.override, policy.onWriteError),
+        };
+    }
+    if (!policy.record) {
+        return { policy, sink: noopSink() };
+    }
+    return {
+        policy,
+        sink: withSampleRate(sinkFromWriteTo(policy.writeTo, policy), policy.sampleRate, args.random ?? Math.random),
+    };
+}
+export { resolveTraceWriter };

package/esm/src/observability/resolve-policy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Observability policy resolution — profile switches become resolved defaults.
+ *
+ * Pure: no sinks, no file system. `policy.ts` builds the writer on top of this
+ * so type consumers of the kernel never pull the JSONL sink into their graph.
+ *
+ * @module
+ */
+import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
+/**
+ * Apply defaults to a profile's observability block.
+ *
+ * Omitted block → record false (noop). Explicit `writeTo: false` → record false.
+ * A writeTo target with sampleRate 0 still resolves record false at write time.
+ */
+export declare function resolveObservabilityPolicy(spec: ProfileObservabilitySpec | undefined): ResolvedObservabilityPolicy;

package/esm/src/observability/resolve-policy.js

@@ -0,0 +1,64 @@
+/**
+ * Observability policy resolution — profile switches become resolved defaults.
+ *
+ * Pure: no sinks, no file system. `policy.ts` builds the writer on top of this
+ * so type consumers of the kernel never pull the JSONL sink into their graph.
+ *
+ * @module
+ */
+import { TheorumError } from '../guardrails/error.js';
+const DEFAULT_RETAIN_DAYS = 14;
+const DEFAULT_ROTATE_MIB = 32;
+function resolveInclude(spec) {
+    // When no observability block is authored, preserve historical buildRecord
+    // behavior (wire + evidence included). Authored blocks default those off.
+    const authored = spec !== undefined;
+    return {
+        upstreamLog: spec?.include?.upstreamLog ?? true,
+        outboundWire: spec?.include?.outboundWire ?? !authored,
+        evidenceRaw: spec?.include?.evidenceRaw ?? !authored,
+        usage: spec?.include?.usage ?? true,
+        guardrailDecisions: spec?.include?.guardrailDecisions ?? true,
+        guardrailMatchPreview: spec?.include?.guardrailMatchPreview ?? false,
+    };
+}
+function resolveScrub(spec) {
+    return {
+        sensitive: spec?.scrub?.sensitive ?? true,
+        injection: spec?.scrub?.injection ?? true,
+        canary: spec?.scrub?.canary ?? true,
+    };
+}
+function clampSampleRate(value) {
+    if (value === undefined) {
+        return 1;
+    }
+    if (!Number.isFinite(value)) {
+        throw new TheorumError('observability.sampleRate must be a finite number');
+    }
+    if (value < 0 || value > 1) {
+        throw new TheorumError('observability.sampleRate must be between 0 and 1 inclusive');
+    }
+    return value;
+}
+/**
+ * Apply defaults to a profile's observability block.
+ *
+ * Omitted block → record false (noop). Explicit `writeTo: false` → record false.
+ * A writeTo target with sampleRate 0 still resolves record false at write time.
+ */
+export function resolveObservabilityPolicy(spec) {
+    const writeTo = spec?.writeTo;
+    const sampleRate = clampSampleRate(spec?.sampleRate);
+    const record = spec !== undefined && writeTo !== false && writeTo !== undefined;
+    return {
+        record,
+        writeTo,
+        sampleRate,
+        include: resolveInclude(spec),
+        scrub: resolveScrub(spec),
+        retainForDays: spec?.retainForDays ?? DEFAULT_RETAIN_DAYS,
+        rotateAfterMiB: spec?.rotateAfterMiB ?? DEFAULT_ROTATE_MIB,
+        onWriteError: spec?.onWriteError,
+    };
+}

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

@@ -1,6 +1,7 @@
 import type { Protocol } from '../kernel/schema.js';
 import type { ResolvedGeneration, TurnEvent, TurnRequest } from '../kernel/types.js';
 import type { TraceRecord } from './trace-record.js';
+import type { ResolvedTraceInclude } from './types.js';
 declare function attachResolved(record: TraceRecord, args: {
     safe: TurnRequest;
     model?: string;
@@ -13,6 +14,7 @@ declare function attachTape(record: TraceRecord, args: {
     system?: string;
     generation?: ResolvedGeneration;
     protocol?: Protocol;
+    include: ResolvedTraceInclude;
 }): Promise<void>;
-declare function attachUsage(record: TraceRecord, upstream: unknown, done: Record<string, unknown> | undefined, events?: TurnEvent[]): void;
+declare function attachUsage(record: TraceRecord, upstream: unknown, done: Record<string, unknown> | undefined, events: TurnEvent[] | undefined, include: ResolvedTraceInclude): void;
 export { attachResolved, attachTape, attachUsage };

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

@@ -6,11 +6,11 @@ function attachResolved(record, args) {
     if (safe.projectId) {
         record.projectId = safe.projectId;
     }
-    if (safe.select) {
-        record.select = safe.select;
+    if (safe.model) {
+        record.modelSelect = safe.model;
     }
-    if (safe.thinking !== undefined) {
-        record.thinking = safe.thinking;
+    if (safe.effort) {
+        record.effort = safe.effort;
     }
     if (safe.metadata) {
         record.metadata = safe.metadata;
@@ -39,11 +39,14 @@ function attachResolved(record, args) {
     }
 }
 async function attachTape(record, args) {
-    const { upstream, canary, system, generation, protocol } = args;
-    if (upstream !== undefined) {
+    const { upstream, canary, system, generation, protocol, include } = args;
+    if (include.upstreamLog && upstream !== undefined) {
         record.upstreamLog = await tapeUpstream(upstream, canary ?? '');
     }
-    if (generation && system !== undefined && protocol === 'geminiInteractions') {
+    if (include.outboundWire &&
+        generation &&
+        system !== undefined &&
+        protocol === 'geminiInteractions') {
         const { toInteractionsBody } = await import('../providers/google/interactions/framing.js');
         record.wire = await tapeUpstream(toInteractionsBody(providerCompleteRequest(generation, system)), canary ?? '');
     }
@@ -74,8 +77,12 @@ function attachUpstreamSummary(record, upstream, done) {
         serviceTier: done?.service_tier ?? done?.serviceTier,
     };
 }
-function attachUsage(record, upstream, done, events) {
-    attachUsageTokens(record, done, events);
-    attachUpstreamSummary(record, upstream, done);
+function attachUsage(record, upstream, done, events, include) {
+    if (include.usage) {
+        attachUsageTokens(record, done, events);
+    }
+    if (include.upstreamLog) {
+        attachUpstreamSummary(record, upstream, done);
+    }
 }
 export { attachResolved, attachTape, attachUsage };

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

@@ -8,10 +8,14 @@
  */
 import type { Protocol } from '../kernel/schema.js';
 import type { ResolvedGeneration, TurnEvent, TurnRequest } from '../kernel/types.js';
+import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
 /** Hash-only image reference stored in trace records. */
 export interface TraceImage {
     mimeType: string;
-    sha256: string;
+    /** Content hash for inline bytes; absent for a provider file reference. */
+    sha256?: string;
+    /** Provider file reference when the attachment was supplied by uri. */
+    uri?: string;
 }
 /** Trace-safe copy of a public turn event. */
 export interface TraceEvent {
@@ -30,6 +34,8 @@ export interface TraceEvent {
     media?: TraceImage;
     grounding?: TurnEvent['grounding'];
     evidence?: TurnEvent['evidence'];
+    /** Guardrail decision — rule identity and offsets, never matched content. */
+    guardrail?: TurnEvent['guardrail'];
     error?: string;
     errorInternal?: string;
 }
@@ -46,8 +52,8 @@ interface TraceRecord {
     profile: string;
     title?: string;
     projectId?: string;
-    select?: string;
-    thinking?: boolean;
+    modelSelect?: string;
+    effort?: string;
     metadata?: Record<string, unknown>;
     model?: {
         id: string;
@@ -55,7 +61,7 @@ interface TraceRecord {
     };
     keySlot?: string;
     generation?: {
-        thinking: string;
+        thinking?: string;
         summaries?: string;
         temperature?: number;
         maxOutputTokens?: number;
@@ -111,6 +117,8 @@ declare function buildRecord(args: {
     generation?: ResolvedGeneration;
     protocol?: Protocol;
     sanitizedReq?: TurnRequest;
+    /** Profile observability — omit for defaults (safe scrub, standard include). */
+    observability?: ProfileObservabilitySpec | ResolvedObservabilityPolicy;
 }): Promise<TraceRecord>;
 export type { TraceRecord };
 export { buildRecord };

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

@@ -8,8 +8,10 @@
  */
 import { OMIT_CANARY } from '../guardrails/canary.js';
 import { isAbortError, publicError } from '../guardrails/error.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, stopKindFromEvents } from './trace-usage.js';
 const TRACE_VERSION = 2;
@@ -18,21 +20,32 @@ 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;
@@ -66,9 +79,12 @@ 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) {
@@ -93,25 +109,43 @@ 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, 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 aborted = isAbortError(thrown);
     const stopKind = stopKindFromEvents(events);
@@ -132,25 +166,35 @@ async function buildRecord(args) {
         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, { upstream: upstreamLog, canary, system, generation, protocol });
-    attachUsage(record, upstreamLog, done, events);
+    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);
+    attachFailure(record, thrown, lastErr, canary, scrub);
     if (traced.sanitizeError && !record.errorInternal) {
-        record.errorInternal = sanitizeText(`request sanitize for trace failed: ${traced.sanitizeError}`);
+        record.errorInternal = scrubStoredText(`request sanitize for trace failed: ${traced.sanitizeError}`, scrub);
     }
     return record;
 }

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.d.ts

@@ -1,12 +1,10 @@
 import type { TraceRecord } from './trace-record.js';
-/** Minimal async destination for completed turn trace records. */
-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;
+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.
@@ -17,8 +15,13 @@ declare function writeTrace(sink: TraceSink, record: Promise<TraceRecord>): Prom
 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;
@@ -27,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 };