@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,23 @@
+import { type TraceRecord } from './trace-schema.js';
+import { type TraceAttributeValue, type TraceSpan } from './trace-span.js';
+import type { ResolvedObservabilityPolicy } from './types.js';
+/** Pinned OpenTelemetry GenAI semantic conventions the attribute names follow. */
+declare const TRACE_SCHEMA_URL = "https://github.com/open-telemetry/semantic-conventions-genai/tree/8ffdf56";
+/** `spans` is `TraceTree.collect()` output, root first. The root gains the policy it ran under. */
+declare function buildRecord(args: {
+    spans: TraceSpan[];
+    policy: ResolvedObservabilityPolicy;
+    /** Every canary bound in this record, the turn's and any nested turn's. */
+    canaries?: readonly string[];
+    metadata?: Record<string, unknown>;
+}): Promise<TraceRecord>;
+/** `undefined` for a non-reference, and for a blob, whose bytes were never stored. */
+declare function contentOf(record: TraceRecord, value: TraceAttributeValue | undefined): string | undefined;
+/**
+ * Replaces every stored reference by what it names. `{ content_sha256 }` beside other keys (a
+ * message part) becomes `content`; `{ json_sha256 }` beside other keys is merged under them. A
+ * reference whose hash is not in `content` (a blob's bytes) is kept as is.
+ */
+declare function inlineContent(record: TraceRecord, value: unknown): unknown;
+export type { TraceRecord };
+export { buildRecord, contentOf, inlineContent, TRACE_SCHEMA_URL };

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

@@ -0,0 +1,223 @@
+// Include flags drop whole attribute families or events here, in one place, so a missing field
+// reads as "not recorded" and the root says which policy applied (`theorem.record.include`).
+import { redactSensitiveOnly, sanitizeText } from '../guardrails/sanitize.js';
+import { sha256, sha256Base64 } from '../kernel/engine/hash.js';
+import { removeCanaries, tapeUpstream } from '../providers/shared/upstream-tape.js';
+import { TRACE_VERSION } from './trace-schema.js';
+import { isTraceBytes, isTraceContent, isTraceJson, } from './trace-span.js';
+/** Pinned OpenTelemetry GenAI semantic conventions the attribute names follow. */
+const TRACE_SCHEMA_URL = 'https://github.com/open-telemetry/semantic-conventions-genai/tree/8ffdf56';
+const TEXT_REF = 'content_sha256';
+const JSON_REF = 'json_sha256';
+const USAGE_PREFIXES = ['gen_ai.usage.', 'theorem.usage.'];
+const EVENT_INCLUDE = {
+    'theorem.upstream.row': 'upstreamLog',
+    'theorem.wire.request': 'outboundWire',
+    'theorem.guardrail': 'guardrailDecisions',
+};
+/** Grounding events keep normalized sources; the provider's raw payload needs `evidenceRaw`. */
+const RAW_ATTRIBUTE = 'raw';
+/** Guardrail hits keep the matched text only under `guardrailMatchPreview`. */
+const MATCH_ATTRIBUTE = 'match';
+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 storeText(text, resolver) {
+    const hash = await sha256(text);
+    resolver.content[hash] = text;
+    resolver.known.set(text, hash);
+    return hash;
+}
+function markerRest(value, key) {
+    const { [key]: _marker, ...rest } = value;
+    return rest;
+}
+/** Pass 1: text and bytes. `$json` waits for pass 2, when every text is known. */
+async function resolveContent(value, resolver) {
+    if (isTraceContent(value)) {
+        const text = removeCanaries(scrubStoredText(value.$content, resolver.scrub), resolver.canaries);
+        return { ...markerRest(value, '$content'), [TEXT_REF]: await storeText(text, resolver) };
+    }
+    if (isTraceBytes(value)) {
+        const rest = markerRest(value, '$bytes');
+        const digest = await sha256Base64(value.$bytes);
+        // Not base64: hash the text as given and say so, rather than lose the record.
+        return digest
+            ? { ...rest, content_sha256: digest.hash, bytes: digest.bytes }
+            : { ...rest, invalid_base64: true, text_sha256: await sha256(value.$bytes) };
+    }
+    if (isTraceJson(value)) {
+        return value;
+    }
+    return await mapNested(value, (nested) => resolveContent(nested, resolver));
+}
+function mapStrings(value, rewrite) {
+    if (typeof value === 'string') {
+        return rewrite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => mapStrings(item, rewrite));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, mapStrings(nested, rewrite)]));
+    }
+    return value;
+}
+/** Scrub a row's strings, then reference any string pass 1 already stored. */
+function internRow(row, resolver) {
+    return mapStrings(row, (text) => {
+        const scrubbed = scrubStoredText(text, resolver.scrub);
+        const hash = resolver.known.get(scrubbed);
+        return hash ? { [TEXT_REF]: hash } : scrubbed;
+    });
+}
+/** Pass 2: rows and bodies, interned against every text pass 1 stored. */
+async function resolveJson(value, resolver) {
+    if (isTraceJson(value)) {
+        const taped = await tapeUpstream(value.$json, resolver.canaries);
+        const text = JSON.stringify(internRow(taped, resolver));
+        const hash = await sha256(text);
+        resolver.content[hash] = text;
+        return { ...markerRest(value, '$json'), [JSON_REF]: hash };
+    }
+    return await mapNested(value, (nested) => resolveJson(nested, resolver));
+}
+async function mapNested(value, map) {
+    if (Array.isArray(value)) {
+        return await Promise.all(value.map(map));
+    }
+    if (value && typeof value === 'object') {
+        const pairs = await Promise.all(Object.entries(value).map(async ([key, nested]) => [key, await map(nested)]));
+        return Object.fromEntries(pairs);
+    }
+    return value;
+}
+async function resolveAttributes(attributes, resolve) {
+    const pairs = await Promise.all(Object.entries(attributes).map(async ([key, value]) => [key, await resolve(value)]));
+    return Object.fromEntries(pairs);
+}
+async function resolveSpan(span, resolve) {
+    const events = await Promise.all(span.events.map(async (event) => ({
+        ...event,
+        attributes: await resolveAttributes(event.attributes, resolve),
+    })));
+    return { ...span, attributes: await resolveAttributes(span.attributes, resolve), events };
+}
+function includedAttributes(attributes, include) {
+    if (include.usage) {
+        return attributes;
+    }
+    return Object.fromEntries(Object.entries(attributes).filter(([key]) => !USAGE_PREFIXES.some((prefix) => key.startsWith(prefix))));
+}
+/** Guardrail hits without the text they matched. */
+function withoutMatches(hits) {
+    return hits.map((hit) => {
+        if (!hit || typeof hit !== 'object' || Array.isArray(hit)) {
+            return hit;
+        }
+        const { [MATCH_ATTRIBUTE]: _match, ...rest } = hit;
+        return rest;
+    });
+}
+function includedEvent(event, include) {
+    const flag = EVENT_INCLUDE[event.name];
+    if (flag && !include[flag]) {
+        return undefined;
+    }
+    if (event.name === 'theorem.grounding' && !include.evidenceRaw) {
+        const { [RAW_ATTRIBUTE]: _raw, ...rest } = event.attributes;
+        return { ...event, attributes: rest };
+    }
+    const { hits } = event.attributes;
+    if (event.name === 'theorem.guardrail' && !include.guardrailMatchPreview && Array.isArray(hits)) {
+        return { ...event, attributes: { ...event.attributes, hits: withoutMatches(hits) } };
+    }
+    return event;
+}
+function applyInclude(span, include) {
+    return {
+        ...span,
+        attributes: includedAttributes(span.attributes, include),
+        events: span.events.flatMap((event) => includedEvent(event, include) ?? []),
+    };
+}
+function enabledKeys(flags) {
+    return Object.entries(flags).flatMap(([key, on]) => (on ? [key] : []));
+}
+/** `spans` is `TraceTree.collect()` output, root first. The root gains the policy it ran under. */
+async function buildRecord(args) {
+    const { policy } = args;
+    const resolver = {
+        scrub: policy.scrub,
+        canaries: policy.scrub.canary ? (args.canaries ?? []) : [],
+        content: {},
+        known: new Map(),
+    };
+    const included = args.spans.map((span) => applyInclude(span, policy.include));
+    const [root] = included;
+    if (root) {
+        root.attributes = {
+            ...root.attributes,
+            'theorem.record.include': enabledKeys(policy.include),
+            'theorem.record.scrub': enabledKeys(policy.scrub),
+        };
+    }
+    const texts = await Promise.all(included.map((span) => resolveSpan(span, (value) => resolveContent(value, resolver))));
+    const spans = await Promise.all(texts.map((span) => resolveSpan(span, (value) => resolveJson(value, resolver))));
+    return {
+        v: TRACE_VERSION,
+        schemaUrl: TRACE_SCHEMA_URL,
+        resource: { ...policy.resource },
+        ...(args.metadata ? { metadata: args.metadata } : {}),
+        spans,
+        content: resolver.content,
+    };
+}
+/** `undefined` for a non-reference, and for a blob, whose bytes were never stored. */
+function contentOf(record, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const hash = value[TEXT_REF] ?? value[JSON_REF];
+    return typeof hash === 'string' ? record.content[hash] : undefined;
+}
+/**
+ * Replaces every stored reference by what it names. `{ content_sha256 }` beside other keys (a
+ * message part) becomes `content`; `{ json_sha256 }` beside other keys is merged under them. A
+ * reference whose hash is not in `content` (a blob's bytes) is kept as is.
+ */
+function inlineContent(record, value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => inlineContent(record, item));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const fields = Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, inlineContent(record, nested)]));
+    const { [TEXT_REF]: textHash, [JSON_REF]: jsonHash, ...rest } = fields;
+    const text = typeof textHash === 'string' ? record.content[textHash] : undefined;
+    if (text !== undefined) {
+        return Object.keys(rest).length === 0 ? text : { ...rest, content: text };
+    }
+    const json = typeof jsonHash === 'string' ? record.content[jsonHash] : undefined;
+    if (json === undefined) {
+        return fields;
+    }
+    const parsed = inlineContent(record, JSON.parse(json));
+    if (Object.keys(rest).length === 0) {
+        return parsed;
+    }
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? { ...parsed, ...rest }
+        : fields;
+}
+export { buildRecord, contentOf, inlineContent, TRACE_SCHEMA_URL };

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

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const TRACE_VERSION = 3;
+/** JSON-shaped attribute value (OTLP `AnyValue`). */
+export type TraceAttributeValue = null | string | number | boolean | TraceAttributeValue[] | {
+    [key: string]: TraceAttributeValue;
+};
+export type TraceAttributes = Record<string, TraceAttributeValue>;
+export declare const traceAttributesSchema: z.ZodType<TraceAttributes>;
+/** OTLP span kind. THEOREM emits INTERNAL (agent, tool) and CLIENT (model call). */
+export type TraceSpanKind = 'INTERNAL' | 'CLIENT';
+/** OTLP status. `UNSET` is used for cancelled and paused spans. */
+export interface TraceSpanStatus {
+    code: 'OK' | 'ERROR' | 'UNSET';
+    message?: string;
+}
+/** Edge to a span in an earlier trace (resume, continue, retry). */
+export interface TraceSpanLink {
+    traceId: string;
+    spanId: string;
+    attributes: TraceAttributes;
+}
+export interface TraceSpanEvent {
+    name: string;
+    timeUnixNano: string;
+    attributes: TraceAttributes;
+}
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: TraceSpanKind;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: TraceAttributes;
+    events: TraceSpanEvent[];
+    links: TraceSpanLink[];
+    status: TraceSpanStatus;
+}
+/** One trace record: a turn, a host-invoked tool, or a Live session root or response. */
+export interface TraceRecord {
+    v: typeof TRACE_VERSION;
+    schemaUrl: string;
+    /** Host-supplied process attributes (`observability.resource`), e.g. `service.name`. */
+    resource: TraceAttributes;
+    /** Host-owned metadata from the request, passed through untouched. */
+    metadata?: Record<string, unknown>;
+    /** Root first, then in start order. */
+    spans: TraceSpan[];
+    /** sha256 hex → exact scrubbed text; every hash the spans reference. */
+    content: Record<string, string>;
+}
+/** What a reader runs on a trace record from a wire; other versions fail. */
+export declare const traceRecordSchema: z.ZodType<TraceRecord>;

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

@@ -0,0 +1,59 @@
+// Each type is checked against its zod schema (`Equals`), so a field in one and not the other fails
+// the build. A record crosses a wire, so a reader parses it with `traceRecordSchema` first.
+import { z } from 'zod';
+export const TRACE_VERSION = 3;
+const traceAttributeValue = z.lazy(() => z.union([
+    z.null(),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(traceAttributeValue),
+    z.record(z.string(), traceAttributeValue),
+]));
+const traceAttributes = z.record(z.string(), traceAttributeValue);
+true;
+export const traceAttributesSchema = traceAttributes;
+const traceSpanKind = z.enum(['INTERNAL', 'CLIENT']);
+true;
+const traceSpanStatus = z.object({
+    code: z.enum(['OK', 'ERROR', 'UNSET']),
+    message: z.string().optional(),
+});
+true;
+const traceSpanLink = z.object({
+    traceId: z.string(),
+    spanId: z.string(),
+    attributes: traceAttributes,
+});
+true;
+const traceSpanEvent = z.object({
+    name: z.string(),
+    timeUnixNano: z.string(),
+    attributes: traceAttributes,
+});
+true;
+const traceSpan = z.object({
+    traceId: z.string(),
+    spanId: z.string(),
+    parentSpanId: z.string().optional(),
+    name: z.string(),
+    kind: traceSpanKind,
+    startTimeUnixNano: z.string(),
+    endTimeUnixNano: z.string(),
+    attributes: traceAttributes,
+    events: z.array(traceSpanEvent),
+    links: z.array(traceSpanLink),
+    status: traceSpanStatus,
+});
+true;
+const traceRecord = z.object({
+    v: z.literal(TRACE_VERSION),
+    schemaUrl: z.string(),
+    resource: traceAttributes,
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    spans: z.array(traceSpan),
+    content: z.record(z.string(), z.string()),
+});
+true;
+/** What a reader runs on a trace record from a wire; other versions fail. */
+export const traceRecordSchema = traceRecord;

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

@@ -0,0 +1,13 @@
+import type { TraceRecord } from './trace-record.js';
+/** Every destination receives it, so a host store reads the storage policy the JSONL writer does. */
+export interface TraceWriteContext {
+    /** Days to keep the record from now; `<= 0` keeps it forever. */
+    retainForDays: number;
+    /** Size at which a file-based destination starts a new file. */
+    rotateAfterMiB: number;
+}
+export interface TraceSink {
+    write: (record: TraceRecord, context: TraceWriteContext) => Promise<void>;
+    /** Called when `writeTrace` catches a build or write failure. Must not throw. */
+    onError?: (err: unknown) => void;
+}

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

@@ -0,0 +1,3 @@
+// Type-only so programs that never write files (browser bundles, Workers) never pull the JSONL
+// file sink into their module graph.
+export {};

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

@@ -0,0 +1,92 @@
+import type { TraceAttributes, TraceAttributeValue, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus } from './trace-schema.js';
+/** In-memory text awaiting scrub + hash at record build. */
+interface TraceContent {
+    [key: string]: TraceAttributeValue;
+    $content: string;
+}
+/** In-memory base64 bytes awaiting hash at record build. */
+interface TraceBytes {
+    [key: string]: TraceAttributeValue;
+    $bytes: string;
+}
+/** In-memory provider row or wire body awaiting scrub, intern and hash at record build. */
+interface TraceJson {
+    [key: string]: TraceAttributeValue;
+    $json: TraceAttributeValue;
+}
+interface SpanLinkInput {
+    traceparent: string;
+    attributes?: TraceAttributes;
+}
+interface SpanOptions {
+    kind?: TraceSpanKind;
+    attributes?: TraceAttributes;
+    links?: SpanLinkInput[];
+    /** When the span began, for work measured before the span was opened. Default: now. */
+    startTimeUnixNano?: string;
+}
+/** Handle to an open span. Every method is safe to call after `end`. */
+interface SpanHandle {
+    readonly traceId: string;
+    readonly spanId: string;
+    /** True once `end` ran or the trace was collected. */
+    readonly ended: boolean;
+    traceparent: () => string;
+    child: (name: string, options?: SpanOptions) => SpanHandle;
+    /** Merge attributes; later values win. Ignored after `end`. */
+    set: (attributes: TraceAttributes) => void;
+    /**
+     * Append a timestamped event. `timeUnixNano` places an event observed before
+     * it could be attached (default: now). Ignored after `end`.
+     */
+    event: (name: string, attributes?: TraceAttributes, timeUnixNano?: string) => void;
+    /** Default status is `OK`. Second and later calls are ignored. */
+    end: (status?: TraceSpanStatus) => void;
+    msSinceStart: () => number;
+    /** Milliseconds from this span's end to now; `undefined` while open. */
+    msSinceEnd: () => number | undefined;
+    /** Now on the trace's clock, as span timestamps are written. */
+    nowUnixNano: () => string;
+}
+interface TraceTree {
+    root: SpanHandle;
+    /** The trace's clock; pass it to `startTrace` so related trees share one timeline. */
+    clock: TraceClock;
+    /** Closes anything still open as `ERROR` / `unclosed`; returns root first, then start order. */
+    collect: () => TraceSpan[];
+}
+interface TraceClock {
+    nowUnixNano: () => bigint;
+}
+/**
+ * The trace and span ids of a W3C `traceparent` THEOREM accepts (version 00,
+ * lowercase hex, non-zero ids), or `undefined`. For a host checking a value from
+ * a request before handing it to a turn, which throws on anything else.
+ */
+declare function readTraceparent(value: string): {
+    traceId: string;
+    spanId: string;
+} | undefined;
+/** Throws on a malformed value: a host bug, not a runtime state. */
+declare function parseTraceparent(value: string): {
+    traceId: string;
+    spanId: string;
+};
+declare function formatTraceparent(traceId: string, spanId: string): string;
+declare function traceContent(text: string): TraceContent;
+declare function traceBytes(base64: string): TraceBytes;
+/** `undefined` members and non-JSON values are dropped the way `JSON.stringify` drops them. */
+declare function traceJson(value: unknown): TraceJson;
+declare function isTraceContent(value: unknown): value is TraceContent;
+declare function isTraceBytes(value: unknown): value is TraceBytes;
+declare function isTraceJson(value: unknown): value is TraceJson;
+/**
+ * Open a root span. With `traceparent`, the root joins that trace as a child of
+ * the named span; without it, the root starts a new trace.
+ */
+declare function startTrace(name: string, options?: SpanOptions & {
+    traceparent?: string;
+    clock?: TraceClock;
+}): TraceTree;
+export type { SpanHandle, SpanLinkInput, SpanOptions, TraceAttributes, TraceAttributeValue, TraceBytes, TraceClock, TraceContent, TraceJson, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus, TraceTree, };
+export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, startTrace, traceBytes, traceContent, traceJson, };

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

@@ -0,0 +1,199 @@
+// Content is held in memory as markers the record builder resolves: `$content` is scrubbed, hashed
+// and moved into `TraceRecord.content`; `$bytes` is hashed and never stored; `$json` has media
+// hashed and strings equal to recorded content replaced by their hash.
+import { TheoremError } from '../guardrails/error.js';
+import { isRecord } from '../kernel/util/record.js';
+const TRACE_ID_BYTES = 16;
+const SPAN_ID_BYTES = 8;
+const NANOS_PER_MS = 1_000_000;
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+const ALL_ZERO = /^0+$/;
+const SAMPLED_FLAGS = '01';
+const UNCLOSED = 'unclosed';
+function randomHex(bytes) {
+    for (;;) {
+        const buf = crypto.getRandomValues(new Uint8Array(bytes));
+        const hex = [...buf].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+        if (!ALL_ZERO.test(hex)) {
+            return hex;
+        }
+    }
+}
+/** On Cloudflare Workers both clocks advance only at I/O; the root carries `theorem.clock=io`. */
+function systemClock() {
+    const epochMs = Date.now();
+    const perfStart = performance.now();
+    return {
+        nowUnixNano: () => BigInt(epochMs) * BigInt(NANOS_PER_MS) +
+            BigInt(Math.round((performance.now() - perfStart) * NANOS_PER_MS)),
+    };
+}
+function clockAdvancesOnlyAtIo() {
+    return globalThis.navigator?.userAgent === 'Cloudflare-Workers';
+}
+/**
+ * The trace and span ids of a W3C `traceparent` THEOREM accepts (version 00,
+ * lowercase hex, non-zero ids), or `undefined`. For a host checking a value from
+ * a request before handing it to a turn, which throws on anything else.
+ */
+function readTraceparent(value) {
+    const match = TRACEPARENT.exec(value.trim());
+    const traceId = match?.[1];
+    const spanId = match?.[2];
+    if (!traceId || !spanId || ALL_ZERO.test(traceId) || ALL_ZERO.test(spanId))
+        return undefined;
+    return { traceId, spanId };
+}
+/** Throws on a malformed value: a host bug, not a runtime state. */
+function parseTraceparent(value) {
+    const parsed = readTraceparent(value);
+    if (!parsed) {
+        throw new TheoremError('request', `traceparent is not a valid W3C trace context: '${value}'`);
+    }
+    return parsed;
+}
+function formatTraceparent(traceId, spanId) {
+    return `00-${traceId}-${spanId}-${SAMPLED_FLAGS}`;
+}
+function traceContent(text) {
+    return { $content: text };
+}
+function traceBytes(base64) {
+    return { $bytes: base64 };
+}
+/** `undefined` members and non-JSON values are dropped the way `JSON.stringify` drops them. */
+function traceJson(value) {
+    return { $json: toAttributeValue(value) ?? null };
+}
+function toAttributeValue(value) {
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => toAttributeValue(item) ?? null);
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            const mapped = toAttributeValue(nested);
+            if (mapped !== undefined) {
+                out[key] = mapped;
+            }
+        }
+        return out;
+    }
+    return undefined;
+}
+function isMarker(value, key) {
+    return isRecord(value) && key in value;
+}
+function isTraceContent(value) {
+    return isMarker(value, '$content') && typeof value.$content === 'string';
+}
+function isTraceBytes(value) {
+    return isMarker(value, '$bytes') && typeof value.$bytes === 'string';
+}
+function isTraceJson(value) {
+    return isMarker(value, '$json');
+}
+function linkFrom(input) {
+    const { traceId, spanId } = parseTraceparent(input.traceparent);
+    return { traceId, spanId, attributes: { ...(input.attributes ?? {}) } };
+}
+function msBetween(fromUnixNano, clock) {
+    return Number(clock.nowUnixNano() - BigInt(fromUnixNano)) / NANOS_PER_MS;
+}
+function openHandle(state, traceId, parentSpanId, name, options) {
+    const entry = {
+        span: {
+            traceId,
+            spanId: randomHex(SPAN_ID_BYTES),
+            ...(parentSpanId ? { parentSpanId } : {}),
+            name,
+            kind: options?.kind ?? 'INTERNAL',
+            startTimeUnixNano: options?.startTimeUnixNano ?? String(state.clock.nowUnixNano()),
+            endTimeUnixNano: '',
+            attributes: { ...(options?.attributes ?? {}) },
+            events: [],
+            links: (options?.links ?? []).map(linkFrom),
+            status: { code: 'UNSET' },
+        },
+        ended: false,
+        order: state.open.length,
+    };
+    state.open.push(entry);
+    const { span } = entry;
+    return {
+        traceId,
+        spanId: span.spanId,
+        get ended() {
+            return entry.ended;
+        },
+        traceparent: () => formatTraceparent(traceId, span.spanId),
+        child: (childName, childOptions) => openHandle(state, traceId, span.spanId, childName, childOptions),
+        set: (attributes) => {
+            if (!entry.ended) {
+                Object.assign(span.attributes, attributes);
+            }
+        },
+        event: (eventName, attributes, timeUnixNano) => {
+            if (!entry.ended) {
+                span.events.push({
+                    name: eventName,
+                    timeUnixNano: timeUnixNano ?? String(state.clock.nowUnixNano()),
+                    attributes: { ...(attributes ?? {}) },
+                });
+            }
+        },
+        end: (status) => {
+            if (entry.ended) {
+                return;
+            }
+            entry.ended = true;
+            span.endTimeUnixNano = String(state.clock.nowUnixNano());
+            span.status = status ?? { code: 'OK' };
+        },
+        msSinceStart: () => msBetween(span.startTimeUnixNano, state.clock),
+        msSinceEnd: () => (entry.ended ? msBetween(span.endTimeUnixNano, state.clock) : undefined),
+        nowUnixNano: () => String(state.clock.nowUnixNano()),
+    };
+}
+/**
+ * Open a root span. With `traceparent`, the root joins that trace as a child of
+ * the named span; without it, the root starts a new trace.
+ */
+function startTrace(name, options = {}) {
+    const parent = options.traceparent ? parseTraceparent(options.traceparent) : undefined;
+    const state = { clock: options.clock ?? systemClock(), open: [] };
+    const root = openHandle(state, parent?.traceId ?? randomHex(TRACE_ID_BYTES), parent?.spanId, name, {
+        ...options,
+        attributes: {
+            ...(clockAdvancesOnlyAtIo() ? { 'theorem.clock': 'io' } : {}),
+            ...(options.attributes ?? {}),
+        },
+    });
+    return {
+        root,
+        clock: state.clock,
+        collect: () => {
+            const now = String(state.clock.nowUnixNano());
+            for (const entry of state.open) {
+                if (!entry.ended) {
+                    entry.ended = true;
+                    entry.span.endTimeUnixNano = now;
+                    entry.span.status = { code: 'ERROR', message: UNCLOSED };
+                }
+            }
+            return [...state.open].sort((a, b) => a.order - b.order).map((entry) => entry.span);
+        },
+    };
+}
+export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, startTrace, traceBytes, traceContent, traceJson, };

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

@@ -0,0 +1,11 @@
+import { type TraceRecord } from './trace-record.js';
+import type { TraceSink } from './trace-sink.js';
+import type { TraceSpan } from './trace-span.js';
+import type { ResolvedObservabilityPolicy } from './types.js';
+/** Trace failures never fail the turn: build and write errors go to `sink.onError`, if set. */
+declare function writeTrace(sink: TraceSink, record: Promise<TraceRecord>, policy: ResolvedObservabilityPolicy): Promise<void>;
+/** Like `writeTrace`, it never fails the caller. */
+declare function writeSpans(sink: TraceSink, spans: TraceSpan[], policy: ResolvedObservabilityPolicy, metadata?: Record<string, unknown>): Promise<void>;
+declare function noopSink(): TraceSink;
+declare function memorySink(into: TraceRecord[]): TraceSink;
+export { memorySink, noopSink, writeSpans, writeTrace };