@lunora/observability 1.0.0-alpha.4 → 1.0.0-alpha.40

package/README.md

@@ -27,7 +27,7 @@ Three details are Cloudflare's rather than this package's, so the host passes th
 
 - **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.
+- **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;
 /**
@@ -488,6 +488,15 @@ type HostTracingResolver = () => HostTracingLike | Promise<HostTracingLike | und
 interface TracerDeps {
   /** The trace this ctx's spans belong to. */
   anchor: TraceAnchor;
+  /**
+   * Whether to record a span body's error message (and a `recordException`
+   * stacktrace) verbatim rather than redacted. Mirrors the request log's
+   * `captureRaw`: `true` in dev (`isDevEnvironment`), `false` in production —
+   * the span pipeline is the one sink third-party collectors (Datadog/Axiom
+   * via `otlpSink`) receive, so it must not ship raw PII/internals by default
+   * the way the request log and function-metrics sinks already don't.
+   */
+  captureRaw?: boolean;
   /** Function path the spans are attributed to. */
   functionPath: string;
   /**
@@ -544,11 +553,17 @@ interface SpanCollector {
  * attributes become the canonical one-event-per-request summary. Sharing the
  * implementation is what makes those two feel like the same API instead of two
  * that happen to resemble each other.
+ *
+ * `captureRaw` (default `false`) gates `recordException`'s `exception.message`/
+ * `exception.stacktrace` the same way {@link createTracer} gates a span's own
+ * error message — a stack is file paths and internals by definition, the exact
+ * 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;
-}) => SpanCollector;
+}, captureRaw?: boolean) => SpanCollector;
 /**
  * Build the `ctx.trace` span factory for one dispatched function.
  *
@@ -590,7 +605,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
@@ -673,6 +688,14 @@ declare const createMetrics: (deps: MetricsDeps) => ContextMetrics;
  */
 declare const dispatchRootSpan: (input: {
   anchor: TraceAnchor;
+  /**
+   * Whether to record the failure message verbatim rather than redacted —
+   * the same dev-only escape hatch as {@link TracerDeps.captureRaw}. This
+   * synthetic root span carries the SAME error message the request log and
+   * function-metrics sinks already redact by default, so it must not be the
+   * one durable copy that ships it raw to a third-party collector.
+   */
+  captureRaw?: boolean;
   /**
    * What the handler attached to the dispatch through `ctx.span` — the **wide
    * event**. These are the attributes that would otherwise have been scattered
@@ -715,6 +738,14 @@ type DatabaseInstrumentation = "off" | "spans" | "summary";
 interface DatabaseTelemetryDeps {
   /** The trace produced spans belong to (`"spans"` mode only). */
   anchor: TraceAnchor;
+  /**
+   * Whether to record a failed call's error message verbatim rather than
+   * redacted (`"spans"` mode only) — the same dev-only escape hatch as
+   * `TracerDeps.captureRaw`. A constraint-error message quotes the
+   * conflicting row, so this CLIENT span gets the same default-redacted
+   * posture as the request log and function-metrics sinks.
+   */
+  captureRaw?: boolean;
   /** Function path spans and attributes are attributed to. */
   functionPath: string;
   /** Detail level; see {@link DatabaseInstrumentation}. */
@@ -786,13 +817,23 @@ declare const FUNCTION_METRICS_BUCKET_RETENTION = 1440;
 /**
  * Maximum distinct function `path`s tracked in the accumulator table. Mirrors
  * `query-metrics.ts`'s `QUERY_METRICS_MAX_STATEMENTS` cap (and exists for the
- * same reason): the `path` is attacker-reachable — an unregistered/`FUNCTION_NOT_FOUND`
- * dispatch still records a row keyed by the caller-supplied `functionPath` — so
- * without a cap a flood of distinct random paths would grow `__lunora_metrics`
- * (and its bucket/scan satellites) without bound, eventually filling the shard's
- * SQLite store shared with the app's real data. A few thousand registered
- * functions is already far beyond any real app, so a new path past this cap is
- * dropped while already-tracked paths keep accumulating.
+ * same reason): the real bound is the app's own registered-function set plus
+ * deploy churn (a rename/removal leaves its old path's row in place, still
+ * counted against the cap, until an operator's own retention/cleanup
+ * process — there is none built in today) — a few thousand registered
+ * functions is already far beyond any real app. `shard-do.ts`'s dispatch
+ * handler explicitly does NOT record per-function metrics for an
+ * unregistered/`FUNCTION_NOT_FOUND` dispatch (see the guard next to its
+ * `FUNCTION_NOT_FOUND` check), so a caller cannot mint arbitrary `path`s here
+ * the way a raw caller-supplied SQL shape can in `query-metrics.ts`. Without a
+ * cap, deploy churn across the app's lifetime would still grow
+ * `__lunora_metrics` (and its bucket/scan satellites) without bound,
+ * eventually filling the shard's SQLite store shared with the app's real
+ * data. At the cap, a brand-new path is refused — protecting the incumbent
+ * leaderboard from a flood of one-off paths is the point, so admission is
+ * refused rather than evicting an existing path to make room; already-tracked
+ * paths keep accumulating past the cap. `readFunctionMetricsTotals`'s
+ * `capped` is the read-side signal for this.
  */
 declare const FUNCTION_METRICS_MAX_PATHS = 5e3;
 /**
@@ -814,6 +855,22 @@ interface FunctionMetricBucket {
   /** Subset of `calls` that threw. */
   errors: number;
 }
+/** {@link readFunctionMetricBuckets} result: the time-series window plus whether the read limit cut it short. */
+interface FunctionMetricBucketsResult {
+  buckets: (FunctionMetricBucket & {
+    path: string;
+  })[];
+  /**
+   * True when more rows existed than {@link FUNCTION_METRICS_READ_LIMIT} could
+   * return, so `buckets` is a partial (newest) window rather than the app's
+   * full retained history. Mirrors `readQueryInsights`'s `capped` and
+   * `foldTraces`'s `total`: a silently truncated read looks identical to a
+   * complete one to a caller that doesn't check for it — the Metrics chart's
+   * window would appear to shrink as the app grows, with a wrong leftmost
+   * bar, and nothing would say why.
+   */
+  truncated: boolean;
+}
 /** One declared index a dispatch exercised (used to narrow a read). */
 interface IndexHit {
   /** The declared index name. */
@@ -854,7 +911,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
@@ -879,7 +936,9 @@ interface RecordFunctionMetricInput {
  * than baked into the `CREATE` so a shard whose `__lunora_metrics` predates the
  * causal-attribution feature gains the column on the next call without a
  * migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the duplicate-column
- * error from a re-run is swallowed.
+ * error from a re-run is swallowed. Both the `CREATE`s and the back-fill only
+ * run once per handle (see {@link ensuredHandles}) — a handle already marked
+ * ensured returns immediately.
  */
 declare const ensureFunctionMetricsTables: (sql: SqlExec) => void;
 /**
@@ -934,18 +993,21 @@ declare const readFunctionMetrics: (sql: SqlExec) => FunctionCallStat[];
 /**
  * Read the coarse time-series buckets for `path` (every path when omitted),
  * oldest-bucket first so a chart can plot them left-to-right. Creates the table
- * first so reads on a never-called shard return `[]`.
+ * first so reads on a never-called shard return `{ buckets: [], truncated: false }`.
  */
-declare const readFunctionMetricBuckets: (sql: SqlExec, path?: string) => (FunctionMetricBucket & {
-  path: string;
-})[];
+declare const readFunctionMetricBuckets: (sql: SqlExec, path?: string) => FunctionMetricBucketsResult;
 /**
  * Aggregate the persisted accumulators into the lifetime totals the metrics
- * health snapshot reports: total calls (`requests`), total `errors`, and the
- * earliest `last_called_at` seen — a best-effort "since" marker for durable
- * data. Returns zeroes on a never-called shard.
+ * health snapshot reports: total calls (`requests`), total `errors`. Returns
+ * zeroes on a never-called shard.
+ *
+ * `capped` is true when the distinct-path cap ({@link FUNCTION_METRICS_MAX_PATHS})
+ * has been reached — the write-side signal that a brand-new function path is
+ * currently being refused (see `admitPath`), mirroring `readQueryInsights`'s
+ * `capped` for query-metrics and `readMetricHistory`'s for metric-history.
  */
 declare const readFunctionMetricsTotals: (sql: SqlExec) => {
+  capped: boolean;
   errors: number;
   requests: number;
 };
@@ -978,7 +1040,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;
@@ -1127,13 +1189,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.
@@ -1261,6 +1325,17 @@ interface MetricHistorySeries {
 }
 /** {@link readMetricHistory} result: every tracked series with its buckets. */
 interface MetricHistoryResult {
+  /**
+   * True when the distinct-series cap has been reached — a **write-side**
+   * signal ("this shard can no longer admit a brand-new series", see
+   * `admitNewSeries`), not a read-side truncation flag. It is computed over
+   * the whole table regardless of `options.sinceMs`/the row-count read
+   * limit, so it can be `true` even when every series `readMetricHistory`
+   * actually returned fits comfortably: the caller should read it as "a
+   * flood of new series would currently be refused", the same thing
+   * `readQueryInsights`'s `capped` already signals for query-metrics.
+   */
+  capped: boolean;
   series: MetricHistorySeries[];
 }
 /**
@@ -1269,7 +1344,7 @@ interface MetricHistoryResult {
  * omitted field keeps the historical behaviour.
  */
 interface MetricHistoryOptions {
-  /** Distinct series tracked before a brand-new one is dropped (default {@link METRIC_HISTORY_MAX_SERIES}). */
+  /** Distinct series tracked before the least-recently-updated one is evicted to admit a new one (default {@link METRIC_HISTORY_MAX_SERIES}). */
   maxSeries?: number;
   /** Minute-buckets kept per series before older rows are trimmed (default {@link METRIC_HISTORY_BUCKET_RETENTION}). */
   retentionBuckets?: number;
@@ -1306,9 +1381,12 @@ declare const recordMetricHistory: (sql: SqlExec, event: MetricEvent, exemplarTr
  * trend line reads oldest→newest.
  *
  * `options.sinceMs`, when set, returns only buckets at or after this epoch-ms —
- * the studio's time-window selector.
+ * the studio's time-window selector. `options.maxSeries`, mirroring the write
+ * side's tunable, is only used to compute `capped` — it does not affect which
+ * rows are read.
  */
 declare const readMetricHistory: (sql: SqlExec, options?: {
+  maxSeries?: number;
   sinceMs?: number;
 }) => MetricHistoryResult;
 /** One row of the `__lunora_metrics_queries` table, as returned by `readQueryMetrics`. */
@@ -1369,14 +1447,23 @@ interface QueryInsightsResult {
  */
 declare const readQueryInsights: (sql: SqlExec, rangeMs: number, now?: number) => QueryInsightsResult;
 /**
- * Record one statement execution. Creates the table on first call. Silently
+ * Record one statement's activity. Creates the table on first call. Silently
  * skips recording when the normalised statement is empty (shouldn't happen
  * in practice) or when the table is already at the
  * {@link QUERY_METRICS_MAX_STATEMENTS} cap and the statement is not yet
- * tracked. The cap check is a single cheap `COUNT(*)` on the primary-key
- * index, so the hot-path cost is minimal.
+ * tracked. See `admitStatement` for how the cap check avoids an unconditional
+ * `COUNT(*)` on every execution.
+ *
+ * `execCount` (default 1) lets a caller fold several executions of the SAME
+ * statement into one call — `shard-do.ts` does this per dispatch so a
+ * query-in-a-loop handler pays one upsert here instead of one per raw
+ * execution. `durationMs`/`rowsRead`/`rowsWritten` are then the SUM across
+ * `execCount` executions, exactly as `exec_count`/`total_duration_ms` already
+ * accumulate sums across separate calls — folding before calling is
+ * indistinguishable, from this table's point of view, from `execCount`
+ * separate calls with the same totals.
  */
-declare const recordQueryMetric: (sql: SqlExec, rawSql: string, durationMs: number, rowsRead: number, rowsWritten: number, now?: number) => void;
+declare const recordQueryMetric: (sql: SqlExec, rawSql: string, durationMs: number, rowsRead: number, rowsWritten: number, now?: number, execCount?: number) => void;
 /**
  * Read all tracked statement aggregates, ordered by `total_duration_ms DESC`
  * (the leaderboard's default). Creates the table first so a read on a
@@ -1393,9 +1480,9 @@ interface RequestLogEntry {
   cacheHit?: boolean;
   /** Handler wall-clock duration in milliseconds (before the subscription write-flush, matching the per-function metrics). */
   durationMs: number;
-  /** Error message when `outcome === "error"`; absent on success. */
+  /** 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>;
@@ -1413,6 +1500,8 @@ 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. */
@@ -1431,6 +1520,7 @@ interface AppendRequestLogEntry {
   subscriptionsReRun?: number;
   tablesRead?: string[];
   tablesWritten?: string[];
+  traceId?: string;
   ts: number;
   userId?: string;
 }
@@ -1443,7 +1533,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;
@@ -1473,15 +1563,20 @@ 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;
-  /** Stable 16-char grouping hash over `functionPath :: bucket(message)`. */
+  /**
+   * Stable 16-char grouping hash over `functionPath :: bucket(message)`,
+   * computed from the RAW (pre-redaction) message at write time and stored on
+   * the row — see {@link appendRequestLogEntry} — so redacting `sampleMessage`
+   * below can't change the grouping.
+   */
   hash: string;
   /** Wall-clock millis of the newest folded row. */
   lastSeen: number;
-  /** A representative raw error message — taken from the most recent folded row. */
+  /** A representative error message (redacted, like the durable row) — taken from the most recent folded row. */
   sampleMessage: string;
   /** Developer-tagged severity from the persisted triage state; absent when untriaged. */
   severity?: IssueSeverity;
@@ -1507,7 +1602,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;
@@ -1518,21 +1613,78 @@ interface ReadIssuesOptions {
   /** Exact acting-userId match. */
   userId?: string;
 }
+/**
+ * Redact the secrets / PII out of a value before it reaches the durable log or a
+ * Logpush event, via `@visulima/redact`'s `standardRules`. Unlike a blunt
+ * type-tag stamp this masks sensitive values by PATTERN (not just by key name)
+ * while leaving benign values readable, so the studio's args/identity columns
+ * stay useful. `null` / `undefined` pass through unchanged.
+ *
+ * What `standardRules` actually catches differs by shape, verified against its
+ * real behavior rather than assumed from its name: on a KEYED object (`args`,
+ * `identity`) it also matches by key name, so `{ password: "hunter2" }` and
+ * `{ token: "…" }` ARE masked regardless of the value's shape. On a PLAIN
+ * 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 <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,
+ * not a general secrets scrubber; a handler that echoes a raw credential into
+ * an error message or a log string can still leak it through here. Works on a
+ * plain string too (`redact` traverses whatever value it's handed), which is
+ * how {@link appendRequestLogEntry} and {@link emitRequestLogEvent} reuse this
+ * for `errorMessage` — a validation error echoes the offending value, a
+ * constraint error quotes the conflicting row, so the error message is at
+ * least as PII-dense as args and gets the same treatment (with the free-text
+ * caveat above).
+ *
+ * `captureRaw` is the development escape hatch: in a dev environment the dispatch
+ * site (`isDevEnvironment`) passes `true` to skip redaction so a developer can
+ * see real arg/identity/error values; production always redacts. The dev
+ * decision is made at the call site from the deployment env, never inferred
+ * here — so a real deploy that omits the env var stays redacted.
+ */
+declare const redactArgs: (value: unknown, captureRaw?: boolean) => unknown;
 /**
  * Create the `__lunora_reqlog__` table. `seq` is an `AUTOINCREMENT` primary
  * key, giving each shard a monotonic cursor the Logs tab pages through; the
  * `args`/`identity`/`tables_read`/`tables_written` columns hold JSON and are
  * `NULL`/empty when none was recorded. Idempotent, so read and write paths can
  * call it defensively.
+ *
+ * `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. `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 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 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;
 /**
  * Append one dispatch to the request log, then trim the log back to the most
  * recent `retention` rows (default {@link REQUEST_LOG_RETENTION}). Creates the
- * table first so callers needn't. Args/identity are redacted here so a raw value
- * never reaches the durable table — callers pass the unredacted entry and rely on
- * this, unless `captureRaw` (dev only) is set. `retention` is the operator's
- * `LUNORA_REQUEST_LOG_RETENTION` override, threaded in by the dispatch site.
+ * table first so callers needn't. Args/identity/error message are redacted here
+ * so a raw value never reaches the durable table — callers pass the unredacted
+ * entry and rely on this, unless `captureRaw` (dev only) is set. `retention` is
+ * the operator's `LUNORA_REQUEST_LOG_RETENTION` override, threaded in by the
+ * dispatch site.
+ *
+ * The error-grouping fingerprint is computed from `entry.errorMessage` BEFORE
+ * 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 `<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;
 /**
@@ -1541,8 +1693,8 @@ declare const appendRequestLogEntry: (sql: SqlExec, entry: AppendRequestLogEntry
  * NOT reimplement a transport: it produces a richer, lunora-attributed event and
  * lets CF's existing trace-log pipe ship it. The event mirrors the durable
  * `__lunora_reqlog__` row (function path, shard, user, outcome, duration, tables
- * read/written, cache hit), with `args` AND `identity` redacted exactly like the
- * durable write so no raw PII/secret reaches the log pipeline.
+ * read/written, cache hit), with `args`, `identity`, AND `error` redacted
+ * exactly like the durable write so no raw PII/secret reaches the log pipeline.
  *
  * An `error` outcome goes to `console.error` (surfacing at error level in the
  * trace so a SIEM can alert on it); everything else to `console.log`. The
@@ -1560,7 +1712,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
@@ -1591,11 +1743,19 @@ declare const parseLogArgs: (args: unknown[], boundFields?: LogFields) => {
  *
  * Structured `fields` (plus `traceId`/`spanId` for correlation) ARE emitted here
  * — they are intentional metadata a log pipeline filters on, unlike raw `args`.
- * A field value that can't be serialised (a circular object) would make
- * `JSON.stringify` throw and drop the whole line, so serialisation falls back to
- * a fields-free line rather than losing the event.
- */
-declare const emitLogEvent: (input: LogEventInput) => void;
+ * Unlike `args`, `fields` IS redacted before it rides this console line — a
+ * developer can attach anything to a fields bag (`ctx.log.info("charged",
+ * { email, cardLast4 })`), and this is the one line that's told to a SIEM as
+ * trustworthy, exactly like the request-log `args`/`identity`/`error` columns.
+ * `options.captureRaw` (dev only) skips it, mirroring every other redaction
+ * point in this module; the sole current caller (`ShardDO.recordUserLog`)
+ * doesn't yet thread a dev flag through, so `fields` redacts unconditionally
+ * there today — a conservative default, never a correctness gap. A field value
+ * that can't be serialised (a circular object) would make `JSON.stringify`
+ * throw and drop the whole line, so serialisation falls back to a fields-free
+ * line rather than losing the event.
+ */
+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
@@ -1692,6 +1852,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;
@@ -1710,12 +1879,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;
@@ -1815,4 +1997,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 DatabaseInstrumentation, type DatabaseTally, 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 FunctionMetricBucket, type FunctionMetricIndexHit, type HostTracingLike, 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 MetricHistoryOptions, type MetricHistoryPoint, type MetricHistorySeries, type MetricSeries, type MetricsDeps, type QueryStatEntry, REQUEST_LOG_TABLE, type RecordAuthEventInput, type RecordFunctionMetricInput, type RequestLogResult, type RequestLogWriteOptions, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, SpanBuffer, type SpanCollection, type SpanCollector, type SpanHandle, type TraceAnchor, type TraceSpan, type TraceSummary, 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, 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 };