@lunora/do 1.0.0-alpha.34 → 1.0.0-alpha.35

package/dist/index.d.mts

@@ -2165,6 +2165,227 @@ declare const recordAuthEvent: (sql: SqlExec, input: RecordAuthEventInput) => vo
  * throwing. `failureRate` is derived here so the consumer needn't recompute it.
  */
 declare const readAuthMetrics: (sql: SqlExec) => AuthMetrics;
+/**
+ * Shared, bundler-inlined helpers for the structured `fields` a
+ * `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call carries.
+ *
+ * Inlined (like {@link file://./otlp.ts}) so `@lunora/do`, `@lunora/runtime`,
+ * `@lunora/config`, and `@lunora/studio` — which sit on different tiers with no
+ * acceptable runtime dependency edge between them — share ONE implementation of
+ * field rendering/normalization instead of the byte-identical copies they would
+ * otherwise hand-mirror. Keep this genuinely zero-dependency (only built-ins) so
+ * inlining into each `dist` stays sound.
+ */
+/** Structured, filterable key/value fields attached to a `ctx.log` line. */
+type LogFields = Record<string, unknown>;
+/**
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
+ *
+ * - `counter` — a monotonic delta to add up (requests, retries, bytes sent).
+ * - `gauge` — a point-in-time reading that replaces the last one (queue depth,
+ *   cache size).
+ * - `histogram` — a value whose *distribution* matters (latency, payload size),
+ *   giving percentiles rather than just a mean.
+ */
+type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * One measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
+ */
+interface MetricEvent {
+  /**
+   * Structured attributes the caller attached, normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
+   * dimensions — keep them low-cardinality; an id-valued attribute creates a
+   * distinct time series per id.
+   *
+   * Caller-controlled, so they MAY contain user input and they DO egress to
+   * whatever destination the sink ships to — the same caveat as a log line's
+   * `fields` and a span's `error.message`. Scrub upstream if that matters.
+   */
+  attributes?: LogFields;
+  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
+  functionPath: string;
+  /** Instrument kind; see {@link MetricKind}. */
+  kind: MetricKind;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Wall-clock millis when the measurement was recorded. */
+  ts: number;
+  /**
+   * The measured value: the increment for a `counter`, the current reading for
+   * a `gauge`, the observed sample for a `histogram`.
+   */
+  value: number;
+}
+/**
+ * One span produced by a `ctx.trace(name, fn)` call, or the synthetic root span
+ * the shard records for the dispatch itself so a waterfall has a bar to hang
+ * its children under.
+ *
+ * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
+ * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
+ * no reformatting.
+ */
+interface SpanEvent {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * Populated when the span body threw. `type` is the error's constructor name
+   * (or its `LunoraError` code); `message` is the human-readable string and may
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
+  error?: {
+    message: string;
+    type: string;
+  };
+  /**
+   * Function path the span was created under, e.g. `"messages:list"`. A span
+   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
+   * `runAction` carries the OUTER entrypoint's path, since the composed call
+   * reuses its context — the same attribution rule `ctx.log` follows.
+   */
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+ * Structural shape of the `ctx.trace` span factory (see the server
+ * `LunoraTracer`). Declared here rather than imported so `@lunora/do` takes no
+ * dependency on `@lunora/server`; a cross-package assignability guard in
+ * `@lunora/testing` fails the build if the two drift apart.
+ */
+type ContextTracer = <T>(name: string, function_: (trace: ContextTracer) => Promise<T> | T, attributes?: LogFields) => Promise<T>;
+/** Structural shape of the `ctx.metrics` recorder (see the server `LunoraMetrics`). */
+interface ContextMetrics {
+  count: (name: string, value?: number, attributes?: LogFields) => void;
+  gauge: (name: string, value: number, attributes?: LogFields) => void;
+  record: (name: string, value: number, attributes?: LogFields) => void;
+}
+/** The trace a ctx's spans hang off: the shared id, and the span they parent to. */
+interface TraceAnchor {
+  rootSpanId: string;
+  traceId: string;
+}
+/** What {@link createTracer} needs from the shard to build a span. */
+interface TracerDeps {
+  /** The trace this ctx's spans belong to. */
+  anchor: TraceAnchor;
+  /** Function path the spans are attributed to. */
+  functionPath: string;
+  /** Hand a finished span to the buffer + sink. */
+  record: (span: SpanEvent) => void;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey: string | undefined;
+  /** Read lazily — the acting user is resolved per span, not per ctx. */
+  userId: () => string | undefined;
+}
+/** What {@link createMetrics} needs from the shard to build a measurement. */
+interface MetricsDeps {
+  functionPath: string;
+  record: (event: MetricEvent) => void;
+  shardKey: string | undefined;
+}
+/**
+ * Build the `ctx.trace` span factory for one dispatched function.
+ *
+ * **Nesting is explicit, not ambient.** Each span's body receives a tracer bound
+ * to that span; calling it is what makes a child. An earlier design kept an
+ * ambient stack of "the currently open span" and parented to its top, which
+ * reads nicer but is unfixably wrong under concurrency: in
+ * `Promise.all([trace("a", …), trace("b", …)])`, `b` starts while `a` is on the
+ * stack and is recorded as a *child* of `a` rather than its sibling — and
+ * parallel fan-out is one of the main things people reach for a tracer to
+ * measure. Distinguishing "called inside a's body" from "called concurrently
+ * with a" needs `AsyncLocalStorage`, which this package deliberately avoids (see
+ * `dependency-tracker.ts` — shard DOs run under a slimmer compat profile than
+ * `nodejs_compat`). So the parent is threaded, exactly like the dependency
+ * tracker and the subscription identity: correct in every case, and visible at
+ * the call site.
+ *
+ * The anchor is passed in for the same reason. `ShardDO.currentRequestTrace` is
+ * cleared in the dispatch `finally`, and a subscription re-run builds its ctx
+ * during* the writing mutation's flush — so reading that shared field at span
+ * time would file the re-run's spans under the mutation's trace.
+ */
+declare const createTracer: (deps: TracerDeps) => ContextTracer;
+/**
+ * Build the `ctx.metrics` recorder for one dispatched function.
+ *
+ * Deliberately stateless: each call emits one measurement rather than
+ * accumulating into a per-dispatch map. Pre-aggregating here would have to pick a
+ * flush point and a merge rule per instrument kind (sum a counter, last-wins a
+ * gauge, and a histogram cannot be merged at all without losing the
+ * distribution) — so the runtime stays a transport and the collector, which is
+ * built for exactly this, does the aggregation.
+ */
+declare const createMetrics: (deps: MetricsDeps) => ContextMetrics;
+/**
+ * Build the synthetic root span for a finished dispatch — the bar the studio's
+ * waterfall hangs a request's `ctx.trace` spans under.
+ *
+ * Pure: the caller decides whether to record it (only when the dispatch actually
+ * produced spans) and where to put it. It is never routed to `sink.onSpan`,
+ * because the runtime already emits the dispatch to `onRpc` and a collector would
+ * otherwise show it twice.
+ */
+declare const dispatchRootSpan: (input: {
+  anchor: TraceAnchor;
+  durationMs: number;
+  failure: {
+    thrown: unknown;
+  } | undefined;
+  functionPath: string;
+  shardKey: string | undefined;
+  startTs: number;
+  userId: string | undefined;
+}) => SpanEvent;
 /** Reserved table the per-shard runner tracks migration progress in. Auto-hidden from the data browser by the `__lunora` prefix. */
 declare const DATA_MIGRATION_STATE_TABLE = "__lunora_migrations";
 type MigrationDirection = "down" | "up";
@@ -2553,6 +2774,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getFanoutMetrics: "__lunora_admin__:getFanoutMetrics";
   readonly getFunctionStats: "__lunora_admin__:getFunctionStats";
   readonly getIssues: "__lunora_admin__:getIssues";
+  readonly getMetricSeries: "__lunora_admin__:getMetricSeries";
   readonly listSubscriptions: "__lunora_admin__:listSubscriptions";
   readonly listTableIndexes: "__lunora_admin__:listTableIndexes";
   readonly getLogs: "__lunora_admin__:getLogs";
@@ -2562,6 +2784,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getRequestLog: "__lunora_admin__:getRequestLog";
   readonly getSecurityAudit: "__lunora_admin__:getSecurityAudit";
   readonly getSettings: "__lunora_admin__:getSettings";
+  readonly getTraces: "__lunora_admin__:getTraces";
   readonly getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus";
   readonly importShard: "__lunora_admin__:importShard";
   readonly listFlags: "__lunora_admin__:listFlags";
@@ -3316,8 +3539,62 @@ declare const readFunctionMetricsTotals: (sql: SqlExec) => {
   errors: number;
   requests: number;
 };
-/** Severity of a buffered log entry, mirroring the usual console levels. */
-type LogLevel = "debug" | "error" | "info" | "warn";
+/**
+ * Severity of a `ctx.log.*` call. The five console method names (`log` is the
+ * default level, distinct from `info`) plus `trace`/`fatal`, so the logger spans
+ * the full OpenTelemetry severity ramp (`trace`→`fatal`).
+ */
+type ContextLogLevel = "debug" | "error" | "fatal" | "info" | "log" | "trace" | "warn";
+/**
+ * Per-event context handed to a sink alongside the event: lets a sink register
+ * background work (a telemetry POST, a durable pipeline send) with the request's
+ * `waitUntil` so it survives isolate teardown after the response returns. Absent
+ * `waitUntil` (no request context) means the sink falls back to fire-and-forget.
+ */
+interface LogSinkContext {
+  /** Keep a background promise alive past the response (the request's `waitUntil`). */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * One application log line emitted from a function handler via `ctx.log`.
+ * Produced per `ctx.log.*` call (unlike a per-dispatch RPC summary).
+ */
+interface LogEvent {
+  /** Raw arguments passed to the `ctx.log.*` call, in order. */
+  args: unknown[];
+  /**
+   * Structured fields the caller attached (`ctx.log.info(message, fields)` or a
+   * bound `ctx.log.with(fields)` child), already normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). Absent for a plain
+   * console-style call.
+   */
+  fields?: LogFields;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Display string — the message, or the console-style args rendered and space-joined. */
+  message: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Span id of the RPC this line was emitted under (trace correlation), or absent. */
+  spanId?: string;
+  /** Trace id this line belongs to (from the inbound `traceparent`), or absent. */
+  traceId?: string;
+  /** Wall-clock millis when the line was emitted. */
+  ts: number;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+ * Severity of a buffered log entry — the full seven-tier `ctx.log` ramp
+ * (`trace`→`fatal`), not a console-shaped subset. The buffer used to fold the
+ * ramp onto four tiers, which made `trace` and `fatal` lines indistinguishable
+ * from `debug` and `error` in the Studio Logs panel; it now stores the level the
+ * caller actually logged at. Container-lifecycle entries only ever use
+ * `info`/`error`, which remain part of the union.
+ */
+type LogLevel = ContextLogLevel;
 /**
  * One buffered log line. `functionPath` is the RPC that produced it (when the
  * entry came from the RPC dispatch site); `timestamp` is `Date.now()` at the
@@ -3327,7 +3604,7 @@ type LogLevel = "debug" | "error" | "info" | "warn";
  */
 interface LogEntry {
   exitCode?: number;
-  /** Structured fields from a `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call, when present. */
+  /** Structured fields from a `ctx.log.&lt;level>(message, fields)` / `ctx.log.with(fields)` call, when present. */
   fields?: Record<string, unknown>;
   functionPath?: string;
   instance?: string;
@@ -3653,66 +3930,6 @@ declare const resolveRelationPredicates: (where: WhereInput | undefined, options
  * schema's shard modes are both in hand).
  */
 declare const assertShapeShardable: (effectiveWhere: WhereInput | undefined, schema: ResolveContext["schema"], table: string) => void;
-/**
- * Shared, bundler-inlined helpers for the structured `fields` a
- * `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call carries.
- *
- * Inlined (like {@link file://./otlp.ts}) so `@lunora/do`, `@lunora/runtime`,
- * `@lunora/config`, and `@lunora/studio` — which sit on different tiers with no
- * acceptable runtime dependency edge between them — share ONE implementation of
- * field rendering/normalization instead of the byte-identical copies they would
- * otherwise hand-mirror. Keep this genuinely zero-dependency (only built-ins) so
- * inlining into each `dist` stays sound.
- */
-/** Structured, filterable key/value fields attached to a `ctx.log` line. */
-type LogFields = Record<string, unknown>;
-/**
- * Severity of a `ctx.log.*` call. The five console method names (`log` is the
- * default level, distinct from `info`) plus `trace`/`fatal`, so the logger spans
- * the full OpenTelemetry severity ramp (`trace`→`fatal`).
- */
-type ContextLogLevel = "debug" | "error" | "fatal" | "info" | "log" | "trace" | "warn";
-/**
- * Per-event context handed to a sink alongside the event: lets a sink register
- * background work (a telemetry POST, a durable pipeline send) with the request's
- * `waitUntil` so it survives isolate teardown after the response returns. Absent
- * `waitUntil` (no request context) means the sink falls back to fire-and-forget.
- */
-interface LogSinkContext {
-  /** Keep a background promise alive past the response (the request's `waitUntil`). */
-  waitUntil?: (promise: Promise<unknown>) => void;
-}
-/**
- * One application log line emitted from a function handler via `ctx.log`.
- * Produced per `ctx.log.*` call (unlike a per-dispatch RPC summary).
- */
-interface LogEvent {
-  /** Raw arguments passed to the `ctx.log.*` call, in order. */
-  args: unknown[];
-  /**
-   * Structured fields the caller attached (`ctx.log.info(message, fields)` or a
-   * bound `ctx.log.with(fields)` child), already normalized to a fresh bag of
-   * JSON-safe primitives (see `shared/log-fields.ts`). Absent for a plain
-   * console-style call.
-   */
-  fields?: LogFields;
-  /** Function path that emitted the line, e.g. `"messages:list"`. */
-  functionPath: string;
-  /** Severity the line was logged at. */
-  level: ContextLogLevel;
-  /** Display string — the message, or the console-style args rendered and space-joined. */
-  message: string;
-  /** Shard key for single-shard calls; absent for the unnamed root DO. */
-  shardKey?: string;
-  /** Span id of the RPC this line was emitted under (trace correlation), or absent. */
-  spanId?: string;
-  /** Trace id this line belongs to (from the inbound `traceparent`), or absent. */
-  traceId?: string;
-  /** Wall-clock millis when the line was emitted. */
-  ts: number;
-  /** Acting userId, or absent when anonymous. */
-  userId?: string;
-}
 /**
  * The `ctx.log` event contract (shape + severity union) lives in
  * `shared/log-event.ts` (inlined into each `dist`) so the DO that builds these
@@ -3971,15 +4188,22 @@ declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown
  * `@lunora/do` takes no dependency on `@lunora/runtime`; the event is the same
  * {@link LogEventInput} shape `emitLogEvent` consumes, built once per call.
  */
-interface LogSink {
+/**
+ * The sink surface the DO hands its three signals to: `ctx.log` lines, `ctx.trace`
+ * spans, and `ctx.metrics` measurements. Structurally compatible with
+ * `@lunora/runtime`'s `ObservabilitySink` without taking a dependency on it.
+ */
+interface TelemetrySink {
   onLog?: (event: LogEventInput, context?: LogSinkContext) => void;
+  onMetric?: (event: MetricEvent, context?: LogSinkContext) => void;
+  onSpan?: (event: SpanEvent, context?: LogSinkContext) => void;
 }
 /**
  * Structural shape of the `ctx.log` logger the DO builds (see the server
  * `LunoraLogger`). Declared locally so `@lunora/do` takes no dependency on
  * `@lunora/server`; the overloaded public method type lives there.
  */
-interface CtxLogger {
+interface ContextLogger {
   debug: (...args: unknown[]) => void;
   error: (...args: unknown[]) => void;
   fatal: (...args: unknown[]) => void;
@@ -3987,7 +4211,7 @@ interface CtxLogger {
   log: (...args: unknown[]) => void;
   trace: (...args: unknown[]) => void;
   warn: (...args: unknown[]) => void;
-  with: (fields: LogFields) => CtxLogger;
+  with: (fields: LogFields) => ContextLogger;
 }
 /**
  * Minimal projection of `DurableObjectState` that the ShardDO base requires.
@@ -4396,6 +4620,14 @@ declare abstract class ShardDO {
   private currentRequestIp;
   /** W3C `traceparent` of the inbound RPC; forwarded onto outbound container fetches. */
   private currentRequestTraceparent;
+  /**
+   * Trace ids for the in-flight dispatch, resolved once at entry (see
+   * {@link resolveTraceAnchor}). Shared by `ctx.trace` and by the synthetic
+   * root span recorded on the way out so both agree even with no inbound
+   * `traceparent`. Cleared in the same `finally` as the other per-request
+   * fields.
+   */
+  private currentRequestTrace;
   /**
    * Client-issued idempotency key for the in-flight mutation, forwarded via the
    * `x-lunora-mutation-id` header. When set, the dispatch path dedups the call
@@ -4593,6 +4825,19 @@ declare abstract class ShardDO {
    * "recent RPC errors on this instance" feed, not a general application log.
    */
   private readonly logs;
+  /**
+   * Recent `ctx.trace` spans (plus the synthetic per-dispatch root), powering
+   * the studio's Traces panel. In-memory and hibernation-volatile like
+   * `logs` — production tracing ships to a collector via `otlpSink`.
+   */
+  private readonly spans;
+  /**
+   * Running aggregates of `ctx.metrics.*` measurements, powering the studio's
+   * Metrics panel. In-memory and hibernation-volatile like `logs` and
+   * `spans`, but folds samples into per-series totals rather than ringing
+   * raw events — production aggregation ships to a collector via the sink.
+   */
+  private readonly metricSeries;
   /**
    * In-flight dependency tracker for the currently-executing query. Set by
    * `runCachedQuery` so the ctx-db hooks (wired via `onRead`) can
@@ -4816,6 +5061,15 @@ declare abstract class ShardDO {
    * container fetches carry it and the container's spans join the same trace.
    */
   protected getCurrentTraceparent(): string | undefined;
+  /**
+   * The in-flight dispatch's trace ids, for the generated `buildCtx` to hand to
+   * {@link makeTracer}. `undefined` outside a dispatch (an alarm, a lifecycle
+   * hook), where the tracer mints its own anchor.
+   */
+  protected getCurrentTrace(): {
+    rootSpanId: string;
+    traceId: string;
+  } | undefined;
   /**
    * Identity claims (email, name, roles, …) forwarded by the runtime's
    * `resolveIdentity` hook. Returns `undefined` for anonymous requests
@@ -5469,7 +5723,7 @@ declare abstract class ShardDO {
    * Unlike request-log args, `ctx.log` args are NOT redacted: the developer
    * chose to log them, exactly like a raw `console.log`.
    */
-  protected recordUserLog(functionPath: string, level: ContextLogLevel, args: unknown[], message: string, fields: Record<string, unknown> | undefined, sink?: LogSink): void;
+  protected recordUserLog(functionPath: string, level: ContextLogLevel, args: unknown[], message: string, fields: Record<string, unknown> | undefined, sink?: TelemetrySink): void;
   /**
    * Build the `ctx.log` logger for one dispatched function. Each severity method
    * accepts either the structured form (`(message, fields)`) or console-style
@@ -5477,7 +5731,59 @@ declare abstract class ShardDO {
    * stamps `fields` onto every line. The generated `buildCtx` calls this once
    * per dispatch and assigns the result to `ctx.log`.
    */
-  protected makeLogger(functionPath: string, sink?: LogSink, boundFields?: Record<string, unknown>): CtxLogger;
+  protected makeLogger(functionPath: string, sink?: TelemetrySink, boundFields?: Record<string, unknown>): ContextLogger;
+  /**
+   * Build the `ctx.trace` span factory for one dispatched function. The
+   * generated `buildCtx` calls this once per dispatch and assigns the result to
+   * `ctx.trace`.
+   *
+   * Thin wiring over {@link createTracer}, which owns the span semantics (see
+   * there for why nesting is explicit rather than ambient). Everything it needs
+   * from the shard is passed explicitly.
+   *
+   * `anchor` is the trace this ctx's spans belong to; omit it for a ctx with no
+   * owning dispatch (an alarm, a subscription re-run) to mint a fresh anchor, so
+   * `ctx.trace` still yields a coherent self-contained trace there.
+   */
+  protected makeTracer(functionPath: string, sink?: TelemetrySink, anchor?: TraceAnchor): ContextTracer;
+  /**
+   * Build the `ctx.metrics` recorder for one dispatched function. Thin wiring
+   * over {@link createMetrics}, which owns the instrument semantics.
+   */
+  protected makeMetrics(functionPath: string, sink?: TelemetrySink): ContextMetrics;
+  /**
+   * Fold one measurement into the in-memory {@link metricSeries} readout and
+   * hand it to the optional `sink.onMetric`. Best-effort like
+   * {@link recordUserLog} and {@link recordSpan}: recording a measurement must
+   * never break the handler that recorded it.
+   *
+   * The buffer folds rather than rings: a measurement's value is in its
+   * aggregate over a window, which a bounded ring of raw samples can't represent
+   * (it evicts the oldest samples, the ones a running total needs). So the
+   * buffer keeps one running aggregate per series and resets on hibernation like
+   * logs and spans — a "recent metrics on this instance" dev readout. Durable,
+   * cross-instance aggregation is still the sink's job.
+   */
+  protected recordMetric(event: MetricEvent, sink?: TelemetrySink): void;
+  /**
+   * Buffer the synthetic root span for a finished dispatch. The caller gates
+   * this on the dispatch having actually produced spans (the `hasTrace` check at
+   * the call site): every request minting a root would fill the bounded ring
+   * with single-bar traces from uninstrumented handlers and evict the
+   * instrumented ones the panel exists to show.
+   *
+   * `anchor` carries the dispatch's trace ids, captured at entry rather than
+   * read from `this` here — this runs after the handler's awaits, where the
+   * shared field may already belong to an interleaved dispatch.
+   */
+  private recordDispatchRootSpan;
+  /**
+   * Buffer one span for the studio Traces panel and hand it to the optional
+   * `sink.onSpan`. Best-effort throughout, exactly like {@link recordUserLog}:
+   * a span is recorded *after* its body already settled, so letting a telemetry
+   * failure escape here would turn a succeeded operation into a failed request.
+   */
+  protected recordSpan(span: SpanEvent, sink?: TelemetrySink): void;
   /**
    * Assemble the per-socket {@link LifecycleDispatchInfo} from its attachment:
    * the verified identity to replay and the {@link LifecycleEvent} the hooks
@@ -6588,6 +6894,11 @@ declare abstract class ShardDO {
   private deliverWhisperLocal;
   private readAttachment;
 }
+/**
+ * @deprecated Renamed to {@link TelemetrySink} — it carries spans and metrics as
+ * well as logs. Kept as an alias so existing import sites keep working.
+ */
+type LogSink = TelemetrySink;
 /** Conventional DO instance name, passed to `idFromName` to address the single registry instance. */
 declare const SHARD_REGISTRY_DO_NAME: string;
 /**
@@ -6745,4 +7056,4 @@ interface WhereSqlStrategy {
  * `undefined` when the input imposes no constraint (empty `where`).
  */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IncrementalMaterializeResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceCursorLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSoftDeleted, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, materializeExternalRowsIncremental, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceIncrementalTick, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type ContextMetrics, type ContextTracer, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IncrementalMaterializeResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MetricsDeps, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceCursorLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TelemetrySink, type TraceAnchor, type TracerDeps, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createMetrics, createShardCtxDb, createSystemReader, createTracer, decodeCursor, depKey, diffExternalSource, dispatchRootSpan, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSoftDeleted, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, materializeExternalRowsIncremental, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceIncrementalTick, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stableWireKey, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };