@lunora/observability 1.0.0-alpha.8 → 1.0.0-alpha.81

package/README.md

@@ -19,15 +19,13 @@ None of it is Cloudflare-specific. It reads and writes through the SQL handle th
 
 That mattered in practice: anything wanting request logs or metrics had to depend on the Cloudflare Durable Object package to get them. The dependency now runs `@lunora/do` → `@lunora/observability` → `@lunora/shard-engine`, so a second host consumes this directly rather than inheriting a provider-bound edge.
 
-`@lunora/do` re-exports every symbol it previously exposed from these modules, so existing imports and the codegen-emitted surface are unchanged.
-
 ## Host-specific values are injected, not baked in
 
 Three details are Cloudflare's rather than this package's, so the host passes them:
 
 - **AI model** — `explainIssue(binding, args, { defaultModel })`. `DEFAULT_EXPLAIN_ISSUE_MODEL` is a Workers AI id, exported so the Cloudflare host has a name to pass rather than a string literal.
-- **Query batch size** — `readIssueStates(sql, hashes, { hashQueryBatch })`. `DEFAULT_HASH_QUERY_BATCH` is 100, the Durable Object SQLite bound-parameter cap; a host with a different cap passes its own.
-- **Span projections** — `HostSpanLike`, `HostTracingLike`, `HostTracingResolver`, `resolveHostTracing`, `fuseHostSpans`, `applyHostSpanAttributes`. Named for the role, not the provider. Cloudflare's `enterSpan` callback argument is one shape that satisfies them.
+- **Query batch size** — hashes are read in batches of `DEFAULT_HASH_QUERY_BATCH` (100), the Durable Object SQLite bound-parameter cap. `readIssueStates` takes it as a `{ hashQueryBatch }` option, but neither the function nor the constant is on the package barrel and the in-package reader passes no options, so the batch is fixed at 100 until a host with a different cap needs it threaded through.
+- **Span projections** — the exported types `HostSpanLike`, `HostTracingLike` and `HostTracingResolver`. Named for the role, not the provider; Cloudflare's `enterSpan` callback argument is one shape that satisfies them. The host injects its tracer through the `TracerDeps` option fields `fuseHostSpans?: boolean` and `resolveHostTracing?: HostTracingResolver` — those are option names, not exported values, and the resolver itself lives in the host (`@lunora/do`'s `shard-do.ts` guards a dynamic `import("cloudflare:workers")`).
 
 ## Importing it
 

package/dist/index.d.mts

@@ -64,9 +64,9 @@ declare const ensureAuthMetricsTables: (sql: SqlExec) => void;
  * `failures` advances only when `outcome === "fail"`. `since_ms` is set once on
  * the first attempt and never moved (so it stays a true first-seen marker).
  *
- * Exactly two `INSERT … ON CONFLICT … DO UPDATE` statements plus a bounded
- * `DELETE`, all keyed by primary key — cheap enough to fire off the auth
- * response path without blocking it.
+ * Exactly two `INSERT … ON CONFLICT … DO UPDATE` statements, all keyed by
+ * primary key, plus a bounded `DELETE` that runs once per bucket window —
+ * cheap enough to fire off the auth response path without blocking it.
  */
 declare const recordAuthEvent: (sql: SqlExec, input: RecordAuthEventInput) => void;
 /**
@@ -320,10 +320,50 @@ interface SpanHandle {
    * `@opentelemetry/api` bridge parenting a third-party library's spans — to
    * reach around the API for it.
    */
-  spanContext: () => {
-    spanId: string;
-    traceId: string;
-  };
+  spanContext: () => SpanContextIds;
+}
+/**
+ * The W3C identity of one span, plus the trace's settled sampling verdict.
+ *
+ * `sampled` is the propagated head decision (absent means "no verdict reached
+ * this tier", which every consumer reads as keep). It rides alongside the ids
+ * because everything that needs the ids to announce this span downstream — a
+ * hand-built `traceparent`, the `@opentelemetry/api` bridge's `SpanContext` —
+ * needs the flag in the same breath, and announcing `sampled` on a trace that
+ * was sampled OUT is what leaves a collector holding the middle of a trace.
+ */
+interface SpanContextIds {
+  /** The trace's settled W3C `sampled` verdict; absent when none was propagated. */
+  sampled?: boolean;
+  /** This span's id (16-hex). */
+  spanId: string;
+  /** The trace this span belongs to (32-hex). */
+  traceId: string;
+}
+/**
+ * Caller-supplied ids for one `ctx.trace` span, passed as the tracer's fourth
+ * argument.
+ *
+ * For adapters that must hand a span's identity to somebody else BEFORE the span
+ * body runs — the `@opentelemetry/api` bridge returns a `SpanContext`
+ * synchronously from `startSpan`, and a library builds a `traceparent` from it —
+ * so the id the adapter published is the id that reaches the collector rather
+ * than a phantom. `parentSpanId` overrides the enclosing span for the same
+ * reason: an adapter that tracks its own parent/child structure (OTel's
+ * `Context`) can express it without an ambient span stack.
+ *
+ * Not part of the ordinary `ctx.trace(name, fn, attributes)` call — a handler
+ * never mints its own ids.
+ *
+ * Both ids are required: an adapter that has published one has published the
+ * other, and `identity` is itself optional — omitting it, not passing a partial
+ * object, is how a caller says "no adapter involved".
+ */
+interface SpanIdentity {
+  /** Parent to this span id instead of the enclosing `ctx.trace` / dispatch span. */
+  parentSpanId: string;
+  /** Record the span under this id (16-hex) instead of a freshly minted one. */
+  spanId: string;
 }
 /** Options accepted by `ctx.trace(name, fn, options)` beyond the plain attribute bag. */
 interface SpanOptions {
@@ -423,7 +463,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, options?: LogFields | SpanOptions) => Promise<T>;
+type ContextTracer = <T>(name: string, function_: (trace: ContextTracer, span: SpanHandle) => Promise<T> | T, options?: LogFields | SpanOptions, identity?: SpanIdentity) => Promise<T>;
 /** Structural shape of the `ctx.metrics` recorder (see the server `LunoraMetrics`). */
 interface ContextMetrics {
   count: (name: string, value?: number, attributes?: LogFields) => void;
@@ -560,10 +600,7 @@ interface SpanCollector {
  * class `isInternalCode` redaction exists for, so it rides the same dev-only
  * escape hatch rather than shipping to a third-party collector by default.
  */
-declare const createSpanCollector: (ids: {
-  spanId: string;
-  traceId: string;
-}, captureRaw?: boolean) => SpanCollector;
+declare const createSpanCollector: (ids: SpanContextIds, captureRaw?: boolean) => SpanCollector;
 /**
  * Build the `ctx.trace` span factory for one dispatched function.
  *
@@ -605,7 +642,7 @@ declare const createSpanCollector: (ids: {
  *
  * **DO async-context caveat (EXPERIMENTAL, partially workerd-validated).**
  * `tracing.enterSpan` is now confirmed to EXIST and RUN inside a real Durable
- * Object under `@cloudflare/vitest-pool-workers` (see
+ * Object under `@cloudflare/vitest-plugin` (see
  * `__tests__/workerd/context-telemetry-cf-bridge.workerd.test.ts`): it resolves
  * from `cloudflare:workers`, its callback executes and returns the body value
  * without throwing, `span.isTraced` is a real boolean, and — the key additive
@@ -625,6 +662,14 @@ declare const createTracer: (deps: TracerDeps) => ContextTracer;
 interface TracedFetchDeps {
   /** The trace the CLIENT spans belong to. */
   anchor: TraceAnchor;
+  /**
+   * Whether to record a failed fetch's error message verbatim rather than
+   * redacted. Same dev-only escape hatch as {@link TracerDeps.captureRaw}, and
+   * the same reason: a `fetch` TypeError embeds the request URL, so a key in a
+   * query string would otherwise reach the collector in the clear on the very
+   * span whose `url.full` is scrubbed by `redactUrl`.
+   */
+  captureRaw?: boolean;
   /** Function path the spans are attributed to. */
   functionPath: string;
   /**
@@ -660,6 +705,15 @@ type ContextFetch = (input: Request | string | URL, init?: RequestInit) => Promi
  * Kind is `client` rather than `internal` — that is what lets a collector draw
  * the edge to the downstream service in a service map.
  *
+ * **Parenting is the DISPATCH, not the enclosing `ctx.trace`.** `ctx.fetch` is
+ * built once per dispatch, and the enclosing span is threaded explicitly rather
+ * than kept on an ambient stack (no `AsyncLocalStorage` in the Durable Object
+ * profile — the same constraint `ctx.trace` and the `@opentelemetry/api` bridge
+ * document), so a fetch inside `ctx.trace("stripe", …)` renders as that span's
+ * SIBLING under the dispatch, not its child. The duration and the ordering are
+ * right and the span is never lost; only the nesting is flat. Wrap the call in
+ * the span whose bar you want it under and read the two side by side.
+ *
  * Failures are recorded and re-thrown untouched, and a non-2xx response is
  * recorded as an ERROR span (it is a failed call from the caller's point of
  * view) while still being returned normally — instrumentation, never flow
@@ -911,7 +965,7 @@ interface RecordFunctionMetricInput {
    * dispatch used no declared index, keeping the hot path unchanged.
    */
   indexHits?: ReadonlyArray<IndexHit>;
-  /** The `&lt;file>:&lt;function>` identifier. */
+  /** The `<file>:<function>` identifier. */
   path: string;
   /**
    * Distinct tables this dispatch full-scanned (read with no index / point
@@ -1040,7 +1094,7 @@ interface AiRunBinding {
 }
 /** Parsed `__lunora_admin__:explainIssue` payload: the folded Issue's identifying facts, plus an optional model override. */
 interface ExplainIssueArgs {
-  /** The Issue's culprit (`&lt;file>:&lt;function>` or `container:&lt;name>`), for grounding context. */
+  /** The Issue's culprit (`<file>:<function>` or `container:<name>`), for grounding context. */
   culprit?: string;
   /** Per-request model-id override; falls back to the caller's `defaultModel`, then {@link DEFAULT_EXPLAIN_ISSUE_MODEL}. */
   model?: string;
@@ -1189,13 +1243,15 @@ type LogLevel = ContextLogLevel;
  */
 interface LogEntry {
   exitCode?: number;
-  /** Structured fields from a `ctx.log.&lt;level>(message, fields)` / `ctx.log.with(fields)` call, when present. */
+  /** Structured fields from a `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call, when present. */
   fields?: Record<string, unknown>;
   functionPath?: string;
   instance?: string;
   level: LogLevel;
   message: string;
   timestamp: number;
+  /** Trace the line was emitted under; absent outside a dispatch (container lifecycle, hibernation-path errors). What the Studio joins a log line to its waterfall on. */
+  traceId?: string;
 }
 /**
  * A bounded, in-memory ring buffer of recent {@link LogEntry} records.
@@ -1216,10 +1272,21 @@ declare class LogBuffer {
   /** Backing store, kept in insertion order (oldest first). */
   private readonly buffer;
   private readonly capacity;
+  /** How many entries the ring has evicted since it was last cleared. */
+  private droppedCount;
   constructor(capacity?: number);
+  /**
+   * Entries evicted for capacity since the last {@link LogBuffer.clear}.
+   *
+   * Without it a full ring is indistinguishable from a quiet instance that
+   * happened to log exactly `capacity` lines: the reader sees 500 entries
+   * either way and cannot tell whether 500 lines happened or 50,000 did. The
+   * count is what turns "the newest 500" into an honest statement.
+   */
+  get dropped(): number;
   /** Number of entries currently buffered. */
   get size(): number;
-  /** Drop every buffered entry. */
+  /** Drop every buffered entry, including the eviction count. */
   clear(): void;
   /**
    * Snapshot of the buffered entries, **newest first** so the panel renders
@@ -1342,7 +1409,14 @@ interface MetricHistoryResult {
  * omitted field keeps the historical behaviour.
  */
 interface MetricHistoryOptions {
-  /** Distinct series tracked before the least-recently-updated one is evicted to admit a new one (default {@link METRIC_HISTORY_MAX_SERIES}). */
+  /**
+   * Distinct series tracked before a brand-new one is REFUSED admission
+   * (default {@link METRIC_HISTORY_MAX_SERIES}). Nothing is evicted: an
+   * already-tracked series keeps accumulating past the cap, and a flood of
+   * one-off series cannot displace the app's real ones — see
+   * {@link admitNewSeries}. `readMetricHistory`'s `capped` flag is the
+   * read-side signal that admission is being refused.
+   */
   maxSeries?: number;
   /** Minute-buckets kept per series before older rows are trimmed (default {@link METRIC_HISTORY_BUCKET_RETENTION}). */
   retentionBuckets?: number;
@@ -1393,9 +1467,9 @@ interface QueryStatEntry {
   execCount: number;
   /** Normalised SQL text (literals stripped, truncated). */
   normalizedSql: string;
-  /** Total rows read across all executions (SELECT result sizes). */
+  /** Total rows SCANNED across all executions (the billed number, not the result-set size). */
   rowsRead: number;
-  /** Total rows written across all executions. */
+  /** Total rows WRITTEN across all executions. */
   rowsWritten: number;
   /** Total wall-clock milliseconds across all executions. */
   totalDurationMs: number;
@@ -1476,11 +1550,13 @@ type RequestOutcome = "error" | "ok";
 interface RequestLogEntry {
   /** Whether the result was served from the reactive cache; `undefined` when the cache is disabled or the path isn't cached (a write/action). */
   cacheHit?: boolean;
+  /** Worker deployment id from the `CF_VERSION_METADATA` binding; `undefined` when the binding isn't declared. Group on this to answer "did this start with a deploy?". */
+  deploymentId?: string;
   /** Handler wall-clock duration in milliseconds (before the subscription write-flush, matching the per-function metrics). */
   durationMs: number;
   /** Error message when `outcome === "error"`, redacted like args/identity; absent on success. */
   errorMessage?: string;
-  /** The `&lt;file>:&lt;function>` identifier dispatched, e.g. `messages:list`. */
+  /** The `<file>:<function>` identifier dispatched, e.g. `messages:list`. */
   functionPath: string;
   /** Identity-claim envelope forwarded by the runtime, JSON-decoded; leaf values are redacted (the claims are PII), so only the shape survives. Absent for anonymous requests. Correlate on `userId` instead. */
   identity?: Record<string, unknown>;
@@ -1498,14 +1574,19 @@ interface RequestLogEntry {
   tablesRead: string[];
   /** Tables the handler wrote (from the change tracker); empty for a read-only dispatch. */
   tablesWritten: string[];
+  /** W3C trace id (32-hex) of the dispatch; `undefined` on a row appended before this column existed. See the module docstring on the retention asymmetry. */
+  traceId?: string;
   /** Wall-clock millis when the dispatch completed. */
   ts: number;
   /** Acting userId forwarded by the runtime, or `undefined` when anonymous. */
   userId?: string;
+  /** Worker version tag from the `CF_VERSION_METADATA` binding; `undefined` when the binding isn't declared or the deploy carried no tag. */
+  versionTag?: string;
 }
 /** Fields accepted when appending one request-log entry; `seq` is assigned by the table. */
 interface AppendRequestLogEntry {
   cacheHit?: boolean;
+  deploymentId?: string;
   durationMs: number;
   errorMessage?: string;
   functionPath: string;
@@ -1516,8 +1597,10 @@ interface AppendRequestLogEntry {
   subscriptionsReRun?: number;
   tablesRead?: string[];
   tablesWritten?: string[];
+  traceId?: string;
   ts: number;
   userId?: string;
+  versionTag?: string;
 }
 /** Knobs the dispatch site threads into a request-log write. */
 interface RequestLogWriteOptions {
@@ -1528,7 +1611,7 @@ interface RequestLogWriteOptions {
 }
 /** Filters for {@link readRequestLog}, all AND-combined; every value is a bound SQL parameter, so nothing here injects SQL. */
 interface ReadRequestLogOptions {
-  /** Functions whose path begins with this prefix (a `&lt;file>:` or `&lt;file>:&lt;fn>` correlation). */
+  /** Functions whose path begins with this prefix (a `<file>:` or `<file>:<fn>` correlation). */
   functionPathPrefix?: string;
   /** Upper bound on returned rows, clamped to [1, 10000]. */
   limit?: number;
@@ -1536,14 +1619,19 @@ interface ReadRequestLogOptions {
   outcome?: RequestOutcome;
   /** Exact shard-key match. */
   shardKey?: string;
-  /** Only entries strictly after this cursor (forward paging). */
+  /**
+   * Only entries strictly after this cursor. Setting it switches the read to
+   * ASCENDING order — see {@link readRequestLog} — because that is the only
+   * ordering under which advancing the cursor to the last returned `seq`
+   * actually pages forward without a hole.
+   */
   sinceSeq?: number;
   /** Keep only entries whose read OR written table set contains this table. */
   tableTouched?: string;
   /** Exact acting-userId match. */
   userId?: string;
 }
-/** Payload of a `__lunora_admin__:getRequestLog` call: the recorded entries, newest first. */
+/** Payload of a `__lunora_admin__:getRequestLog` call: the recorded entries, newest first — or oldest first when the request paged forward with `sinceSeq` (see {@link readRequestLog}). */
 interface RequestLogResult {
   entries: RequestLogEntry[];
 }
@@ -1558,7 +1646,7 @@ interface ErrorIssue {
   assignee?: string;
   /** Number of `error` rows folded into this Issue within the scanned window. */
   count: number;
-  /** The `&lt;file>:&lt;function>` (or `container:&lt;name>`) the errors came from. */
+  /** The `<file>:<function>` (or `container:<name>`) the errors came from. */
   culprit: string;
   /** Wall-clock millis of the oldest folded row. */
   firstSeen: number;
@@ -1597,7 +1685,7 @@ interface IssuesResult {
 }
 /** Filters for {@link readErrorIssues}; forwarded to {@link readRequestLog} with `outcome` forced to `error`. */
 interface ReadIssuesOptions {
-  /** Functions whose path begins with this prefix (a `&lt;file>:` or `&lt;file>:&lt;fn>` correlation). */
+  /** Functions whose path begins with this prefix (a `<file>:` or `<file>:<fn>` correlation). */
   functionPathPrefix?: string;
   /** Upper bound on error rows scanned before grouping, clamped to [1, 10000]. */
   limit?: number;
@@ -1622,7 +1710,7 @@ interface ReadIssuesOptions {
  * STRING — which is what `errorMessage`/log `fields`-as-rendered-text are —
  * only pattern-shaped matches apply: emails, long digit runs / structured
  * numeric IDs (credit-card, phone, SSN, AWS-access-key-style), and an explicit
- * `Bearer &lt;token>` / `token=…`-shaped substring. A free-text `password=hunter2`
+ * `Bearer <token>` / `token=…`-shaped substring. A free-text `password=hunter2`
  * or a bare provider API key embedded in prose (e.g. `sk-live-…`) is NOT
  * caught on a plain string — there is no key to match against, and neither is
  * a recognized value pattern. So this is a PII-pattern net for rendered text,
@@ -1651,12 +1739,17 @@ declare const redactArgs: (value: unknown, captureRaw?: boolean) => unknown;
  *
  * `error_fingerprint` is the {@link fingerprintError} grouping hash captured
  * from the RAW `error_message` at write time, before {@link appendRequestLogEntry}
- * redacts it — see that function's docstring. It is added via a guarded
- * `ALTER TABLE` rather than baked into the `CREATE`, mirroring
+ * redacts it — see that function's docstring. `trace_id` is the dispatch's W3C
+ * trace id, the correlation key to the span ring and to whatever collector
+ * `otlpSink` ships to.
+ *
+ * Both are also added via a guarded `ALTER TABLE`, mirroring
  * `function-metrics.ts`'s `ensureFunctionMetricsTables`, so a shard whose
- * `__lunora_reqlog__` predates this column gains it on the next call without a
+ * `__lunora_reqlog__` predates a column gains it on the next call without a
  * migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the duplicate-column
- * error from a re-run (or the freshly-created schema above) is swallowed.
+ * error from a re-run (or from the freshly-created schema above) is swallowed
+ * per column — the loop is what keeps one column's duplicate from skipping the
+ * next column's add.
  */
 declare const ensureRequestLogTable: (sql: SqlExec) => void;
 /**
@@ -1672,8 +1765,8 @@ declare const ensureRequestLogTable: (sql: SqlExec) => void;
  * it's redacted below, and the resulting hash is persisted in
  * `error_fingerprint`. `readErrorIssues` groups off that stored hash instead of
  * recomputing `fingerprintError` from the (redacted) `error_message` column, so
- * masking a PII-bearing value — e.g. two different `&lt;n>`-bucketed IDs that
- * redact to two different tag lengths (`&lt;DL>` vs `&lt;BANKACC>`) — can't split an
+ * masking a PII-bearing value — e.g. two different `<n>`-bucketed IDs that
+ * redact to two different tag lengths (`<DL>` vs `<BANKACC>`) — can't split an
  * existing Issue or change its identity.
  */
 declare const appendRequestLogEntry: (sql: SqlExec, entry: AppendRequestLogEntry, options?: RequestLogWriteOptions) => void;
@@ -1702,7 +1795,7 @@ declare const emitRequestLogEvent: (entry: AppendRequestLogEntry, options?: Requ
  */
 type LogEventInput = LogEvent;
 /**
- * Split a `ctx.log.&lt;level>(...)` call's raw arguments into a display `message`
+ * Split a `ctx.log.<level>(...)` call's raw arguments into a display `message`
  * and optional structured `fields`. The structured form — a message string plus
  * a plain-object fields bag — is matched only for exactly `(string, object)`;
  * every other shape is console-style and rendered whole (so existing
@@ -1747,12 +1840,21 @@ declare const parseLogArgs: (args: unknown[], boundFields?: LogFields) => {
  */
 declare const emitLogEvent: (input: LogEventInput, options?: RequestLogWriteOptions) => void;
 /**
- * Read request-log entries newest-first, AND-combining the supplied filters
- * (function-path prefix, exact userId/shardKey/outcome, and a table-touched
- * match against the read OR written table sets), up to `limit` (clamped to
- * [1, 10000]). Each value is a bound parameter, so no filter can inject SQL.
- * Creates the table first so reads on a never-logged shard return `[]` instead
- * of throwing. Mirrors `readAuditLog`/`readCdcChanges`.
+ * Read request-log entries, AND-combining the supplied filters (function-path
+ * prefix, exact userId/shardKey/outcome, and a table-touched match against the
+ * read OR written table sets), up to `limit` (clamped to [1, 10000]). Each value
+ * is a bound parameter, so no filter can inject SQL. Creates the table first so
+ * reads on a never-logged shard return `[]` instead of throwing. Mirrors
+ * `readAuditLog`/`readCdcChanges`.
+ *
+ * **Ordering follows `sinceSeq`.** Without a cursor this is a "show me the tail"
+ * read and returns NEWEST FIRST, which is what the studio's Logs tab renders.
+ * With `sinceSeq` it is forward paging and returns OLDEST FIRST, starting at the
+ * cursor: descending there silently loses rows, because `ORDER BY seq DESC LIMIT
+ * n` answers "the newest n after the cursor", so a consumer that advances to the
+ * largest returned `seq` skips everything between `sinceSeq` and that page
+ * whenever more than `limit` rows accumulated between polls — the more traffic
+ * the shard takes, the more it drops.
  */
 declare const readRequestLog: (sql: SqlExec, options?: ReadRequestLogOptions) => RequestLogEntry[];
 declare const readErrorIssues: (sql: SqlExec, options?: ReadIssuesOptions) => ErrorIssue[];
@@ -1770,7 +1872,7 @@ type SecurityFindingLevel = "error" | "info" | "warning";
  *
  * `admin-token-weak`: `LUNORA_ADMIN_TOKEN` is set but short enough to be brute-forceable. (An *unset* token disables admin introspection entirely, so this audit — itself admin-gated — only ever runs with a token present.)
  *
- * `ws-gate-open`: admin HTTP RPCs require the bearer, but `LUNORA_WS_BEARER` is unset so the WebSocket upgrade gate defaults open — live admin subscriptions (Logs, Metrics, …) are reachable without a credential.
+ * `ws-gate-open`: `LUNORA_WS_BEARER` is unset, so the WebSocket upgrade gate defaults open and anyone who can reach the worker can open a socket and run ordinary USER subscriptions (whatever `ctx.auth` / RLS then allows them to read). Admin subscriptions are NOT part of this: they require the socket's `admin` stamp, which the upgrade sets only from `LUNORA_ADMIN_TOKEN` or a minted admin sub-token, so an unset `LUNORA_WS_BEARER` never exposes Logs/Metrics/introspection. Which is why this is a posture finding about the app's own live-query surface, not an admin hole — set the var when subscribers are expected to present a shared credential.
  *
  * `dev-args-unredacted`: the worker reports a development environment, so the durable request log captures raw, un-redacted args and identity (PII). A production deploy mislabeled as dev would persist sensitive payloads.
  *
@@ -1842,6 +1944,15 @@ interface TraceSpan {
     message: string;
     type: string;
   };
+  /**
+   * Timestamped occurrences inside the span — `span.addEvent(...)` and
+   * `span.recordException(...)`. Carried through so a handled retry or a
+   * swallowed exception is visible on the span it happened in, which is the
+   * only place it is interpretable. Absent when the body recorded none.
+   */
+  events?: SpanEventPoint[];
+  /** OTel `SpanKind`; absent means `"internal"`. */
+  kind?: OtlpSpanKind;
   name: string;
   /** Start of this span relative to the trace's start, in ms. */
   offsetMs: number;
@@ -1860,12 +1971,25 @@ interface TraceSummary {
   rootName: string;
   shardKey?: string;
   /**
-   * Spans ordered by `(offsetMs, depth)`, ready to render as waterfall rows.
-   * Start time alone is not enough to order them: spans are recorded on
-   * completion and `startTs` has millisecond resolution, so a parent and its
-   * child routinely tie. Breaking that tie by depth makes the sequence a valid
-   * pre-order traversal of the span tree, so indenting each row by its `depth`
-   * yields the nesting without a separate tree walk.
+   * Spans in **pre-order**, ready to render as waterfall rows: every span is
+   * immediately followed by its own subtree, siblings in start order. So
+   * indenting each row by its `depth` yields the real nesting — the row above
+   * a `depth`-`n+1` row is genuinely its parent.
+   *
+   * This is a tree walk, not a sort, because no ordering on `(offsetMs,
+   * depth)` can produce it. Given a parent, its child `a`, `a`'s child `a1`
+   * and `a`'s sibling `b` all at offset 0, that comparator yields
+   * `parent, a, b, a1` — which renders `a1` indented beneath `b`, under a
+   * parent it does not belong to.
+   *
+   * **Why they tie is not millisecond resolution.** On the Workers runtime
+   * `Date.now()` is pinned to the time of the last I/O — a Spectre mitigation,
+   * not a bug — so it does not advance at all across pure computation. Every
+   * duration in this package is `Date.now() - startTs`, which means a span
+   * wrapping CPU-only work reports `0`, and a parent whose child performed no
+   * I/O shares its exact start and end. See `docs/concepts/observability`
+   * ("Span durations on Workers"); the practical consequence is that a `0 ms`
+   * span means "no I/O happened here", not "this was fast".
    */
   spans: TraceSpan[];
   startTs: number;
@@ -1880,10 +2004,19 @@ interface TraceSummary {
 declare class SpanBuffer {
   private readonly buffer;
   private readonly capacity;
+  /** How many spans the ring has evicted since it was last cleared. */
+  private droppedCount;
   constructor(capacity?: number);
+  /**
+   * Spans evicted for capacity since the last {@link SpanBuffer.clear}. The
+   * ring silently drops its oldest span once full, which makes a busy instance
+   * look identical to one that recorded exactly `capacity` spans; this count
+   * is the difference between the two.
+   */
+  get dropped(): number;
   /** Number of spans currently buffered. */
   get size(): number;
-  /** Drop every buffered span. */
+  /** Drop every buffered span, including the eviction count. */
   clear(): void;
   /** Snapshot of the buffered spans in insertion order. Fresh array per call. */
   entries(): SpanEvent[];
@@ -1965,4 +2098,61 @@ declare const resolveTraceAnchor: (traceparent: string | undefined) => {
   sampled: boolean;
   traceId: string;
 };
-export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AiRunBinding, type AppendRequestLogEntry, type AuthMetrics, type AuthMetricsBucket, type ContextFetch, type ContextLogLevel, type ContextMetrics, type ContextTracer, DEFAULT_EXPLAIN_ISSUE_MODEL, type DanglingReference, type DanglingReferenceResult, type DatabaseInstrumentation, type DatabaseTally, type DatabaseTelemetryDeps, type ErrorIssue, type ExplainIssueArgs, type ExplainIssueDegradedReason, type ExplainIssueGrounding, type ExplainIssueResult, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_MAX_PATHS, FUNCTION_METRICS_READ_LIMIT, FUNCTION_METRICS_SCANS_TABLE, FUNCTION_METRICS_TABLE, type FoldedTraces, type FunctionMetricBucket, type FunctionMetricBucketsResult, type FunctionMetricIndexHit, type HostSpanLike, type HostTracingLike, type HostTracingResolver, ISSUE_SEVERITIES, ISSUE_STATE_TABLE, ISSUE_STATUSES, type IndexHit, type IssueSeverity, type IssueState, type IssueStatePatch, type IssueStatus, type IssuesResult, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, MetricBuffer, type MetricEvent, type MetricHistoryOptions, type MetricHistoryPoint, type MetricHistoryResult, type MetricHistorySeries, type MetricKind, type MetricSeries, type MetricsDeps, type QueryInsightBucket, type QueryInsightEntry, type QueryInsightsResult, type QueryStatEntry, REQUEST_LOG_TABLE, type ReadIssuesOptions, type ReadRequestLogOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RequestLogEntry, type RequestLogResult, type RequestLogWriteOptions, type RequestOutcome, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, SpanBuffer, type SpanCollection, type SpanCollector, type SpanEvent, type SpanEventPoint, type SpanHandle, type OtlpSpanKind as SpanKind, type SpanLink, type SpanOptions, type TraceAnchor, type TraceSpan, type TraceSummary, type TracedFetchDeps, type TracerDeps, appendRequestLogEntry, buildSecurityAudit, createDatabaseTally, createMetrics, createSpanCollector, createTracedFetch, createTracer, dispatchRootSpan, emitLogEvent, emitRequestLogEvent, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureRequestLogTable, explainIssue, findDanglingReferences, foldTraces, formatTally, instrumentDatabase, mergeScanAttribution, parseExplainIssueArgs, parseLogArgs, readAuthMetrics, readErrorIssues, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetricScans, readFunctionMetrics, readFunctionMetricsTotals, readMetricHistory, readQueryInsights, readQueryMetrics, readRequestLog, recordAuthEvent, recordFunctionMetric, recordMetricHistory, recordQueryMetric, redactArgs, resolveTraceAnchor, upsertIssueState };
+export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AiRunBinding, type AppendRequestLogEntry,
+/**
+ * `@lunora/observability` — host-neutral telemetry storage and read models.
+ *
+ * Logs, traces, metrics, issue grouping and the security-audit view: the data
+ * behind the Studio's observability pages. None of it is Cloudflare-specific —
+ * it reads and writes through the SQL handle the engine hands it, and it lived
+ * inside `@lunora/do` only because that is where the Durable Object it
+ * instruments happens to live.
+ *
+ * The dependency runs `@lunora/do` → here → `@lunora/shard-engine`, never the
+ * reverse, which is what makes this reusable by a second host rather than
+ * merely relocated.
+ *
+ * This barrel is deliberately curated rather than `export *`. A star export
+ * would promote every module internal to permanent public API — the exact
+ * mistake `@lunora/do`'s own barrel documents having made once with the search
+ * core. What is exported here is what a consumer actually needs.
+ */
+type AuthMetrics,
+/**
+ * `@lunora/observability` — host-neutral telemetry storage and read models.
+ *
+ * Logs, traces, metrics, issue grouping and the security-audit view: the data
+ * behind the Studio's observability pages. None of it is Cloudflare-specific —
+ * it reads and writes through the SQL handle the engine hands it, and it lived
+ * inside `@lunora/do` only because that is where the Durable Object it
+ * instruments happens to live.
+ *
+ * The dependency runs `@lunora/do` → here → `@lunora/shard-engine`, never the
+ * reverse, which is what makes this reusable by a second host rather than
+ * merely relocated.
+ *
+ * This barrel is deliberately curated rather than `export *`. A star export
+ * would promote every module internal to permanent public API — the exact
+ * mistake `@lunora/do`'s own barrel documents having made once with the search
+ * core. What is exported here is what a consumer actually needs.
+ */
+type AuthMetricsBucket, type ContextFetch, type ContextLogLevel, type ContextMetrics, type ContextTracer, DEFAULT_EXPLAIN_ISSUE_MODEL, type DanglingReference, type DanglingReferenceResult, type DatabaseInstrumentation, type DatabaseTally, type DatabaseTelemetryDeps, type ErrorIssue, type ExplainIssueArgs, type ExplainIssueDegradedReason, type ExplainIssueGrounding, type ExplainIssueResult, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_MAX_PATHS, FUNCTION_METRICS_READ_LIMIT, FUNCTION_METRICS_SCANS_TABLE, FUNCTION_METRICS_TABLE, type FoldedTraces, type FunctionMetricBucket, type FunctionMetricBucketsResult, type FunctionMetricIndexHit, type HostSpanLike, type HostTracingLike, type HostTracingResolver, ISSUE_SEVERITIES, ISSUE_STATE_TABLE, ISSUE_STATUSES, type IndexHit, type IssueSeverity, type IssueState, type IssueStatePatch, type IssueStatus, type IssuesResult, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, MetricBuffer, type MetricEvent, type MetricHistoryOptions, type MetricHistoryPoint, type MetricHistoryResult, type MetricHistorySeries, type MetricKind, type MetricSeries, type MetricsDeps, type QueryInsightBucket, type QueryInsightEntry, type QueryInsightsResult, type QueryStatEntry, REQUEST_LOG_TABLE, type ReadIssuesOptions, type ReadRequestLogOptions,
+/**
+ * `@lunora/observability` — host-neutral telemetry storage and read models.
+ *
+ * Logs, traces, metrics, issue grouping and the security-audit view: the data
+ * behind the Studio's observability pages. None of it is Cloudflare-specific —
+ * it reads and writes through the SQL handle the engine hands it, and it lived
+ * inside `@lunora/do` only because that is where the Durable Object it
+ * instruments happens to live.
+ *
+ * The dependency runs `@lunora/do` → here → `@lunora/shard-engine`, never the
+ * reverse, which is what makes this reusable by a second host rather than
+ * merely relocated.
+ *
+ * This barrel is deliberately curated rather than `export *`. A star export
+ * would promote every module internal to permanent public API — the exact
+ * mistake `@lunora/do`'s own barrel documents having made once with the search
+ * core. What is exported here is what a consumer actually needs.
+ */
+type RecordAuthEventInput, type RecordFunctionMetricInput, type RequestLogEntry, type RequestLogResult, type RequestLogWriteOptions, type RequestOutcome, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, SpanBuffer, type SpanCollection, type SpanCollector, type SpanEvent, type SpanEventPoint, type SpanHandle, type OtlpSpanKind as SpanKind, type SpanLink, type SpanOptions, type TraceAnchor, type TraceSpan, type TraceSummary, type TracedFetchDeps, type TracerDeps, appendRequestLogEntry, buildSecurityAudit, createDatabaseTally, createMetrics, createSpanCollector, createTracedFetch, createTracer, dispatchRootSpan, emitLogEvent, emitRequestLogEvent, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureRequestLogTable, explainIssue, findDanglingReferences, foldTraces, formatTally, instrumentDatabase, mergeScanAttribution, parseExplainIssueArgs, parseLogArgs, readAuthMetrics, readErrorIssues, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetricScans, readFunctionMetrics, readFunctionMetricsTotals, readMetricHistory, readQueryInsights, readQueryMetrics, readRequestLog, recordAuthEvent, recordFunctionMetric, recordMetricHistory, recordQueryMetric, redactArgs, resolveTraceAnchor, upsertIssueState };