theorum 0.1.15 → 1.1.3

package/esm/src/kernel/util/find-last.d.ts

@@ -0,0 +1,2 @@
+/** ES2022-safe replacement for `Array.prototype.findLast`. */
+export declare function findLast<T>(items: readonly T[], predicate: (item: T) => boolean): T | undefined;

package/esm/src/kernel/util/find-last.js

@@ -0,0 +1,10 @@
+/** ES2022-safe replacement for `Array.prototype.findLast`. */
+export function findLast(items, predicate) {
+    for (let i = items.length - 1; i >= 0; i -= 1) {
+        const item = items[i];
+        if (item !== undefined && predicate(item)) {
+            return item;
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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 type { TraceSink } from './trace-sink.js';
+/** JSONL directory destination — retention comes from profile policy at resolve time. */
+export interface JsonlTraceDestination {
+    readonly kind: 'jsonl';
+    readonly dir: string;
+}
+/** Something a host may register under a destination id. */
+export type TraceDestination = TraceSink | JsonlTraceDestination;
+/** Build a JSONL destination descriptor for `registerTraceDestination`. */
+declare function jsonlDestination(dir: string): JsonlTraceDestination;
+declare function isJsonlTraceDestination(value: TraceDestination): value is JsonlTraceDestination;
+declare function isTraceSink(value: TraceDestination): value is TraceSink;
+/** Register a named destination for profile `observability.writeTo`. */
+declare function registerTraceDestination(id: string, destination: TraceDestination): void;
+/** Look up a registered destination; undefined when missing. */
+declare function getTraceDestination(id: string): TraceDestination | undefined;
+/** Require a registered destination or throw. */
+declare function requireTraceDestination(id: string): TraceDestination;
+/** List registered destination ids (stable sort). */
+declare function listTraceDestinationIds(): string[];
+/** Clear the destination registry (tests). */
+declare function clearTraceDestinations(): void;
+export { clearTraceDestinations, getTraceDestination, isJsonlTraceDestination, isTraceSink, jsonlDestination, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, };

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,16 +1,20 @@
-import type { ResolvedGeneration, TurnRequest } from '../kernel/types.js';
+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;
-    bucket?: string;
+    keySlot?: string;
     generation?: ResolvedGeneration;
 }): void;
 declare function attachTape(record: TraceRecord, args: {
-    gemini?: unknown;
+    upstream?: unknown;
     canary?: string;
     system?: string;
     generation?: ResolvedGeneration;
+    protocol?: Protocol;
+    include: ResolvedTraceInclude;
 }): Promise<void>;
-declare function attachUsage(record: TraceRecord, gemini: unknown, done: Record<string, unknown> | undefined): 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

@@ -1,20 +1,16 @@
 import { providerCompleteRequest } from '../kernel/registry/provider-request.js';
-import { tapeGemini } from '../providers/gemini-tape.js';
-import { toInteractionsBody } from '../providers/interactions.js';
-import { httpStatus } from './trace-usage.js';
+import { tapeUpstream } from '../providers/shared/upstream-tape.js';
+import { httpStatus, openAiFinishReason, tokensFromEvents } from './trace-usage.js';
 function attachResolved(record, args) {
-    const { safe, model, bucket, generation } = args;
+    const { safe, model, keySlot, generation } = 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.tools) {
-        record.tools = safe.tools;
+    if (safe.effort) {
+        record.effort = safe.effort;
     }
     if (safe.metadata) {
         record.metadata = safe.metadata;
@@ -25,43 +21,68 @@ function attachResolved(record, args) {
             apiId: generation?.apiId ?? model,
         };
     }
-    if (bucket) {
-        record.bucket = bucket;
+    if (keySlot) {
+        record.keySlot = keySlot;
     }
     if (generation) {
-        record.generation = {
+        const traceGeneration = {
             thinking: generation.thinking,
             summaries: generation.summaries,
             temperature: generation.temperature,
             maxOutputTokens: generation.maxOutputTokens,
             builtins: generation.builtins,
-            custom: generation.custom,
+            visibleTools: generation.tools.visible,
             structured: generation.structured,
             image: generation.image,
         };
+        record.generation = traceGeneration;
     }
 }
 async function attachTape(record, args) {
-    const { gemini, canary, system, generation } = args;
-    if (gemini !== undefined) {
-        record.gemini = await tapeGemini(gemini, canary ?? '');
+    const { upstream, canary, system, generation, protocol, include } = args;
+    if (include.upstreamLog && upstream !== undefined) {
+        record.upstreamLog = await tapeUpstream(upstream, canary ?? '');
     }
-    if (generation && system !== undefined) {
-        record.wire = await tapeGemini(toInteractionsBody(providerCompleteRequest(generation, system)), canary ?? '');
+    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 ?? '');
     }
 }
-function attachUsage(record, gemini, done) {
+function attachUsageTokens(record, done, events) {
     if (done?.usage !== undefined) {
         record.usage = done.usage;
+        return;
     }
-    const upStatus = httpStatus(gemini);
-    if (upStatus !== undefined || done) {
-        record.upstream = {
-            status: upStatus,
-            id: done?.id,
-            finish: done?.status,
-            serviceTier: done?.service_tier ?? done?.serviceTier,
-        };
+    if (!events) {
+        return;
+    }
+    const tokens = tokensFromEvents(events);
+    if (tokens) {
+        record.usage = tokens;
+    }
+}
+function attachUpstreamSummary(record, upstream, done) {
+    const upStatus = httpStatus(upstream);
+    const finishReason = openAiFinishReason(upstream);
+    if (upStatus === undefined && !done && finishReason === undefined) {
+        return;
+    }
+    record.upstream = {
+        status: upStatus,
+        id: done?.id,
+        finish: done?.status ?? finishReason,
+        serviceTier: done?.service_tier ?? done?.serviceTier,
+    };
+}
+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

@@ -6,11 +6,16 @@
  *
  * @module
  */
+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 {
@@ -29,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;
 }
@@ -45,22 +52,21 @@ interface TraceRecord {
     profile: string;
     title?: string;
     projectId?: string;
-    select?: string;
-    thinking?: boolean;
-    tools?: TurnRequest['tools'];
+    modelSelect?: string;
+    effort?: string;
     metadata?: Record<string, unknown>;
     model?: {
         id: string;
         apiId: string;
     };
-    bucket?: string;
+    keySlot?: string;
     generation?: {
-        thinking: string;
-        summaries: string;
-        temperature: number;
-        maxOutputTokens: number;
+        thinking?: string;
+        summaries?: string;
+        temperature?: number;
+        maxOutputTokens?: number;
         builtins: string[];
-        custom: string[];
+        visibleTools: string[];
         structured: string | null;
         image: unknown;
     };
@@ -75,7 +81,8 @@ interface TraceRecord {
     };
     wire?: unknown;
     events: TraceEvent[];
-    gemini?: unknown;
+    /** Raw upstream tap rows (HTTP, SSE, provider events). */
+    upstreamLog?: unknown;
     usage?: unknown;
     upstream?: {
         status?: unknown;
@@ -102,13 +109,16 @@ declare function buildRecord(args: {
     events: TurnEvent[];
     started: number;
     model?: string;
-    bucket?: string;
+    keySlot?: string;
     thrown?: unknown;
-    gemini?: unknown;
+    upstreamLog?: unknown;
     canary?: string;
     system?: string;
     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 };