indusagi 0.12.32 → 0.12.34

package/dist/types/tracing/recorder/recorder.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The tracer instance: a {@link Recorder}.
+ *
+ * A recorder is the object call sites reach for to *start* tracing. It owns a
+ * {@link SignalChannel} (the transport sinks drain) and a {@link SampleGate}
+ * (admission control), and stamps every trace it produces with a `serviceName`.
+ * Its one job is {@link open}: consult the gate, and either mint a live
+ * {@link SegmentHandle} whose signals flow onto the channel, or hand back the
+ * shared {@link NOOP_HANDLE} so a sampled-out trace costs nothing downstream.
+ *
+ * This replaces the OTel "tracer provider / tracer" pair with a single, flat
+ * object: there is no global ambient context, no `startSpan` ceremony, and no
+ * exporter wiring here — sinks subscribe by draining {@link channel}.
+ */
+import { SignalChannel } from "../channel/signal";
+import { type SegmentHandle } from "../signal/handle";
+import { type SegmentKind } from "../signal/segment";
+import { SampleGate, type SampleStrategy } from "./sampling";
+/** Per-`open` options; all optional. */
+export interface OpenOptions {
+    /**
+     * Trace to join. Omit to start a *new* trace (the recorder mints a fresh id
+     * and the gate decides on it). Supplied for a child whose admission should
+     * follow its trace's verdict.
+     */
+    readonly traceId?: string;
+    /** Enclosing segment id, or `null`/omitted for a trace root. */
+    readonly parentId?: string | null;
+    /** Initial attributes for the opened segment. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/** Construction options for a {@link Recorder}. */
+export interface RecorderOptions {
+    /**
+     * Logical name of the service/agent this recorder traces. Stamped onto the
+     * root attributes of every admitted trace under the `service.name` key.
+     */
+    readonly serviceName: string;
+    /** Admission strategy or a pre-built gate; defaults to `"always"`. */
+    readonly sampling?: SampleStrategy | SampleGate;
+    /** Transport to emit onto; a fresh unbounded {@link SignalChannel} by default. */
+    readonly channel?: SignalChannel;
+}
+/**
+ * A homegrown tracer instance.
+ *
+ * Holds a service name, a {@link SampleGate}, and a {@link SignalChannel}.
+ * {@link open} is the sole entry point; {@link channel} exposes the stream for
+ * sinks to drain.
+ */
+export declare class Recorder {
+    /** Logical service/agent name stamped onto admitted root traces. */
+    readonly serviceName: string;
+    private readonly gate;
+    private readonly signalChannel;
+    constructor(options: RecorderOptions);
+    /**
+     * Open a segment, subject to sampling.
+     *
+     * Resolves the trace id (a supplied `opts.traceId` joins an existing trace; a
+     * root mints a fresh one), then consults the {@link SampleGate}. Sampled out →
+     * the frozen {@link NOOP_HANDLE} (nothing is emitted). Sampled in → a live
+     * {@link SegmentHandle} from {@link openHandle}, whose `open` signal — and all
+     * subsequent `update`/`close` signals — land on this recorder's channel. A
+     * root open also folds `serviceName` into the segment's attributes.
+     */
+    open(kind: SegmentKind, name: string, opts?: OpenOptions): SegmentHandle;
+    /**
+     * The recorder's signal stream.
+     *
+     * Sinks drain this with `for await … of recorder.channel()`. It is the same
+     * underlying {@link SignalChannel} every {@link open}ed handle emits onto.
+     */
+    channel(): SignalChannel;
+}

package/dist/types/tracing/recorder/sampling.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Trace admission control: the {@link SampleGate}.
+ *
+ * A {@link Recorder} consults a gate once per `open` to decide whether a new
+ * trace is recorded at all. Three strategies cover the useful spectrum:
+ *
+ * - `"always"` — admit everything (the default; good for dev/diagnostics).
+ * - `"never"`  — admit nothing (a kill-switch that keeps call sites intact).
+ * - `{ ratio }` — admit a deterministic fraction in `[0, 1]`, keyed by the
+ *   trace id, so the *same* trace id always yields the *same* verdict. This is
+ *   ratio sampling without a random draw: the decision is reproducible across
+ *   processes and replays, and a child opened on an admitted trace id is itself
+ *   admitted (the whole trace is consistently in or out).
+ *
+ * The ratio hash is a small, dependency-free FNV-1a over the trace id's bytes,
+ * folded to a unit fraction. It is *not* cryptographic — it only needs to spread
+ * hex trace ids roughly uniformly across `[0, 1)`, which FNV-1a does well enough
+ * for sampling. (Trace ids are themselves minted from `node:crypto`, so the
+ * input is already high-entropy.)
+ */
+/** A deterministic ratio strategy: admit a fraction `ratio ∈ [0, 1]` of traces. */
+export interface RatioStrategy {
+    readonly ratio: number;
+}
+/**
+ * How a {@link SampleGate} decides admission.
+ *
+ * `"always"`/`"never"` are constant verdicts; `{ ratio }` is a per-trace-id
+ * deterministic fraction.
+ */
+export type SampleStrategy = "always" | "never" | RatioStrategy;
+/**
+ * Admission control for traces.
+ *
+ * Construct with a {@link SampleStrategy} and call {@link decide} with a trace
+ * id; the verdict is constant for `"always"`/`"never"` and deterministic per id
+ * for a ratio. A gate holds no mutable state, so a single instance is safely
+ * shared across recorders and threads of execution.
+ */
+export declare class SampleGate {
+    private readonly strategy;
+    /** Pre-clamped admission threshold for the ratio strategy; unused otherwise. */
+    private readonly threshold;
+    constructor(strategy?: SampleStrategy);
+    /**
+     * Decide whether the trace identified by `traceId` is admitted.
+     *
+     * - `"always"` → always `true`.
+     * - `"never"`  → always `false`.
+     * - `{ ratio }` → `unitHash(traceId) < ratio` (clamped): deterministic, so the
+     *   same id always yields the same answer. Ratio `0` admits nothing and ratio
+     *   `1` admits everything regardless of the hash.
+     */
+    decide(traceId: string): boolean;
+}

package/dist/types/tracing/redaction/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Redaction layer — attribute scrubbing before trace data leaves the process.
+ *
+ * Re-exports the {@link SecretScrubber} processor along with its default rule
+ * set and redaction token, so sinks can sanitize segment attributes without
+ * reaching into the module directly.
+ */
+export * from "./secret-scrubber";

package/dist/types/tracing/redaction/secret-scrubber.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Attribute scrubbing: the {@link SecretScrubber} segment-attribute processor.
+ *
+ * Trace attributes are an open `Record<string, unknown>` bag — callers stash
+ * request payloads, tool arguments, headers, and model parameters in there, and
+ * any of those can carry a credential. Before a {@link import('../signal/segment').Segment}'s
+ * attributes leave the process (persisted by a sink, printed to a console), this
+ * processor walks the whole bag and replaces anything that looks secret with an
+ * inert {@link REDACTION_TOKEN}.
+ *
+ * Two independent signals trigger a redaction:
+ *
+ * - **Key shape** — the *path key* matches a {@link SecretPattern} (e.g. a field
+ *   literally named `api_key`, `authorization`, `password`). The value is
+ *   redacted regardless of what it is.
+ * - **Value shape** — a *string value* matches a pattern (e.g. a `Bearer …`
+ *   token or a `sk-…` style key) even when its key looks innocuous.
+ *
+ * The walk is a single iterative pass over an explicit work stack rather than a
+ * recursive per-field branch cascade: every node (object, array, leaf) is
+ * pushed once and handled by one uniform loop body, so arbitrarily nested
+ * structures cost no extra call frames and there is no field-by-field `if`
+ * ladder to maintain. The vocabulary is deliberately our own — `SecretScrubber`
+ * and a guillemet redaction token, not an OTel "attribute processor" emitting
+ * `[REDACTED]`.
+ */
+/**
+ * A rule that flags a secret.
+ *
+ * `key` matches against the *name* of a field on the current path; `value`
+ * matches against a *string* leaf. A pattern provides at least one of the two.
+ * Patterns are tested with {@link RegExp.test}, so a global (`/g`) flag would
+ * make matching stateful — supply non-global expressions.
+ */
+export interface SecretPattern {
+    /** Human label, useful when reasoning about which rule fired. */
+    readonly label: string;
+    /** Matches a field/key name on the attribute path. */
+    readonly key?: RegExp;
+    /** Matches a string leaf value. */
+    readonly value?: RegExp;
+}
+/** The inert string that replaces any redacted value. Not `[REDACTED]`. */
+export declare const REDACTION_TOKEN = "\u2039redacted\u203A";
+/**
+ * The built-in rule set. Fresh wording — these are not lifted from any existing
+ * processor's defaults. Tuned to catch the common shapes that show up in agent
+ * trace attributes without being so broad they swallow ordinary text.
+ */
+export declare const DEFAULT_SECRET_PATTERNS: readonly SecretPattern[];
+/** Construction options for a {@link SecretScrubber}. */
+export interface SecretScrubberOptions {
+    /** Override the default rule set entirely. Defaults to {@link DEFAULT_SECRET_PATTERNS}. */
+    readonly patterns?: readonly SecretPattern[];
+    /** Override the replacement string. Defaults to {@link REDACTION_TOKEN}. */
+    readonly token?: string;
+}
+/**
+ * A configurable, OTel-free attribute processor that redacts secret-looking
+ * keys and values from a trace attribute bag.
+ *
+ * Stateless across calls and safe to share: {@link scrub} never mutates its
+ * input and produces a fresh structure each time.
+ */
+export declare class SecretScrubber {
+    private readonly patterns;
+    private readonly token;
+    /** Pre-split views so the hot loop never re-checks which rules have a key/value side. */
+    private readonly keyRules;
+    private readonly valueRules;
+    constructor(options?: SecretScrubberOptions);
+    /** True when a field name matches any key-shaped rule. */
+    private keyIsSecret;
+    /** True when a string leaf matches any value-shaped rule. */
+    private valueIsSecret;
+    /**
+     * Decide a leaf's sanitized form given the key that points at it.
+     *
+     * Redacts when the key looks secret, or when a string value looks secret.
+     * Non-string leaves under an innocuous key pass through untouched.
+     */
+    private sanitizeLeaf;
+    /**
+     * Return a deep copy of `attributes` with secret-looking keys and values
+     * replaced by the redaction token.
+     *
+     * Walks the structure with a single explicit stack (no recursion). Containers
+     * are cloned shallowly up front and their children enqueued; leaves are
+     * resolved through {@link sanitizeLeaf}. The input — including nested objects
+     * and arrays — is never mutated. A key whose name is itself secret short-
+     * circuits the descent: the whole subtree under it collapses to the token,
+     * so credentials nested inside (e.g. `auth: { token: … }`) cannot leak.
+     */
+    scrub(attributes: Record<string, unknown>): Record<string, unknown>;
+}

package/dist/types/tracing/registry/hub.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The recorder registry: a {@link TelemetryHub}.
+ *
+ * Where a {@link Recorder} traces one service, an application usually wants a
+ * handful — one per agent, subsystem, or tenant — addressable by name without
+ * threading instances through every call site. The hub is that lookup: a small
+ * named map of recorders with a designated default.
+ *
+ * This is the homegrown analogue of an OTel "tracer provider" registry, minus
+ * the global ambient machinery: a hub is an ordinary object you can construct,
+ * pass around, and replace. A module-level *process default* is offered for
+ * convenience ({@link getDefaultHub}/{@link setDefaultHub}) but is strictly
+ * opt-in — nothing here reads it implicitly.
+ */
+import { Recorder, type RecorderOptions } from "../recorder/recorder";
+/**
+ * A named registry of {@link Recorder}s.
+ *
+ * {@link register} adds (or replaces) a recorder under a name and returns it;
+ * {@link recorder} looks one up (falling back to the default when called with no
+ * name); {@link getDefault} returns the default recorder if one exists. The
+ * *first* recorder registered becomes the default unless a later
+ * {@link register} explicitly uses the reserved default name.
+ */
+export declare class TelemetryHub {
+    private readonly recorders;
+    /** Name of the recorder returned by {@link recorder} with no argument. */
+    private defaultName;
+    /**
+     * Register a recorder under `name`, returning the constructed instance.
+     *
+     * Re-registering a name replaces the prior recorder. If no default has been
+     * chosen yet, the first registration becomes the default; registering under
+     * the reserved `"default"` name always (re)designates the default.
+     */
+    register(name: string, options: RecorderOptions): Recorder;
+    /**
+     * Look up a recorder by `name`, or the default when `name` is omitted.
+     *
+     * Throws if the requested (or default) recorder is not registered, so a
+     * missing recorder fails loudly rather than silently dropping traces.
+     */
+    recorder(name?: string): Recorder;
+    /** The default recorder, or `undefined` if none has been registered. */
+    getDefault(): Recorder | undefined;
+    /** Whether a recorder is registered under `name`. */
+    has(name: string): boolean;
+}
+/**
+ * The process-wide default {@link TelemetryHub}, created on first access.
+ *
+ * A convenience for code that has no hub to hand. Purely opt-in: nothing in this
+ * subsystem consults it unless a caller does.
+ */
+export declare function getDefaultHub(): TelemetryHub;
+/** Replace the process-wide default {@link TelemetryHub} (e.g. for tests). */
+export declare function setDefaultHub(hub: TelemetryHub): void;

package/dist/types/tracing/registry/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The registry layer — public surface.
+ *
+ * The {@link TelemetryHub} named-recorder registry plus the opt-in process
+ * default accessors {@link getDefaultHub}/{@link setDefaultHub}.
+ */
+export { TelemetryHub, getDefaultHub, setDefaultHub } from "./hub";

package/dist/types/tracing/signal/handle.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The behavioural face of a segment: a functional {@link SegmentHandle}.
+ *
+ * Where {@link Segment} is the immutable data, a {@link SegmentHandle} is the
+ * small bag of closures a caller actually uses — `note`, `child`, `fail`,
+ * `close`. Each operation derives the next frozen segment value and emits a
+ * {@link TraceSignal} onto an injected `sink`. There is intentionally **no
+ * class hierarchy**: a sampled-in handle is a plain object of closures built by
+ * {@link openHandle}, and a sampled-out handle is the single frozen
+ * {@link NOOP_HANDLE} value implementing the same shape with empty methods — not
+ * a subclass, not a separate `NoopSegment` type.
+ *
+ * The handle keeps the segment's *current* value in a closed-over variable so
+ * that `note`/`fail` can derive successive values; this is the only mutable
+ * state in the module and it never escapes — callers only ever see immutable
+ * {@link Segment}/{@link TraceRecord} values via the emitted signals.
+ */
+import type { TraceSignal } from "../channel/signal";
+import { type SegmentKind } from "./segment";
+/** A consumer of trace signals — typically a {@link import('../channel/signal').SignalChannel}'s `emit`. */
+export type SignalSink = (signal: TraceSignal) => void;
+/**
+ * The functional handle over a single in-flight segment.
+ *
+ * `note`, `child`, and `fail` are no-ops after `close`; `close` itself is
+ * idempotent (the first call wins, later calls do nothing). This makes the
+ * happy path forgiving of double-close in `finally` blocks.
+ */
+export interface SegmentHandle {
+    /** The trace this handle's segment belongs to. Hex; stable across the trace. */
+    readonly traceId: string;
+    /** This segment's own id. Hex. `""` for the {@link NOOP_HANDLE}. */
+    readonly id: string;
+    /** Whether this handle does real work (`true`) or is the sampled-out no-op. */
+    readonly active: boolean;
+    /** Amend the segment's attributes; emits an `update` signal. */
+    note(attributes: Readonly<Record<string, unknown>>): void;
+    /** Open a child segment under this one, sharing the trace; returns its handle. */
+    child(kind: SegmentKind, name: string): SegmentHandle;
+    /** Record a failure (sets the closing status to `error`). Does not close. */
+    fail(error: unknown): void;
+    /** Close the segment; emits a `close` signal carrying the {@link TraceRecord}. */
+    close(status?: "ok" | "error"): void;
+}
+/** Inputs for opening a real, sampled-in handle. */
+export interface OpenHandleInput {
+    readonly kind: SegmentKind;
+    readonly name: string;
+    /** Trace to join; a fresh trace id is minted when omitted (a root). */
+    readonly traceId?: string;
+    /** Enclosing segment id, or `null`/omitted for a root. */
+    readonly parentId?: string | null;
+    /** Initial attributes. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Open a live segment and return its functional handle.
+ *
+ * Immediately emits an `open` {@link TraceSignal} carrying the fresh frozen
+ * {@link Segment}. Subsequent `note`/`fail`/`close` derive successive frozen
+ * values and emit `update`/`close` signals through the same `sink`. Children
+ * inherit `traceId` and are parented to this segment, and share the `sink`.
+ */
+export declare function openHandle(input: OpenHandleInput, sink: SignalSink): SegmentHandle;
+/**
+ * The single shared sampled-out handle.
+ *
+ * A frozen no-op object satisfying {@link SegmentHandle}: it emits nothing,
+ * allocates nothing per call, and returns *itself* from `child` so an entire
+ * sampled-out subtree costs nothing. This is the whole "noop" story — there is
+ * no `NoopSegment` class to subclass.
+ */
+export declare const NOOP_HANDLE: SegmentHandle;

package/dist/types/tracing/signal/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The signal layer — public surface.
+ *
+ * The immutable {@link Segment} data model and its terminal {@link TraceRecord},
+ * the value constructors/derivations ({@link openSegment}/{@link withAttributes}/
+ * {@link closeSegment}) and id minting, plus the functional {@link SegmentHandle}
+ * with its sampled-in factory {@link openHandle} and shared {@link NOOP_HANDLE}.
+ */
+export type { Segment, SegmentKind, SegmentStatus, SegmentError, TraceRecord, OpenSegmentInput, } from "./segment";
+export { openSegment, withAttributes, closeSegment, freshId, freshTraceId, freshSegmentId, } from "./segment";
+export type { SegmentHandle, SignalSink, OpenHandleInput } from "./handle";
+export { openHandle, NOOP_HANDLE } from "./handle";

package/dist/types/tracing/signal/segment.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The unit of trace data: an immutable {@link Segment} value.
+ *
+ * A {@link Segment} is a plain, frozen value object — never a class instance and
+ * never mutated in place. The lifecycle (open → note → close) is expressed by
+ * *producing new* segment values rather than by toggling fields on a live
+ * object, which keeps the data model trivially serializable and free of the
+ * `BaseSpan`/`DefaultSpan`/`NoopSpan` inheritance shape. The behavioural side —
+ * the open/note/close operations a caller actually invokes — lives entirely in
+ * {@link SegmentHandle} (see `./handle`).
+ *
+ * The vocabulary here is deliberately distinct from the OpenTelemetry "span"
+ * lineage: an entity kind is a {@link SegmentKind} (`run`/`inference`/`action`/
+ * `recall`/`custom`), and the exported, closed form is a {@link TraceRecord}.
+ */
+/**
+ * The kind of work a segment records.
+ *
+ * - `run`       — a whole agent run / top-level invocation.
+ * - `inference` — a single model/LLM call.
+ * - `action`    — a tool or side-effecting action execution.
+ * - `recall`    — a memory / retrieval operation.
+ * - `custom`    — anything a caller wants to time that does not fit above.
+ */
+export type SegmentKind = "run" | "inference" | "action" | "recall" | "custom";
+/** The lifecycle status of a segment. `open` until closed; then `ok` or `error`. */
+export type SegmentStatus = "open" | "ok" | "error";
+/** A captured failure attached to a segment. Intentionally minimal and serializable. */
+export interface SegmentError {
+    readonly message: string;
+}
+/**
+ * An immutable trace segment.
+ *
+ * Every field is `readonly`; the value is frozen at construction (see
+ * {@link openSegment}). Transitions are modelled as *new* frozen values derived
+ * from a prior one ({@link withAttributes}, {@link closeSegment}) — there is no
+ * in-place mutation anywhere in this module.
+ */
+export interface Segment {
+    /** Stable identifier for this segment, unique within its trace. Hex. */
+    readonly id: string;
+    /** Identifier of the trace this segment belongs to. Shared by all kin. Hex. */
+    readonly traceId: string;
+    /** The enclosing segment's `id`, or `null` for a trace root. */
+    readonly parentId: string | null;
+    /** What kind of work this segment records. */
+    readonly kind: SegmentKind;
+    /** Human-readable label for the segment. */
+    readonly name: string;
+    /** Wall-clock start, in epoch milliseconds. */
+    readonly startedAt: number;
+    /** Wall-clock end, in epoch milliseconds; `null` while still open. */
+    readonly endedAt: number | null;
+    /** Lifecycle status. */
+    readonly status: SegmentStatus;
+    /** Arbitrary structured annotations; a frozen, read-only bag. */
+    readonly attributes: Readonly<Record<string, unknown>>;
+    /** Present only once a segment has failed. */
+    readonly error?: SegmentError;
+}
+/**
+ * The exported, serializable form of a *closed* segment.
+ *
+ * Structurally a {@link Segment} that is guaranteed terminal: `endedAt` is a
+ * number (not `null`) and `status` is no longer `open`. This is what a
+ * `close` signal carries and what sinks persist; it never appears for a segment
+ * still in flight.
+ */
+export interface TraceRecord extends Segment {
+    readonly endedAt: number;
+    readonly status: "ok" | "error";
+}
+/**
+ * Generate a fresh hex identifier of `byteLength` random bytes.
+ *
+ * Trace ids default to 16 bytes (128-bit) and segment ids to 8 bytes (64-bit),
+ * mirroring the W3C Trace Context sizing without depending on any OTel SDK.
+ */
+export declare function freshId(byteLength: number): string;
+/** A new 128-bit hex trace id. */
+export declare function freshTraceId(): string;
+/** A new 64-bit hex segment id. */
+export declare function freshSegmentId(): string;
+/** Inputs for opening a fresh segment. Missing ids/clock are generated/sampled. */
+export interface OpenSegmentInput {
+    readonly kind: SegmentKind;
+    readonly name: string;
+    /** Trace to join. Omit on a root to mint a fresh trace id. */
+    readonly traceId?: string;
+    /** Enclosing segment id, or `null`/omitted for a root. */
+    readonly parentId?: string | null;
+    /** Pre-assigned segment id; one is minted when omitted. */
+    readonly id?: string;
+    /** Initial annotations. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    /** Start clock override (epoch ms); `Date.now()` when omitted. */
+    readonly startedAt?: number;
+}
+/**
+ * Construct a fresh, frozen, `open` {@link Segment}.
+ *
+ * Pure aside from id/clock defaulting: with all fields supplied it is
+ * deterministic. The returned value and its `attributes` bag are both frozen.
+ */
+export declare function openSegment(input: OpenSegmentInput): Segment;
+/**
+ * Derive a new frozen segment with `patch` merged over its attributes.
+ *
+ * Last-writer-wins on key collision. The original segment is untouched.
+ */
+export declare function withAttributes(segment: Segment, patch: Readonly<Record<string, unknown>>): Segment;
+/**
+ * Derive the terminal {@link TraceRecord} for an open segment.
+ *
+ * Stamps `endedAt` (defaulting to now), sets the final `status`, and — when the
+ * status is `error` — attaches `error` (a passed-in error wins over any already
+ * recorded one). Closing an already-closed segment is idempotent in spirit:
+ * the new end clock and status simply replace the prior terminal fields.
+ */
+export declare function closeSegment(segment: Segment, status: "ok" | "error", options?: {
+    readonly endedAt?: number;
+    readonly error?: SegmentError;
+}): TraceRecord;

package/dist/types/tracing/sinks/base.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The {@link Sink} contract: a consumer that drains a {@link SignalChannel}.
+ *
+ * A sink is the *terminal* end of the trace transport. Where a producer pushes
+ * {@link TraceSignal}s into a {@link SignalChannel} (via `emit`), a sink pulls
+ * them back out with `for await … of channel` and does something with them —
+ * print a line, append NDJSON, forward to an injected stream. There is no
+ * subscriber registration and no push: the sink owns its own pull loop and runs
+ * until the channel is closed and drained.
+ *
+ * This mirrors the layer's deliberate divergence from the OTel exporter shape:
+ * a sink is not an `Exporter` with `export(batch)` / `shutdown()`; it is a plain
+ * object with a single mandatory {@link Sink.drain} coroutine plus optional
+ * {@link Sink.flush}/{@link Sink.close} lifecycle hooks. Concrete sinks
+ * (`ConsoleSink`, `FileSink`, `StreamSink`) implement this interface.
+ */
+import type { SignalChannel } from "../channel/signal";
+/**
+ * A terminal consumer of a {@link SignalChannel}.
+ *
+ * Implementations iterate the channel to completion inside {@link drain},
+ * handling each {@link TraceSignal} as it arrives. {@link flush} and
+ * {@link close} are optional: a buffered sink overrides `flush` to force pending
+ * writes to their destination, and a sink that owns a resource (a file handle,
+ * a socket) overrides `close` to release it. A sink with no buffering and no
+ * owned resource needs neither.
+ */
+export interface Sink {
+    /**
+     * Pull every signal from `channel` and handle it, returning once the channel
+     * is closed and fully drained.
+     *
+     * Implemented as a `for await … of channel` loop. A sink is expected to call
+     * this once per channel; concurrent drains of the same channel are undefined
+     * because the channel is single-consumer.
+     */
+    drain(channel: SignalChannel): Promise<void>;
+    /**
+     * Force any buffered output to its destination without ending the sink.
+     *
+     * Optional — only buffered sinks need it. Safe to call repeatedly.
+     */
+    flush?(): Promise<void>;
+    /**
+     * Release any resource the sink owns (file handle, socket, …).
+     *
+     * Optional — only resource-owning sinks need it. Should be idempotent and is
+     * typically preceded by an implicit or explicit {@link flush}.
+     */
+    close?(): Promise<void>;
+}

package/dist/types/tracing/sinks/console.d.ts

@@ -0,0 +1,44 @@
+/**
+ * {@link ConsoleSink}: a human-facing sink that prints one tidy line per closed
+ * segment.
+ *
+ * It drains a {@link SignalChannel} and ignores `open`/`update` chatter,
+ * emitting a single formatted line only when a segment *closes* — i.e. on each
+ * {@link CloseSignal} / {@link TraceRecord}. The line carries the status, the
+ * segment kind and name, the wall-clock duration, and a short trace/segment id
+ * tag, e.g.:
+ *
+ * ```text
+ * ✓ inference  chat.completion        842ms  [a1b2c3d4/9f8e7d6c]
+ * ✗ action     write_file              12ms  [a1b2c3d4/0011aabb] — EACCES: permission denied
+ * ```
+ *
+ * Output goes through an injected `log` function (default `console.log`) so the
+ * sink stays testable and never reaches for a global directly beyond that
+ * default.
+ */
+import type { SignalChannel } from "../channel/signal";
+import type { Sink } from "./base";
+/** Tuning for a {@link ConsoleSink}. */
+export interface ConsoleSinkOptions {
+    /**
+     * Where formatted lines go. Defaults to `console.log`. Injected for tests and
+     * for routing to alternative loggers.
+     */
+    readonly log?: (line: string) => void;
+}
+/**
+ * A {@link Sink} that prints one line per closed segment to a `log` function.
+ *
+ * Stateless and resource-free: it owns no buffer and no handle, so it needs
+ * neither `flush` nor `close`. Constructing it does nothing until {@link drain}
+ * is awaited on a channel.
+ */
+export declare class ConsoleSink implements Sink {
+    private readonly log;
+    constructor(options?: ConsoleSinkOptions);
+    /** Render the one-line summary for a closed segment. */
+    private format;
+    /** Drain `channel`, printing a line for every `close` signal. */
+    drain(channel: SignalChannel): Promise<void>;
+}

package/dist/types/tracing/sinks/file.d.ts

@@ -0,0 +1,47 @@
+/**
+ * {@link FileSink}: persists closed segments as newline-delimited JSON.
+ *
+ * It drains a {@link SignalChannel} and, for every `close` signal, appends the
+ * carried {@link TraceRecord} as a single JSON line to a file. The result is an
+ * NDJSON log — one self-contained record per line — that downstream tools can
+ * stream-parse without loading the whole file.
+ *
+ * Writes go through `node:fs/promises` `appendFile`, which creates the file if
+ * absent and atomically appends otherwise. Records are buffered in memory and
+ * flushed in a single append either when the in-memory batch reaches
+ * `flushEvery` lines or when {@link flush}/{@link close} is called — so a busy
+ * trace is not one syscall per segment. Only `open`/`update` are ignored;
+ * everything persisted is a terminal record.
+ */
+import type { SignalChannel } from "../channel/signal";
+import type { Sink } from "./base";
+/** Tuning for a {@link FileSink}. */
+export interface FileSinkOptions {
+    /**
+     * How many records to accumulate before an automatic append. Defaults to 1
+     * (append each record as it closes). Larger values trade latency for fewer
+     * syscalls; any remainder is flushed on {@link flush}/{@link close}.
+     */
+    readonly flushEvery?: number;
+}
+/**
+ * A {@link Sink} that appends each closed segment to a path as NDJSON.
+ *
+ * Owns an in-memory pending batch (hence a meaningful {@link flush}) but no live
+ * OS handle — each write opens, appends, and closes via `fs/promises`. {@link drain}
+ * flushes whatever remains when the channel ends, and {@link close} is a final
+ * flush.
+ */
+export declare class FileSink implements Sink {
+    private readonly path;
+    private readonly flushEvery;
+    /** Serialized records awaiting their append, oldest first. */
+    private pending;
+    constructor(path: string, options?: FileSinkOptions);
+    /** Drain `channel`, buffering each closed record and flushing on threshold/end. */
+    drain(channel: SignalChannel): Promise<void>;
+    /** Append all pending records to the file as NDJSON lines, then clear them. */
+    flush(): Promise<void>;
+    /** Flush any remaining records. Idempotent; the sink holds no OS handle. */
+    close(): Promise<void>;
+}