@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/observability/openinference.js

@@ -0,0 +1,205 @@
+/**
+ * OpenInference attributes for Phoenix, whose message views, reasoning tokens, and cost read only
+ * OpenInference names; they are copied beside the semconv names so `toOtlpJson` stays neutral.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { isRecord } from '../kernel/util/record.js';
+import { inlineContent } from './trace-record.js';
+const MODEL_CALLS = new Set(['chat', 'generate_content']);
+const AGENT_CALLS = new Set(['invoke_agent']);
+/** A decision (`theorem.decision.*`): one model call over JSON state, with no messages. */
+const DECISION = 'decide';
+/** Eval spans carry no semconv operation: a trial grades one turn, a run chains the trials. */
+const EVAL_KINDS = {
+    'theorem.eval.trial': 'EVALUATOR',
+    'theorem.eval.run': 'CHAIN',
+};
+/** Model calls only: a viewer sums usage across a trace, and an agent span's is already a sum. */
+function openInferenceUsage(attributes) {
+    const reasoning = attributes['gen_ai.usage.reasoning.output_tokens'];
+    const cost = attributes['theorem.usage.cost_usd'];
+    return {
+        ...(typeof reasoning === 'number'
+            ? { 'llm.token_count.completion_details.reasoning': reasoning }
+            : {}),
+        // why: A partial cost would read as the call's total; it keeps only its theorem.* name.
+        ...(typeof cost === 'number' && attributes['theorem.usage.cost_partial'] !== true
+            ? { 'llm.cost.total': cost }
+            : {}),
+    };
+}
+function messagesOf(record, value) {
+    const inlined = inlineContent(record, value);
+    if (!Array.isArray(inlined))
+        return [];
+    return inlined.flatMap((message) => {
+        if (!isRecord(message) || typeof message.role !== 'string')
+            return [];
+        const parts = Array.isArray(message.parts) ? message.parts.filter(isRecord) : [];
+        return [{ role: message.role, parts: parts }];
+    });
+}
+function partText(part) {
+    if (part.type === 'text' && typeof part.content === 'string')
+        return part.content;
+    if (part.type === 'structured' && part.content !== undefined)
+        return JSON.stringify(part.content);
+    if (part.type === 'tool_call' || part.type === 'tool_call_response')
+        return undefined;
+    if (typeof part.modality === 'string')
+        return `[${part.modality}]`;
+    return undefined;
+}
+/** A text part that repeats the structured part's JSON is shown once, as the JSON. */
+function repeatsStructured(part, structured) {
+    if (structured === undefined || part.type !== 'text' || typeof part.content !== 'string') {
+        return false;
+    }
+    try {
+        return JSON.stringify(JSON.parse(part.content)) === JSON.stringify(structured.content);
+    }
+    catch {
+        return false;
+    }
+}
+function messageText(message) {
+    const structured = message.parts.find((part) => part.type === 'structured');
+    return message.parts
+        .filter((part) => !repeatsStructured(part, structured))
+        .flatMap((part) => partText(part) ?? [])
+        .join('\n');
+}
+function messageAttributes(prefix, message) {
+    const out = { [`${prefix}.message.role`]: message.role };
+    const text = messageText(message);
+    if (text !== '')
+        out[`${prefix}.message.content`] = text;
+    let calls = 0;
+    for (const part of message.parts) {
+        if (part.type === 'tool_call') {
+            const call = `${prefix}.message.tool_calls.${calls}.tool_call`;
+            calls += 1;
+            if (typeof part.id === 'string')
+                out[`${call}.id`] = part.id;
+            if (typeof part.name === 'string')
+                out[`${call}.function.name`] = part.name;
+            if (typeof part.arguments === 'string')
+                out[`${call}.function.arguments`] = part.arguments;
+        }
+        else if (part.type === 'tool_call_response') {
+            if (typeof part.id === 'string')
+                out[`${prefix}.message.tool_call_id`] = part.id;
+            if (typeof part.response === 'string')
+                out[`${prefix}.message.content`] = part.response;
+        }
+    }
+    return out;
+}
+function messagesAttributes(key, messages) {
+    return Object.assign({}, ...messages.map((message, index) => messageAttributes(`${key}.${index}`, message)));
+}
+/** `input.value` / `output.value`: the text a person would read, else the messages as JSON. */
+function valueAttributes(side, messages) {
+    if (messages.length === 0)
+        return {};
+    const texts = messages.map(messageText).filter((text) => text !== '');
+    if (texts.length === messages.length && texts.length === 1 && texts[0] !== undefined) {
+        return { [`${side}.value`]: texts[0], [`${side}.mime_type`]: 'text/plain' };
+    }
+    return {
+        [`${side}.value`]: JSON.stringify(messages.map((message) => ({ role: message.role, content: messageText(message) }))),
+        [`${side}.mime_type`]: 'application/json',
+    };
+}
+function openInferenceModelMessages(record, span) {
+    const system = messagesOf(record, span.attributes['gen_ai.system_instructions'] === undefined
+        ? undefined
+        : [{ role: 'system', parts: span.attributes['gen_ai.system_instructions'] }]);
+    const input = [...system, ...messagesOf(record, span.attributes['gen_ai.input.messages'])];
+    const output = messagesOf(record, span.attributes['gen_ai.output.messages'] ?? span.attributes['theorem.output.delivered']);
+    return {
+        ...messagesAttributes('llm.input_messages', input),
+        ...messagesAttributes('llm.output_messages', output),
+        ...valueAttributes('input', input.filter((message) => message.role !== 'system')),
+        ...valueAttributes('output', output),
+    };
+}
+function openInferenceAgentValues(record, span) {
+    return {
+        ...valueAttributes('input', messagesOf(record, span.attributes['gen_ai.input.messages'])),
+        ...valueAttributes('output', messagesOf(record, span.attributes['gen_ai.output.messages'])),
+    };
+}
+function jsonValue(record, side, value) {
+    if (value === undefined)
+        return {};
+    return {
+        [`${side}.value`]: JSON.stringify(inlineContent(record, value)),
+        [`${side}.mime_type`]: 'application/json',
+    };
+}
+/**
+ * Phoenix derives no kind for an operation semconv does not name, and has no price for Jev, so
+ * the kind, model, tokens, and cost are stated. It has no messages, so Phoenix cannot replay it.
+ */
+function openInferenceDecision(record, span) {
+    const { attributes } = span;
+    const input = attributes['gen_ai.usage.input_tokens'];
+    const output = attributes['gen_ai.usage.output_tokens'];
+    const model = attributes['gen_ai.response.model'] ?? attributes['gen_ai.request.model'];
+    return {
+        'openinference.span.kind': 'LLM',
+        ...(typeof model === 'string' ? { 'llm.model_name': model } : {}),
+        ...(typeof attributes['gen_ai.provider.name'] === 'string'
+            ? { 'llm.provider': attributes['gen_ai.provider.name'] }
+            : {}),
+        ...(typeof input === 'number' ? { 'llm.token_count.prompt': input } : {}),
+        ...(typeof output === 'number' ? { 'llm.token_count.completion': output } : {}),
+        ...(typeof input === 'number' && typeof output === 'number'
+            ? { 'llm.token_count.total': input + output }
+            : {}),
+        ...openInferenceUsage(attributes),
+        ...jsonValue(record, 'input', attributes['theorem.decision.state']),
+        ...jsonValue(record, 'output', attributes['theorem.decision.answers']),
+    };
+}
+function withSpanAttributes(record, span) {
+    const operation = span.attributes['gen_ai.operation.name'];
+    if (MODEL_CALLS.has(operation)) {
+        return {
+            ...span,
+            attributes: {
+                ...span.attributes,
+                ...openInferenceUsage(span.attributes),
+                ...openInferenceModelMessages(record, span),
+            },
+        };
+    }
+    if (AGENT_CALLS.has(operation)) {
+        return {
+            ...span,
+            attributes: { ...span.attributes, ...openInferenceAgentValues(record, span) },
+        };
+    }
+    if (operation === DECISION) {
+        return {
+            ...span,
+            attributes: { ...span.attributes, ...openInferenceDecision(record, span) },
+        };
+    }
+    const evalKind = EVAL_KINDS[span.name];
+    if (evalKind !== undefined) {
+        return { ...span, attributes: { ...span.attributes, 'openinference.span.kind': evalKind } };
+    }
+    return span;
+}
+/** Pure: input records are not changed. Export with `toOtlpJson(withOpenInference(records))`. */
+function withOpenInference(records) {
+    return records.map((record) => ({
+        ...record,
+        spans: record.spans.map((span) => withSpanAttributes(record, span)),
+    }));
+}
+export { withOpenInference };

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

@@ -0,0 +1,71 @@
+import { type TraceRecord } from './trace-record.js';
+/** An OTLP/JSON attribute value. */
+type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    boolValue: boolean;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    arrayValue: {
+        values: OtlpAnyValue[];
+    };
+} | {
+    kvlistValue: {
+        values: OtlpKeyValue[];
+    };
+};
+/** An OTLP/JSON attribute: a key and its value. */
+interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+/** A span as OTLP/JSON carries it. */
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    events: {
+        timeUnixNano: string;
+        name: string;
+        attributes: OtlpKeyValue[];
+    }[];
+    links: {
+        traceId: string;
+        spanId: string;
+        attributes: OtlpKeyValue[];
+    }[];
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+/** An OTLP/JSON `ExportTraceServiceRequest` (the body of `POST /v1/traces`). */
+interface OtlpTraceRequest {
+    resourceSpans: {
+        resource: {
+            attributes: OtlpKeyValue[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+            };
+            schemaUrl: string;
+            spans: OtlpSpan[];
+        }[];
+    }[];
+}
+/**
+ * One resource per record, one scope, with every stored reference inlined. For a backend that
+ * takes protobuf only, send this through an OpenTelemetry Collector.
+ */
+declare function toOtlpJson(records: readonly TraceRecord[]): OtlpTraceRequest;
+export type { OtlpAnyValue, OtlpKeyValue, OtlpSpan, OtlpTraceRequest };
+export { toOtlpJson };

package/esm/src/observability/otlp.js

@@ -0,0 +1,98 @@
+// why: OTLP has no record-level slot for `TraceRecord.metadata` (the resource is the service's
+// identity), so each key lands on the record's top spans as `theorem.metadata.<key>`.
+import { inlineContent } from './trace-record.js';
+const SCOPE_NAME = '@theoremjs/agents';
+const SPAN_KIND = { INTERNAL: 1, CLIENT: 3 };
+const STATUS_CODE = { UNSET: 0, OK: 1, ERROR: 2 };
+function anyValue(value) {
+    if (typeof value === 'string') {
+        return { stringValue: value };
+    }
+    if (typeof value === 'boolean') {
+        return { boolValue: value };
+    }
+    if (typeof value === 'number') {
+        // why: int64 is a decimal string in OTLP/JSON.
+        return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    }
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.flatMap((item) => anyValue(item) ?? []) } };
+    }
+    if (value && typeof value === 'object') {
+        return { kvlistValue: { values: keyValues(value) } };
+    }
+    // why: null / undefined: OTLP has no empty value, so the key is left out.
+    return undefined;
+}
+function keyValues(fields) {
+    return Object.entries(fields).flatMap(([key, field]) => {
+        const value = anyValue(field);
+        return value ? [{ key, value }] : [];
+    });
+}
+function inlined(record, attributes) {
+    return keyValues(inlineContent(record, attributes));
+}
+const METADATA_PREFIX = 'theorem.metadata.';
+function metadataAttributes(record) {
+    return keyValues(record.metadata ?? {}).map(({ key, value }) => ({
+        key: `${METADATA_PREFIX}${key}`,
+        value,
+    }));
+}
+/** Includes the root, which may hang under a host `traceparent` span that lives elsewhere. */
+function topSpanIds(record) {
+    const ids = new Set(record.spans.map((span) => span.spanId));
+    return new Set(record.spans
+        .filter((span) => !(span.parentSpanId && ids.has(span.parentSpanId)))
+        .map((span) => span.spanId));
+}
+function otlpSpan(record, span, metadata) {
+    return {
+        traceId: span.traceId,
+        spanId: span.spanId,
+        ...(span.parentSpanId ? { parentSpanId: span.parentSpanId } : {}),
+        name: span.name,
+        kind: SPAN_KIND[span.kind],
+        startTimeUnixNano: span.startTimeUnixNano,
+        endTimeUnixNano: span.endTimeUnixNano,
+        attributes: [...inlined(record, span.attributes), ...metadata],
+        events: span.events.map((event) => ({
+            timeUnixNano: event.timeUnixNano,
+            name: event.name,
+            attributes: inlined(record, event.attributes),
+        })),
+        links: span.links.map((link) => ({
+            traceId: link.traceId,
+            spanId: link.spanId,
+            attributes: inlined(record, link.attributes),
+        })),
+        status: {
+            code: STATUS_CODE[span.status.code],
+            ...(span.status.message ? { message: span.status.message } : {}),
+        },
+    };
+}
+/**
+ * One resource per record, one scope, with every stored reference inlined. For a backend that
+ * takes protobuf only, send this through an OpenTelemetry Collector.
+ */
+function toOtlpJson(records) {
+    return {
+        resourceSpans: records.map((record) => {
+            const top = topSpanIds(record);
+            const metadata = metadataAttributes(record);
+            return {
+                resource: { attributes: keyValues(record.resource) },
+                scopeSpans: [
+                    {
+                        scope: { name: SCOPE_NAME },
+                        schemaUrl: record.schemaUrl,
+                        spans: record.spans.map((span) => otlpSpan(record, span, top.has(span.spanId) ? metadata : [])),
+                    },
+                ],
+            };
+        }),
+    };
+}
+export { toOtlpJson };

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

@@ -0,0 +1,30 @@
+/**
+ * Eval results as Phoenix span annotations, which Phoenix reads over REST
+ * (`POST /v1/span_annotations`), not OTLP. Pure: it builds the body, the host posts it.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { type TraceRecord } from './trace-record.js';
+/** A Phoenix annotation on a judged trial span: its name, whether an LLM judge or a code grader produced it, the result, and metadata. */
+interface PhoenixSpanAnnotation {
+    /** The judged root span, as OTLP hex. */
+    span_id: string;
+    name: string;
+    /** `LLM` for a judge's result, `CODE` for a code grader's. */
+    annotator_kind: 'LLM' | 'CODE';
+    result: {
+        label?: string;
+        score?: number;
+        explanation?: string;
+    };
+    metadata: Record<string, string | number | boolean>;
+}
+/**
+ * Each annotation lands on the root the trial judged. Send as
+ * `{ data: phoenixAnnotations(records) }`; Phoenix keeps one annotation per span and name, so
+ * grading a record again replaces them.
+ */
+declare function phoenixAnnotations(records: readonly TraceRecord[]): PhoenixSpanAnnotation[];
+export type { PhoenixSpanAnnotation };
+export { phoenixAnnotations };

package/esm/src/observability/phoenix.js

@@ -0,0 +1,71 @@
+/**
+ * Eval results as Phoenix span annotations, which Phoenix reads over REST
+ * (`POST /v1/span_annotations`), not OTLP. Pure: it builds the body, the host posts it.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { inlineContent } from './trace-record.js';
+const TRIAL_SPAN = 'theorem.eval.trial';
+const RESULT_EVENT = 'gen_ai.evaluation.result';
+function scalar(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+        ? value
+        : undefined;
+}
+function present(entries) {
+    const kept = {};
+    for (const [key, value] of Object.entries(entries))
+        if (value !== undefined)
+            kept[key] = value;
+    return kept;
+}
+/** `undefined` when the policy did not keep the explanation. */
+function explanationOf(record, value) {
+    if (value === undefined)
+        return undefined;
+    const text = inlineContent(record, value);
+    return typeof text === 'string' ? text : undefined;
+}
+function annotation(record, span, attributes) {
+    const name = attributes['gen_ai.evaluation.name'];
+    if (typeof name !== 'string')
+        return undefined;
+    const label = attributes['gen_ai.evaluation.score.label'];
+    const score = attributes['gen_ai.evaluation.score.value'];
+    const explanation = explanationOf(record, attributes['gen_ai.evaluation.explanation']);
+    return {
+        span_id: span.parentSpanId,
+        name,
+        annotator_kind: attributes['theorem.evaluation.source'] === 'model' ? 'LLM' : 'CODE',
+        result: {
+            ...(typeof label === 'string' ? { label } : {}),
+            ...(typeof score === 'number' ? { score } : {}),
+            ...(explanation === undefined ? {} : { explanation }),
+        },
+        metadata: present({
+            suite: scalar(span.attributes['theorem.evaluation.suite']),
+            case: scalar(span.attributes['theorem.evaluation.case']),
+            trial: scalar(span.attributes['theorem.evaluation.trial']),
+            passed: scalar(attributes['theorem.evaluation.passed']),
+            error_type: scalar(attributes['error.type']),
+            grader_version: scalar(attributes['theorem.evaluation.grader.version']),
+        }),
+    };
+}
+/**
+ * Each annotation lands on the root the trial judged. Send as
+ * `{ data: phoenixAnnotations(records) }`; Phoenix keeps one annotation per span and name, so
+ * grading a record again replaces them.
+ */
+function phoenixAnnotations(records) {
+    return records.flatMap((record) => record.spans.flatMap((span) => {
+        if (span.name !== TRIAL_SPAN || span.parentSpanId === undefined)
+            return [];
+        const trial = { ...span, parentSpanId: span.parentSpanId };
+        return span.events
+            .filter((event) => event.name === RESULT_EVENT)
+            .flatMap((event) => annotation(record, trial, event.attributes) ?? []);
+    }));
+}
+export { phoenixAnnotations };

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

@@ -0,0 +1,17 @@
+import type { ProfileGuardrailsSpec } from '../guardrails/types.js';
+import type { TraceSink } from './trace-sink.js';
+import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
+/**
+ * Precedence: explicit `override` (runTurn's third arg), then profile `writeTo`, then noop. An
+ * override always records, ignoring `sampleRate`, so tests and one-off capture are deterministic.
+ */
+declare function resolveTraceWriter(args: {
+    override?: TraceSink;
+    observability?: ProfileObservabilitySpec;
+    /** The profile's guardrails: the patterns a host gave its detectors clean the record too. */
+    guardrails?: ProfileGuardrailsSpec;
+}): {
+    sink: TraceSink;
+    policy: ResolvedObservabilityPolicy;
+};
+export { resolveTraceWriter };

package/esm/src/observability/policy.js

@@ -0,0 +1,73 @@
+import { resolveGuardrailPolicy } from '../guardrails/policy.js';
+import { requireTraceDestination } from './destinations.js';
+import { resolveObservabilityPolicy } from './resolve-policy.js';
+import { noopSink } from './trace.js';
+function bindOnWriteError(sink, onWriteError) {
+    if (!onWriteError && !sink.onError) {
+        return sink;
+    }
+    return {
+        write: (record, context) => sink.write(record, context),
+        onError: sink.onError ?? onWriteError,
+    };
+}
+/** Trace-id bits the sampling decision reads: the low 32 (8 hex digits). */
+const SAMPLE_HEX_DIGITS = 8;
+const SAMPLE_SPACE = 2 ** 32;
+/**
+ * Decided by trace id (OpenTelemetry `TraceIdRatioBased`), so every record of one trace (a turn,
+ * its specialists, a Live session's responses, a host's cutout) is kept or dropped together.
+ */
+function traceSampled(record, sampleRate) {
+    const traceId = record.spans[0]?.traceId ?? '';
+    return Number.parseInt(traceId.slice(-SAMPLE_HEX_DIGITS), 16) / SAMPLE_SPACE < sampleRate;
+}
+function withSampleRate(sink, sampleRate) {
+    if (sampleRate >= 1) {
+        return sink;
+    }
+    if (sampleRate <= 0) {
+        return noopSink();
+    }
+    return {
+        write: async (record, context) => {
+            if (traceSampled(record, sampleRate)) {
+                await sink.write(record, context);
+            }
+        },
+        onError: sink.onError,
+    };
+}
+function sinkFromWriteTo(writeTo, policy) {
+    if (writeTo === undefined || writeTo === false) {
+        return noopSink();
+    }
+    if (typeof writeTo !== 'string') {
+        return bindOnWriteError(writeTo, policy.onWriteError);
+    }
+    return bindOnWriteError(requireTraceDestination(writeTo), policy.onWriteError);
+}
+/**
+ * Precedence: explicit `override` (runTurn's third arg), then profile `writeTo`, then noop. An
+ * override always records, ignoring `sampleRate`, so tests and one-off capture are deterministic.
+ */
+function resolveTraceWriter(args) {
+    const policy = {
+        ...resolveObservabilityPolicy(args.observability),
+        detect: resolveGuardrailPolicy(args.guardrails).detect,
+    };
+    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),
+    };
+}
+export { resolveTraceWriter };

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

@@ -0,0 +1,8 @@
+import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
+/** Default record retention in days; `<= 0` keeps records forever. */
+declare const DEFAULT_RETAIN_DAYS = 14;
+/** Default JSONL file size, in MiB, before the writer rotates to a new file. */
+declare const DEFAULT_ROTATE_MIB = 32;
+/** An omitted block or `writeTo: false` resolves `record: false`; `sampleRate` applies at write. */
+declare function resolveObservabilityPolicy(spec: ProfileObservabilitySpec | undefined): ResolvedObservabilityPolicy;
+export { DEFAULT_RETAIN_DAYS, DEFAULT_ROTATE_MIB, resolveObservabilityPolicy };

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

@@ -0,0 +1,64 @@
+// why: Pure, with no sinks or file system, so kernel type consumers never pull the JSONL sink into their
+// graph.
+import { TheoremError } from '../guardrails/error.js';
+/** Default record retention in days; `<= 0` keeps records forever. */
+const DEFAULT_RETAIN_DAYS = 14;
+/** Default JSONL file size, in MiB, before the writer rotates to a new file. */
+const DEFAULT_ROTATE_MIB = 32;
+function resolveInclude(spec) {
+    // why: No authored block records only through an explicit capture sink (tests,
+    // `runTurn(..., sink)`), which keeps wire and raw evidence. Authored blocks
+    // default those two 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 resolveSwitch(spec) {
+    if (spec === undefined || typeof spec === 'boolean')
+        return spec ?? true;
+    const sides = { theorem: spec.theorem ?? true, host: spec.host ?? true };
+    return (sides.theorem || sides.host) && sides;
+}
+function resolveScrub(spec) {
+    return {
+        sensitive: resolveSwitch(spec?.scrub?.sensitive),
+        injection: resolveSwitch(spec?.scrub?.injection),
+        canary: resolveSwitch(spec?.scrub?.canary),
+    };
+}
+function clampSampleRate(value) {
+    if (value === undefined) {
+        return 1;
+    }
+    if (!Number.isFinite(value)) {
+        throw new TheoremError('config', 'observability.sampleRate must be a finite number');
+    }
+    if (value < 0 || value > 1) {
+        throw new TheoremError('config', 'observability.sampleRate must be between 0 and 1 inclusive');
+    }
+    return value;
+}
+/** An omitted block or `writeTo: false` resolves `record: false`; `sampleRate` applies at write. */
+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),
+        resource: { ...(spec?.resource ?? {}) },
+        retainForDays: spec?.retainForDays ?? DEFAULT_RETAIN_DAYS,
+        rotateAfterMiB: spec?.rotateAfterMiB ?? DEFAULT_ROTATE_MIB,
+        onWriteError: spec?.onWriteError,
+    };
+}
+export { DEFAULT_RETAIN_DAYS, DEFAULT_ROTATE_MIB, resolveObservabilityPolicy };

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

@@ -0,0 +1,22 @@
+declare const OMIT_INJECTION = "[omitted - injection]";
+declare const OMIT_SENSITIVE = "[omitted -sensitive]";
+declare const OMIT_CANARY = "[omitted - canary]";
+type RedactKind = 'injection' | 'sensitive' | 'canary' | 'prompt' | 'image' | 'link' | 'tool' | 'directive' | 'host';
+interface RedactSpan {
+    start: number;
+    end: number;
+    kind: RedactKind;
+    /** The name of the host's pattern that matched; unset for a match of Theorem's own. */
+    name?: string;
+    /** What about the match makes it one, for a detector that finds more than one thing. */
+    signal?: string;
+}
+declare function blobAt(match: RegExpMatchArray): {
+    blob: string;
+    index: number;
+} | undefined;
+declare function mergeSpans(spans: RedactSpan[]): RedactSpan[];
+declare function applySpans(text: string, spans: RedactSpan[]): string;
+declare function spansFromPatterns(text: string, patterns: RegExp[], kind: RedactKind): RedactSpan[];
+export type { RedactKind, RedactSpan };
+export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns, };