@lunora/do 1.0.0-alpha.45 → 1.0.0-alpha.46

package/dist/index.d.mts

@@ -2323,6 +2323,124 @@ interface MetricEvent {
    */
   value: number;
 }
+/**
+ * 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 {
+  /**
+   * Resolves this request's detected OTLP resource attributes (`service.version`,
+   * `cloud.region`, …) on demand, or absent when the host does not detect any.
+   *
+   * Deliberately a resolved, allowlisted bag behind a thunk rather than the raw
+   * `env` and `Request` the host detected them from: this context is fanned out
+   * to **every** registered sink, including user-authored ones, so anything
+   * reachable here should be assumed to end up in someone's debug log — and raw
+   * `env` is every secret binding, while a raw `Request` carries the caller's
+   * `Authorization` and `Cookie`. The thunk keeps detection lazy (a sink that
+   * does not want resource attributes pays nothing) and hosts are expected to
+   * memoize it per request.
+   */
+  resourceAttributes?: () => Record<string, boolean | number | string>;
+  /** 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[];
+  /**
+   * OTel `LogRecord.eventName` — set when the line was emitted as a **structured
+   * event** via `ctx.log.event(name, fields)` rather than as a human-readable
+   * log line.
+   *
+   * The distinction is the whole point of the Events API: a log line's payload
+   * is its `message` (prose, for a human, unstable), while an event's payload is
+   * its `fields` (a named schema, for a query, stable). A collector that knows
+   * `eventName` can index and aggregate the latter; without it, "how many
+   * checkouts failed" degrades into a substring search over prose.
+   *
+   * Absent for ordinary `ctx.log.*` calls.
+   */
+  eventName?: string;
+  /**
+   * 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 OTel `SpanKind` union, in the spec's own words rather than its wire
+ * numbers, so a call site reads `{ kind: "client" }` instead of `{ kind: 3 }`.
+ *
+ * Kind is not cosmetic: a service map is built from it. A CLIENT span with no
+ * matching SERVER span on the other side is a dropped hop; PRODUCER/CONSUMER is
+ * what makes a queue render as an async edge rather than a synchronous call.
+ * Getting it wrong is why "everything is INTERNAL" traces produce no topology.
+ */
+type OtlpSpanKind = "client" | "consumer" | "internal" | "producer" | "server";
+/**
+ * One timestamped occurrence inside a span — OTel's `Span.events`.
+ *
+ * The right shape for something that has a moment but no duration: a retry, a
+ * cache miss, a validation failure, a thrown exception. Modelling those as
+ * near-zero-width child spans clutters the waterfall, and modelling them as
+ * separate log lines loses the "which span was I in" correlation that makes them
+ * useful in the first place.
+ */
+interface SpanEventPoint {
+  /** Structured attributes, normalized like a span's own. */
+  attributes?: LogFields;
+  /** Event name, e.g. `"exception"` or `"cache.miss"`. */
+  name: string;
+  /** Wall-clock millis when it happened. */
+  ts: number;
+}
+/**
+ * A causal reference to a span in ANOTHER trace — OTel's `Span.links`.
+ *
+ * The standard answer to fan-in: a queue consumer processing a batch of 100
+ * messages links to the 100 producing spans rather than parenting to one of them
+ * (arbitrary) or all of them (impossible). The traces stay separately navigable
+ * and the causal edge survives.
+ */
+interface SpanLink {
+  /** Attributes describing the relationship, e.g. `{ "link.kind": "enqueued_by" }`. */
+  attributes?: LogFields;
+  /** Linked span id (16-hex). */
+  spanId: string;
+  /** Linked trace id (32-hex). */
+  traceId: string;
+}
 /**
  * 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
@@ -2342,10 +2460,61 @@ interface MetricEvent {
  * value winning on a key clash.
  */
 interface SpanHandle {
+  /**
+   * Record a timestamped {@link SpanEventPoint} on the enclosing span — a retry,
+   * a cache miss, a state transition. Prefer this over an extra `ctx.log` line
+   * for anything that only makes sense *relative to this span*: it rides the
+   * span's own export, so it costs no additional log record and can never be
+   * separated from its context.
+   */
+  addEvent: (name: string, attributes?: LogFields) => void;
+  /**
+   * Link this span to one in another trace (see {@link SpanLink}) — how a batch
+   * consumer points back at the requests that enqueued its items without
+   * collapsing every producer into one giant trace.
+   */
+  addLink: (link: SpanLink) => void;
+  /**
+   * Record a caught exception as the OTel-conventional `exception` span event
+   * (`exception.type` / `exception.message` / `exception.stacktrace`).
+   *
+   * Distinct from letting the error propagate: this is for an error you
+   * **handled** — a retried request, a fallback that worked — which should be
+   * visible in the trace without marking the span failed. An error that escapes
+   * the span body is recorded automatically and *does* set the error status.
+   */
+  recordException: (error: unknown) => void;
   /** Set one attribute on the enclosing span (merged at record time; post-hoc wins on key clash). */
   setAttribute: (key: string, value: LogFields[string]) => void;
   /** Merge attributes onto the enclosing span (post-hoc wins on key clash). */
   setAttributes: (fields: LogFields) => void;
+  /**
+   * The W3C ids of the span this handle refers to.
+   *
+   * A handle that cannot say WHICH span it is forces every consumer that needs
+   * the identity — a `traceparent` for a hand-rolled outbound call, a trace id
+   * echoed in an error response so a user can quote it in a bug report, an
+   * `@opentelemetry/api` bridge parenting a third-party library's spans — to
+   * reach around the API for it.
+   */
+  spanContext: () => {
+    spanId: string;
+    traceId: string;
+  };
+}
+/** Options accepted by `ctx.trace(name, fn, options)` beyond the plain attribute bag. */
+interface SpanOptions {
+  /** Start attributes, snapshotted before the body runs. */
+  attributes?: LogFields;
+  /**
+   * OTel `SpanKind`, default `"internal"`. Set `"client"` for a call OUT to
+   * another service, `"producer"`/`"consumer"` for queue hops — this is what a
+   * collector builds its service map from, so leaving everything `"internal"`
+   * yields a trace with no topology.
+   */
+  kind?: OtlpSpanKind;
+  /** Links to spans in other traces, known at start (see {@link SpanLink}). */
+  links?: SpanLink[];
 }
 interface SpanEvent {
   /**
@@ -2356,6 +2525,12 @@ interface SpanEvent {
   attributes?: LogFields;
   /** Wall-clock duration of the span body, in milliseconds. */
   durationMs: number;
+  /**
+   * Timestamped occurrences inside the span (see {@link SpanEventPoint}) —
+   * `ctx.trace`'s `span.addEvent(...)` / `span.recordException(...)`. Absent
+   * when the body recorded none.
+   */
+  events?: SpanEventPoint[];
   /**
    * 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
@@ -2372,6 +2547,14 @@ interface SpanEvent {
    * reuses its context — the same attribution rule `ctx.log` follows.
    */
   functionPath: string;
+  /**
+   * OTel `SpanKind`. Absent means `"internal"` — the overwhelming majority of
+   * `ctx.trace` spans — so the common case costs no bytes on the wire and every
+   * pre-existing recorded span stays valid.
+   */
+  kind?: OtlpSpanKind;
+  /** Causal references to spans in other traces (see {@link SpanLink}). Absent when none. */
+  links?: SpanLink[];
   /** Caller-supplied span name, e.g. `"stripe.charge"`. */
   name: string;
   /** True when the span body returned without throwing. */
@@ -2417,7 +2600,7 @@ interface SpanEvent {
  * which it can attach attributes only known *after* it resolves (post-hoc). It is
  * a trailing parameter, so a `(trace) => …` body that ignores it still conforms.
  */
-type ContextTracer = <T>(name: string, function_: (trace: ContextTracer, span: SpanHandle) => Promise<T> | T, attributes?: LogFields) => Promise<T>;
+type ContextTracer = <T>(name: string, function_: (trace: ContextTracer, span: SpanHandle) => Promise<T> | T, options?: LogFields | SpanOptions) => Promise<T>;
 /** Structural shape of the `ctx.metrics` recorder (see the server `LunoraMetrics`). */
 interface ContextMetrics {
   count: (name: string, value?: number, attributes?: LogFields) => void;
@@ -2503,6 +2686,12 @@ interface MetricsDeps {
   record: (event: MetricEvent) => void;
   shardKey: string | undefined;
 }
+/** Everything a {@link SpanHandle}'s body attached, ready to merge into the recorded span. */
+interface SpanCollection {
+  attributes: Record<string, LogFields[string]>;
+  events: SpanEventPoint[];
+  links: SpanLink[];
+}
 /**
  * Build the `ctx.trace` span factory for one dispatched function.
  *
@@ -2560,6 +2749,8 @@ interface MetricsDeps {
  * waterfall is unaffected.
  */
 declare const createTracer: (deps: TracerDeps) => ContextTracer;
+/** The `fetch` shape `ctx.fetch` exposes — the platform global's, narrowed to what we wrap. */
+type ContextFetch = (input: Request | string | URL, init?: RequestInit) => Promise<Response>;
 /**
  * Build the `ctx.metrics` recorder for one dispatched function.
  *
@@ -2582,6 +2773,14 @@ declare const createMetrics: (deps: MetricsDeps) => ContextMetrics;
  */
 declare const dispatchRootSpan: (input: {
   anchor: TraceAnchor;
+  /**
+   * What the handler attached to the dispatch through `ctx.span` — the **wide
+   * event**. These are the attributes that would otherwise have been scattered
+   * across a dozen `ctx.log` lines; carrying them on the one span that already
+   * exists per request is the OTel-native way to get a wide event without
+   * multiplying log records.
+   */
+  collected?: SpanCollection;
   durationMs: number;
   failure: {
     thrown: unknown;
@@ -3787,67 +3986,6 @@ declare const pointInBoundingBox: (point: GeoPoint, box: GeoBoundingBox) => bool
  * in the box is scanned before the exact `pointInBoundingBox` refine.
  */
 declare const boundingBoxGeohashes: (box: GeoBoundingBox) => string[];
-/**
- * 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 {
-  /**
-   * Resolves this request's detected OTLP resource attributes (`service.version`,
-   * `cloud.region`, …) on demand, or absent when the host does not detect any.
-   *
-   * Deliberately a resolved, allowlisted bag behind a thunk rather than the raw
-   * `env` and `Request` the host detected them from: this context is fanned out
-   * to **every** registered sink, including user-authored ones, so anything
-   * reachable here should be assumed to end up in someone's debug log — and raw
-   * `env` is every secret binding, while a raw `Request` carries the caller's
-   * `Authorization` and `Cookie`. The thunk keeps detection lazy (a sink that
-   * does not want resource attributes pays nothing) and hosts are expected to
-   * memoize it per request.
-   */
-  resourceAttributes?: () => Record<string, boolean | number | string>;
-  /** 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
@@ -4413,6 +4551,18 @@ declare class SessionDO {
   private handleGet;
   private handleRevoke;
 }
+/**
+ * How much detail `ctx.db` auto-instrumentation produces.
+ *
+ * `"summary"` (default) — aggregate counters on the dispatch's wide event: no
+ * extra spans, no extra log records, and a cost that does not grow with call count.
+ *
+ * `"spans"` — one span per database call. The full waterfall, at the price of a
+ * span per call; right when diagnosing, noisy as a permanent default.
+ *
+ * `"off"` — no database telemetry at all.
+ */
+type DatabaseInstrumentation = "off" | "spans" | "summary";
 /** One table's resolved TTL policy, as surfaced to the DO alarm by the generated shard subclass. */
 interface TtlSweepSpec {
   /** Millisecond offset added to `field` to derive the expiry (`field + after`); absent ⇒ `field` is the absolute expiry. */
@@ -4481,6 +4631,15 @@ declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown
  * `@lunora/runtime`'s `ObservabilitySink` without taking a dependency on it.
  */
 interface TelemetrySink {
+  /**
+   * Ship anything the sink has buffered, now. Called at the end of every
+   * dispatch (and of an alarm / socket message), so a batching sink — which
+   * exports one request per invocation instead of one per event — is never left
+   * holding telemetry a quiet shard would sit on indefinitely. Optional: a
+   * non-buffering sink simply omits it. Mirror of `@lunora/runtime`'s
+   * `ObservabilitySink.flush`.
+   */
+  flush?: (context?: LogSinkContext) => void;
   /**
    * **Opt-in, EXPERIMENTAL, default off.** When `true`, each `ctx.trace` span is
    * ALSO emitted as a Cloudflare **custom span** (`tracing.enterSpan` from
@@ -4495,9 +4654,25 @@ interface TelemetrySink {
    * `fuseCloudflareTraces`; see {@link createTracer} for the double-export caveat.
    */
   fuseCloudflareTraces?: boolean;
+  /**
+   * Detail level for automatic `ctx.db` instrumentation. Default `"summary"` —
+   * aggregate counters folded onto the dispatch's root span when one is recorded,
+   * so cost does not grow with call count and an uninstrumented handler still
+   * emits nothing extra. Mirror of `@lunora/runtime`'s `ObservabilitySink`.
+   */
+  instrumentDatabase?: DatabaseInstrumentation;
   onLog?: (event: LogEventInput, context?: LogSinkContext) => void;
   onMetric?: (event: MetricEvent, context?: LogSinkContext) => void;
   onSpan?: (event: SpanEvent, context?: LogSinkContext) => void;
+  /**
+   * Whether `ctx.fetch` is instrumented — a CLIENT span per outbound call plus
+   * W3C `traceparent` propagation to the callee. Default on; set `false` to get
+   * the bare platform `fetch`, or an object to control which destinations
+   * receive trace context. Mirror of `@lunora/runtime`'s `ObservabilitySink`.
+   */
+  traceFetch?: boolean | {
+    propagate?: ((url: URL) => boolean) | boolean;
+  };
 }
 /**
  * Structural shape of the `ctx.log` logger the DO builds (see the server
@@ -4507,6 +4682,20 @@ interface TelemetrySink {
 interface ContextLogger {
   debug: (...args: unknown[]) => void;
   error: (...args: unknown[]) => void;
+  /**
+   * Emit a **structured event** — OTel's Events API — rather than a log line.
+   *
+   * The difference is what carries the meaning. A log line's payload is its
+   * message: prose, written for a human, free to be reworded next week. An
+   * event's payload is its `fields` under a stable `name`, written for a query.
+   * Only the second can answer "how many checkouts failed, by plan, this hour"
+   * without a substring search over English.
+   *
+   * On the wire this sets OTel's `LogRecord.eventName` (plus the `event.name`
+   * attribute for collectors predating that field), so any OTLP backend
+   * recognises it without Lunora-specific configuration.
+   */
+  event: (name: string, fields?: LogFields) => void;
   fatal: (...args: unknown[]) => void;
   info: (...args: unknown[]) => void;
   log: (...args: unknown[]) => void;
@@ -4947,6 +5136,34 @@ declare abstract class ShardDO {
    * by `span.traceId`, and deleted in the `finally`.
    */
   private traceSampling;
+  /**
+   * The per-dispatch **wide event** — everything a handler attached through
+   * `ctx.span` — keyed by `traceId` for exactly the reason `traceSampling`
+   * is: a DO interleaves dispatches across `await` points, and a flat field
+   * would let a sibling dispatch's attributes land on this one's span.
+   *
+   * A wide event is the answer to "monitor everything without drowning in
+   * logs": rather than a dozen `ctx.log.info` lines whose only readers are
+   * humans grepping, a handler accumulates its facts onto the ONE span the
+   * dispatch already emits, and the collector gets a single richly-attributed
+   * record it can group and aggregate. Cost is flat — one span per request,
+   * however much you attach.
+   *
+   * Keyed by {@link dispatchSpanKey} (trace id AND root span id) rather than
+   * `traceId` alone — see there for the concurrent-dispatch collision that
+   * distinction prevents.
+   *
+   * Bounded by {@link MAX_TRACKED_DISPATCH_SPANS}: the dispatch `finally`
+   * deletes its own entry, but a ctx built outside a dispatch (an alarm, a
+   * subscription re-run) mints its own anchor and has no such boundary, so the
+   * map is FIFO-capped rather than trusted to drain.
+   */
+  private dispatchSpans;
+  /**
+   * The most recent telemetry sink seen while building a ctx — the flush handle
+   * for paths that have no ctx of their own (see `flushTelemetry`).
+   */
+  private lastTelemetrySink;
   /**
    * 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
@@ -5223,6 +5440,19 @@ declare abstract class ShardDO {
    * Hibernation API: invoked by the runtime when a message arrives on a
    * hibernated socket. Subclasses can override this to intercept; the
    * default decodes a {@link SubscriptionEnvelope} and updates the registry.
+   *
+   * Deliberately NOT wrapped in {@link withTriggerTrace}, unlike `alarm`. Frame
+   * rate here is unbounded — a whisper fan-out or presence stream drives many
+   * per second — and minting a trace anchor per frame costs two `crypto`
+   * draws plus hex encoding, which measurably regressed the fan-out benchmark
+   * (~30% on `broadcastWhisper` to 128 members). The trade is also worse than it
+   * looks: a frame's work is a subscription re-evaluation whose data flow is
+   * already attributable to the RPC that wrote the data, so the root span buys
+   * little. An alarm is the opposite — low frequency, and genuinely
+   * un-attributable background work — which is why that one keeps the wrapper.
+   *
+   * `ctx.trace`/`ctx.span` inside a frame still record; they just anchor to the
+   * ctx's own trace rather than a per-frame root.
    */
   webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
   /**
@@ -6071,7 +6301,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?: TelemetrySink): void;
+  protected recordUserLog(functionPath: string, level: ContextLogLevel, args: unknown[], message: string, fields: Record<string, unknown> | undefined, sink?: TelemetrySink, eventName?: string, anchor?: TraceAnchor): void;
   /**
    * Build the `ctx.log` logger for one dispatched function. Each severity method
    * accepts either the structured form (`(message, fields)`) or console-style
@@ -6097,6 +6327,44 @@ declare abstract class ShardDO {
    * resolved sink sets `fuseCloudflareTraces` (see {@link resolveCloudflareTracing}).
    */
   protected makeTracer(functionPath: string, sink?: TelemetrySink, anchor?: TraceAnchor): ContextTracer;
+  /**
+   * The trace anchor a ctx's `trace` and `span` both hang off.
+   *
+   * Resolved once per `buildCtx` and shared, so `ctx.trace` spans and the
+   * `ctx.span` wide event land in the SAME trace. Previously each consumer
+   * minted its own fallback when there was no current trace, which was fine
+   * while `ctx.trace` was the only consumer and silently splits the two now
+   * that there are two.
+   *
+   * `identityScoped` marks a deferred/interleaved caller (a subscription seed
+   * or refresh): those must NOT inherit the shared per-request trace, which a
+   * concurrent RPC may have re-set, so they mint their own self-contained one.
+   */
+  protected resolveDispatchAnchor(identityScoped: boolean): TraceAnchor;
+  /**
+   * Wrap `ctx.db` in automatic instrumentation — see {@link instrumentDatabase}
+   * for why the default is aggregate counters rather than a span per call.
+   *
+   * A no-op (returning the database untouched) with no sink configured or with
+   * `instrumentDatabase: "off"`, so a deployment that collects nothing pays
+   * nothing.
+   */
+  protected instrumentDb<T extends object>(database: T, functionPath: string, anchor: TraceAnchor, sink?: TelemetrySink): T;
+  /**
+   * Build `ctx.fetch` — the platform `fetch`, instrumented.
+   *
+   * Every outbound call becomes a CLIENT span and carries a `traceparent` to
+   * the callee, so time spent waiting on someone else's service stops being an
+   * unexplained gap in the waterfall and the callee's spans join this trace
+   * instead of starting an unrelated one.
+   *
+   * Falls back to the bare global `fetch` when no sink is configured or the
+   * sink opted out via `traceFetch: false` — there is no point paying for spans
+   * nobody collects, and an app calling a third party it would rather not send
+   * trace ids to needs a way to say so.
+   */
+  protected makeFetch(functionPath: string, anchor: TraceAnchor, sink?: TelemetrySink): ContextFetch;
+  protected makeDispatchSpan(anchor: TraceAnchor, sink?: TelemetrySink): SpanHandle;
   /**
    * Build the `ctx.metrics` recorder for one dispatched function. Thin wiring
    * over {@link createMetrics}, which owns the instrument semantics.
@@ -6116,6 +6384,70 @@ declare abstract class ShardDO {
    * cross-instance aggregation is still the sink's job.
    */
   protected recordMetric(event: MetricEvent, sink?: TelemetrySink): void;
+  /** The decode + route body of {@link webSocketMessage}, split out so the trace wrapper stays a one-liner. */
+  protected handleWebSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+  /**
+   * The alarm's actual work, split out so {@link alarm} is a one-line trace
+   * wrapper. An alarm drives `.global()` shape refreshes and external-source
+   * ingest with no client waiting on a response, which is exactly where a
+   * silent failure hides longest — so it gets a root span like any dispatch.
+   */
+  private handleAlarmBody;
+  /**
+   * Build `ctx.span` — the handle onto the **dispatch's own span**, and with it
+   * the wide-event surface.
+   *
+   * `ctx.trace(...)` creates a *new* child span for a sub-operation; this
+   * attaches to the one that already exists for the request. That is the
+   * distinction between "time this thing" and "record a fact about this
+   * request", and conflating them is why instrumentation usually degrades into
+   * log spam: with nowhere to put a fact, people reach for `ctx.log.info`.
+   *
+   * Attributes accumulate across the whole dispatch and are folded into the
+   * root span in `recordDispatchRootSpan` — the OTel-native form of a
+   * wide event, needing no non-standard "canonical log line" convention on the
+   * collector side.
+   *
+   * Keyed by `dispatchSpanKey` — trace id AND root span id — so two concurrent
+   * dispatches forwarded under the same client trace accumulate separately.
+   */
+  /**
+   * The dispatch entry's db tally, created on first use. Shares the entry with
+   * `ctx.span`'s collector but is deliberately a separate slot — see
+   * `instrumentDb`.
+   */
+  private dispatchTally;
+  /**
+   * Give a NON-`fetch` Durable Object trigger — an alarm, an inbound socket
+   * frame — the same telemetry an RPC dispatch gets: its own trace anchor, a
+   * dispatch root span, and a flush of the batching sink when it finishes.
+   *
+   * These paths were previously invisible. An alarm can drive `.global()` shape
+   * refreshes and external-source ingest, and a socket frame can run a whole
+   * subscription re-evaluation, but neither produced a root span — so any
+   * `ctx.trace` span they created hung off a freshly-minted anchor with nothing
+   * above it, and a collector showed orphans with no bar explaining what caused
+   * them. Alarms are also precisely where a silent failure hides longest,
+   * because no client is waiting on a response to notice.
+   *
+   * The anchor is published on `currentRequestTrace` ONLY when nothing else has
+   * claimed it, and restored afterwards, so a concurrently-interleaved RPC
+   * dispatch (which captured its own anchor in a local at entry) keeps its
+   * attribution. Worst case under interleaving is a mis-attributed inner span —
+   * the same trade the surrounding code already makes with this field — never a
+   * corrupted or lost one.
+   */
+  private withTriggerTrace;
+  /**
+   * Ask the last-seen telemetry sink to ship what it has buffered.
+   *
+   * Used by the trigger paths ({@link withTriggerTrace}), which have no `ctx`
+   * and therefore no direct handle on `config.observability`. The sink is a
+   * per-worker singleton in every real configuration, so remembering the most
+   * recent one is exact in practice and harmless otherwise: a flush is
+   * idempotent and a sink with an empty buffer is a no-op.
+   */
+  private flushTelemetry;
   /**
    * Buffer the synthetic root span for a finished dispatch. The caller gates
    * this on the dispatch having actually produced spans (the `hasTrace` check at
@@ -6126,8 +6458,31 @@ declare abstract class ShardDO {
    * `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.
+   *
+   * When the handler attached a **wide event** through `ctx.span`, this also
+   * exports it — see {@link exportWideEvent} for why it goes out as an OTel
+   * Event record rather than on the span itself.
    */
   private recordDispatchRootSpan;
+  /**
+   * Export a dispatch's wide event as a standard OTel **Event** log record
+   * (`lunora.dispatch`), correlated to the dispatch's trace and span.
+   *
+   * **Why a log record rather than the span's attributes.** The local dispatch
+   * root span shares its `spanId` with the SERVER span `@lunora/runtime` emits
+   * for the same dispatch — they are the same logical span, seen from the two
+   * sides of the shard hop. Exporting our copy too would put two partial spans
+   * with identical `trace_id`/`span_id` on the wire, which collectors resolve
+   * inconsistently (merge, last-write, or duplicate). An Event record carrying
+   * `traceId`/`spanId` is unambiguous, is the OTel-sanctioned shape for exactly
+   * this ("a named, structured occurrence"), and every OTLP backend can group
+   * and aggregate it with no Lunora-specific configuration.
+   *
+   * The span still carries the attributes LOCALLY, which is what the Studio
+   * waterfall renders — so the wide event is visible in both places, exported
+   * exactly once.
+   */
+  private exportWideEvent;
   /**
    * Buffer one span for the studio Traces panel and hand it to the optional
    * `sink.onSpan`. Best-effort throughout, exactly like {@link recordUserLog}: