@lunora/observability 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,1818 @@
+import { SqlExec, FunctionScanAttribution, FunctionCallStat } from '@lunora/shard-engine';
+/** Reserved single-row auth accumulator table. Auto-hidden from the data browser by the `__lunora` prefix. */
+declare const AUTH_METRICS_TABLE = "__lunora_auth_metrics";
+/** Reserved coarse time-series table: app-wide auth attempt/failure counts bucketed by a fixed window. */
+declare const AUTH_METRICS_BUCKETS_TABLE = "__lunora_auth_metrics_buckets";
+/**
+ * Width of one history bucket, in milliseconds. 60s gives a minute-resolution
+ * time series — fine-grained enough to chart a burst of failed sign-ins on the
+ * studio, coarse enough that auth emits at most one row per minute. Mirrors
+ * `FUNCTION_METRICS_BUCKET_MS`.
+ */
+declare const AUTH_METRICS_BUCKET_MS = 6e4;
+/**
+ * Most recent buckets kept; older rows are trimmed after each write so the time
+ * series can't grow unbounded. 1440 minute-buckets ≈ 24h of auth history.
+ */
+declare const AUTH_METRICS_BUCKET_RETENTION = 1440;
+/** One coarse time-series sample: auth attempt/failure counts within `[bucketMs, bucketMs + AUTH_METRICS_BUCKET_MS)`. */
+interface AuthMetricsBucket {
+  /** Auth attempts recorded in this window. */
+  attempts: number;
+  /** Epoch-ms floor of the bucket window. */
+  bucketMs: number;
+  /** Subset of `attempts` that failed (HTTP ≥ 400). */
+  failures: number;
+}
+/**
+ * Lifetime auth health for the app, served by `__lunora_admin__:getAuthMetrics`
+ * and consumed by the studio SLO panel. `failureRate` is the derived
+ * `failures / attempts` (0 when there have been no attempts), surfaced so the
+ * panel needn't recompute it; `sinceMs` is the epoch-ms the first attempt was
+ * recorded (a best-effort "since" marker); `history` is the minute-bucketed
+ * series for the sparkline, oldest bucket first.
+ */
+interface AuthMetrics {
+  /** Total auth attempts (sign-in / sign-up / callback) recorded. */
+  attempts: number;
+  /** Derived `attempts === 0 ? 0 : failures / attempts`. */
+  failureRate: number;
+  /** Subset of `attempts` that failed (the auth route answered HTTP ≥ 400). */
+  failures: number;
+  /** Minute-bucketed attempt/failure series for the sparkline, oldest bucket first. */
+  history: AuthMetricsBucket[];
+  /** Epoch-ms the first attempt was recorded, or `0` on a never-seen app. */
+  sinceMs: number;
+}
+/** Fields recorded for one auth attempt. `outcome === "fail"` advances the failure counters. */
+interface RecordAuthEventInput {
+  /** `"ok"` for a 2xx/3xx auth response, `"fail"` for an HTTP ≥ 400 response. */
+  outcome: "fail" | "ok";
+  /** Epoch-ms the auth attempt completed. */
+  ts: number;
+}
+/**
+ * Create the two reserved auth-metrics tables. Idempotent, so the read and write
+ * paths can call it defensively. The accumulator is a single keyed row; the
+ * bucket table is keyed by `bucket_ms` (one row per minute window).
+ */
+declare const ensureAuthMetricsTables: (sql: SqlExec) => void;
+/**
+ * Persist one auth attempt: a single upsert into the accumulator row and one
+ * upsert into the current time bucket, then a bounded trim of old buckets.
+ * Creates the tables first so callers needn't. `attempts` always advances;
+ * `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.
+ */
+declare const recordAuthEvent: (sql: SqlExec, input: RecordAuthEventInput) => void;
+/**
+ * Read the durable auth metrics as the {@link AuthMetrics} wire shape the
+ * studio SLO panel consumes. Creates the tables first so a read on a
+ * never-authenticated app returns an all-zero shape (empty `history`) instead of
+ * throwing. `failureRate` is derived here so the consumer needn't recompute it.
+ */
+declare const readAuthMetrics: (sql: SqlExec) => AuthMetrics;
+/**
+ * Shared, bundler-inlined helpers for the structured `fields` a
+ * `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call carries.
+ *
+ * Inlined (like {@link file://./otlp.ts}) so `@lunora/do`, `@lunora/runtime`,
+ * `@lunora/config`, and `@lunora/studio` — which sit on different tiers with no
+ * acceptable runtime dependency edge between them — share ONE implementation of
+ * field rendering/normalization instead of the byte-identical copies they would
+ * otherwise hand-mirror. Keep this genuinely zero-dependency (only built-ins) so
+ * inlining into each `dist` stays sound.
+ */
+/** Structured, filterable key/value fields attached to a `ctx.log` line. */
+type LogFields = Record<string, unknown>;
+/**
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
+ *
+ * - `counter` — a monotonic delta to add up (requests, retries, bytes sent).
+ * - `gauge` — a point-in-time reading that replaces the last one (queue depth,
+ *   cache size).
+ * - `histogram` — a value whose *distribution* matters (latency, payload size),
+ *   giving percentiles rather than just a mean.
+ */
+type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * One measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
+ */
+interface MetricEvent {
+  /**
+   * Structured attributes the caller attached, normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
+   * dimensions — keep them low-cardinality; an id-valued attribute creates a
+   * distinct time series per id.
+   *
+   * Caller-controlled, so they MAY contain user input and they DO egress to
+   * whatever destination the sink ships to — the same caveat as a log line's
+   * `fields` and a span's `error.message`. Scrub upstream if that matters.
+   */
+  attributes?: LogFields;
+  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
+  functionPath: string;
+  /** Instrument kind; see {@link MetricKind}. */
+  kind: MetricKind;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /**
+   * Trace id of the dispatch that recorded this measurement, when it ran inside
+   * one — the measurement's **exemplar**, letting a consumer jump from a metric
+   * point to a trace that produced it (OpenTelemetry's exemplar model). Stamped
+   * by the shard from the current request's trace context, not by the caller.
+   */
+  traceId?: string;
+  /** Wall-clock millis when the measurement was recorded. */
+  ts: number;
+  /**
+   * The measured value: the increment for a `counter`, the current reading for
+   * a `gauge`, the observed sample for a `histogram`.
+   */
+  value: number;
+}
+/** One eval verdict to turn into `gen_ai.evaluation.*` attributes. */
+interface EvaluationInput {
+  /**
+   * Optional categorical label (e.g. `"pass"` / `"fail"` / a rubric bucket),
+   * emitted as the `.label` attribute. Omitted → no label attribute.
+   */
+  label?: string;
+  /**
+   * The scorer/evaluation name — becomes the key's name segment. Any character
+   * outside `[A-Za-z0-9._-]` is replaced with `_` so a scorer name carrying a
+   * colon (e.g. `"contains:shipped"`) still yields a well-formed attribute key.
+   */
+  name: string;
+  /** The numeric score (typically `[0, 1]`), emitted as the `.score` attribute. */
+  score: 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";
+/**
+ * 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
+ * its children under.
+ *
+ * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
+ * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
+ * no reformatting.
+ */
+/**
+ * Handle the enclosing `ctx.trace` span hands its body, so the body can attach
+ * attributes only known *after* it resolves — an AI call's token usage or dollar
+ * cost, a downstream response's status, a computed row count. The start
+ * attributes passed to `ctx.trace(name, fn, attributes)` are snapshotted before
+ * the body runs (so a mid-span mutation can't rewrite them); anything set through
+ * this handle is merged over that snapshot at record time, with the post-hoc
+ * 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;
+  /**
+   * Attach an AI **evaluation** verdict to this (generation) span as the
+   * `gen_ai.evaluation.<name>.score` / `.label` OpenTelemetry attributes, so a
+   * scorer's grade rides the same trace as the generation it graded and the
+   * collector reads it straight off the span. Convenience over
+   * {@link SpanHandle.setAttributes} that owns the key format; privacy-safe —
+   * only the name, score, and optional label are emitted, never the graded
+   * prompt or completion. Throws on an empty name or a non-finite score.
+   */
+  recordEvaluation: (evaluation: EvaluationInput) => 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 {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * 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
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
+  error?: {
+    message: string;
+    type: string;
+  };
+  /**
+   * Function path the span was created under, e.g. `"messages:list"`. A span
+   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
+   * `runAction` carries the OUTER entrypoint's path, since the composed call
+   * reuses its context — the same attribution rule `ctx.log` follows.
+   */
+  functionPath: string;
+  /**
+   * 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. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+ * Structural shape of the `ctx.trace` span factory (see the server
+ * `LunoraTracer`). Declared here rather than imported so `@lunora/do` takes no
+ * dependency on `@lunora/server`; a cross-package assignability guard in
+ * `@lunora/testing` fails the build if the two drift apart.
+ *
+ * The body's second argument is the enclosing span's {@link SpanHandle}, through
+ * 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>;
+/** Structural shape of the `ctx.metrics` recorder (see the server `LunoraMetrics`). */
+interface ContextMetrics {
+  count: (name: string, value?: number, attributes?: LogFields) => void;
+  gauge: (name: string, value: number, attributes?: LogFields) => void;
+  record: (name: string, value: number, attributes?: LogFields) => void;
+}
+/** The trace a ctx's spans hang off: the shared id, and the span they parent to. */
+interface TraceAnchor {
+  rootSpanId: string;
+  /**
+   * The W3C `sampled` verdict for this trace, inherited from the inbound
+   * `traceparent` when there was one. Carried on the anchor rather than
+   * re-derived per outbound call so every `ctx.fetch` of one dispatch
+   * propagates the same answer.
+   */
+  sampled?: boolean;
+  traceId: string;
+}
+/**
+ * Minimal structural shape of one **host-native custom span** — the object a
+ * `tracing.enterSpan(name, (span) => …)` callback receives (GA 2026-06-16). Only
+ * the surface the bridge touches is declared, so `@lunora/do` needs no runtime
+ * dependency on `cloudflare:workers`; the real platform span is structurally
+ * assignable.
+ */
+/**
+ * A host-supplied span, structurally.
+ *
+ * Named for the role rather than the provider: this is whatever the runtime's
+ * own tracer hands back, and Cloudflare's `enterSpan` callback argument is one
+ * shape that satisfies it. Kept structural so no provider type is imported —
+ * the repo's documented `*Like` pattern.
+ */
+interface HostSpanLike {
+  /**
+   * Whether this span is actually being recorded by the runtime's sampler.
+   * `false` off the traced path (unsampled) — the bridge skips its
+   * `setAttribute` work in that case rather than building attribute strings for
+   * a span nobody will read.
+   */
+  readonly isTraced: boolean;
+  /** Attach one primitive attribute to the CF span. */
+  setAttribute: (key: string, value: boolean | number | string | undefined) => void;
+}
+/**
+ * Minimal structural shape of the `tracing` namespace exported by
+ * `cloudflare:workers`. `enterSpan` opens a custom span that auto-nests under the
+ * runtime's ambient span and ends when `callback` settles.
+ */
+interface HostTracingLike {
+  enterSpan: <T>(name: string, callback: (span: HostSpanLike) => T) => T;
+}
+/**
+ * Resolves CF's `tracing` namespace, or `undefined` when it is unavailable —
+ * on a host with no native tracer, on a Cloudflare compat date predating custom spans, or when
+ * `tracing.enterSpan` is not a function. **Injected, never imported here**, so the
+ * tracer stays pure and unit-testable without `cloudflare:workers`; the shard
+ * supplies the real resolver, tests a fake or `undefined`.
+ */
+type HostTracingResolver = () => HostTracingLike | Promise<HostTracingLike | undefined> | undefined;
+/** What {@link createTracer} needs from the shard to build a span. */
+interface TracerDeps {
+  /** The trace this ctx's spans belong to. */
+  anchor: TraceAnchor;
+  /** Function path the spans are attributed to. */
+  functionPath: string;
+  /**
+   * **Opt-in, EXPERIMENTAL, default off.** When `true` *and*
+   * {@link TracerDeps.resolveHostTracing} yields a working
+   * `tracing.enterSpan`, each `ctx.trace` span is ALSO emitted as a host-native
+   * **custom span**, so it nests inside CF's native binding/fetch/handler trace
+   * tree on the hosted path. This only ADDS a CF-side span — the recorded
+   * {@link SpanEvent} (our `SpanBuffer`/`otlpSink`) is untouched and remains the
+   * source of truth plus the local studio waterfall. The `enterSpan` call itself
+   * is now workerd-validated as available and side-effect-free inside a Durable
+   * Object; CF's exported parent-linking under sampling remains unverified. See
+   * {@link createTracer} for the double-export and Durable-Object async-context
+   * caveats.
+   */
+  fuseHostSpans?: boolean;
+  /** Hand a finished span to the buffer + sink. */
+  record: (span: SpanEvent) => void;
+  /**
+   * Injected resolver for CF's `tracing` namespace (see
+   * {@link HostTracingResolver}). Only consulted when
+   * {@link TracerDeps.fuseHostSpans} is `true`, so the default path never
+   * calls it.
+   */
+  resolveHostTracing?: HostTracingResolver;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey: string | undefined;
+  /** Read lazily — the acting user is resolved per span, not per ctx. */
+  userId: () => string | undefined;
+}
+/** What {@link createMetrics} needs from the shard to build a measurement. */
+interface MetricsDeps {
+  functionPath: string;
+  record: (event: MetricEvent) => void;
+  shardKey: string | undefined;
+}
+/** 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[];
+}
+/** A {@link SpanHandle} plus read access to what it has collected so far. */
+interface SpanCollector {
+  collected: SpanCollection;
+  handle: SpanHandle;
+}
+/**
+ * Build a span's post-hoc collection surface: the {@link SpanHandle} handed to a
+ * `ctx.trace` body, and the bag it writes into.
+ *
+ * Factored out because the same surface backs two things — every `ctx.trace`
+ * span, and the per-dispatch **wide event** (`ctx.span`), where the accumulated
+ * 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.
+ */
+declare const createSpanCollector: (ids: {
+  spanId: string;
+  traceId: string;
+}) => SpanCollector;
+/**
+ * Build the `ctx.trace` span factory for one dispatched function.
+ *
+ * **Nesting is explicit, not ambient.** Each span's body receives a tracer bound
+ * to that span; calling it is what makes a child. An earlier design kept an
+ * ambient stack of "the currently open span" and parented to its top, which
+ * reads nicer but is unfixably wrong under concurrency: in
+ * `Promise.all([trace("a", …), trace("b", …)])`, `b` starts while `a` is on the
+ * stack and is recorded as a *child* of `a` rather than its sibling — and
+ * parallel fan-out is one of the main things people reach for a tracer to
+ * measure. Distinguishing "called inside a's body" from "called concurrently
+ * with a" needs `AsyncLocalStorage`, which this package deliberately avoids (see
+ * `dependency-tracker.ts` — shard DOs run under a slimmer compat profile than
+ * `nodejs_compat`). So the parent is threaded, exactly like the dependency
+ * tracker and the subscription identity: correct in every case, and visible at
+ * the call site.
+ *
+ * The anchor is passed in for the same reason. `ShardDO.currentRequestTrace` is
+ * cleared in the dispatch `finally`, and a subscription re-run builds its ctx
+ * during* the writing mutation's flush — so reading that shared field at span
+ * time would file the re-run's spans under the mutation's trace.
+ *
+ * **Cloudflare custom-spans bridge (opt-in, EXPERIMENTAL).** When
+ * `deps.fuseHostSpans` is `true` and `deps.resolveHostTracing` yields
+ * a working `tracing.enterSpan` (`cloudflare:workers`, GA 2026-06-16), each span
+ * body runs inside a CF custom span so our span nests under CF's native
+ * binding/fetch/handler trace tree on the hosted path, and the finished span's
+ * key attributes are mirrored onto it (gated on `span.isTraced`). Two deliberate
+ * boundaries hold.
+ *
+ * **No double-export by default, and never a replacement.** The bridge only ADDS a
+ * CF-side span; the recorded {@link SpanEvent} handed to `record` (our
+ * `SpanBuffer`/`otlpSink`) is byte-for-byte the same as without the bridge and
+ * stays the source of truth. It is off unless explicitly enabled precisely
+ * because, once on, a deployment that ALSO ships our `otlpSink` to a collector
+ * AND lets CF export its trace tree emits the same logical span down two
+ * pipelines — an intentional, documented trade the operator opts into, not a
+ * default.
+ *
+ * **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
+ * `__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
+ * guarantee — our recorded {@link SpanEvent} tree (parent/child via the threaded
+ * `parentSpanId`) is byte-for-byte identical with the bridge on vs off. What that
+ * harness CANNOT prove is CF's own *exported* parent-linking: with no trace head
+ * attached the run is unsampled (`isTraced === false`), so CF records nothing and
+ * its span tree is not introspectable. So `enterSpan`'s ambient-span parent-linking
+ * inside a DO stays unverified upstream, and this remains capability-probed: an
+ * absent/undefined `tracing`, a missing `enterSpan`, or an off-CF/unsampled run all
+ * resolve to `undefined`/no-op — exact prior behavior. If CF's ambient-span linkage
+ * misbehaves in a DO, the worst case is a mis-parented CF span; our own recorded
+ * waterfall is unaffected.
+ */
+declare const createTracer: (deps: TracerDeps) => ContextTracer;
+/** What {@link createTracedFetch} needs from the shard. */
+interface TracedFetchDeps {
+  /** The trace the CLIENT spans belong to. */
+  anchor: TraceAnchor;
+  /** Function path the spans are attributed to. */
+  functionPath: string;
+  /**
+   * Whether to inject `traceparent` into the outbound request — and, with a
+   * predicate, to which destinations. Default `true`.
+   */
+  propagate?: ((url: URL) => boolean) | boolean;
+  /** Hand a finished span to the buffer + sink. */
+  record: (span: SpanEvent) => void;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey: string | undefined;
+  /** Read lazily — the acting user is resolved per span. */
+  userId: () => string | undefined;
+}
+/** 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 `ctx.fetch`: the platform `fetch`, wrapped so every outbound call
+ * becomes a **CLIENT span** and carries W3C trace context to the callee.
+ *
+ * Two gaps close here. First, an uninstrumented `fetch` makes the single most
+ * common source of latency — waiting on somebody else's service — invisible: a
+ * handler that spends 900ms in Stripe shows one opaque 900ms bar. Second,
+ * without an outbound `traceparent` the callee starts a brand-new trace, so the
+ * two halves of one logical request can never be stitched together, which is the
+ * entire premise of distributed tracing.
+ *
+ * The span id is minted BEFORE the request is sent, precisely so the header
+ * announces the id the span will actually be recorded under. Deriving it
+ * afterwards (or reusing the parent's) would produce a `traceparent` naming a
+ * span that never existed, and a callee parented to nothing.
+ *
+ * Kind is `client` rather than `internal` — that is what lets a collector draw
+ * the edge to the downstream service in a service map.
+ *
+ * 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
+ * control.
+ */
+declare const createTracedFetch: (deps: TracedFetchDeps, base: ContextFetch) => ContextFetch;
+/**
+ * Build the `ctx.metrics` recorder for one dispatched function.
+ *
+ * Deliberately stateless: each call emits one measurement rather than
+ * accumulating into a per-dispatch map. Pre-aggregating here would have to pick a
+ * flush point and a merge rule per instrument kind (sum a counter, last-wins a
+ * gauge, and a histogram cannot be merged at all without losing the
+ * distribution) — so the runtime stays a transport and the collector, which is
+ * built for exactly this, does the aggregation.
+ */
+declare const createMetrics: (deps: MetricsDeps) => ContextMetrics;
+/**
+ * Build the synthetic root span for a finished dispatch — the bar the studio's
+ * waterfall hangs a request's `ctx.trace` spans under.
+ *
+ * Pure: the caller decides whether to record it (only when the dispatch actually
+ * produced spans) and where to put it. It is never routed to `sink.onSpan`,
+ * because the runtime already emits the dispatch to `onRpc` and a collector would
+ * otherwise show it twice.
+ */
+declare const dispatchRootSpan: (input: {
+  anchor: TraceAnchor;
+  /**
+   * 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;
+  } | undefined;
+  functionPath: string;
+  shardKey: string | undefined;
+  startTs: number;
+  userId: string | undefined;
+}) => SpanEvent;
+/** Running totals for `"summary"` mode; created by the caller, read once at the dispatch boundary. */
+interface DatabaseTally {
+  calls: number;
+  durationMs: number;
+  errors: number;
+  perOperation: Record<string, number>;
+  spansEmitted: number;
+  spansTruncated: boolean;
+}
+/**
+ * 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";
+/** What {@link instrumentDatabase} needs to record what it observes. */
+interface DatabaseTelemetryDeps {
+  /** The trace produced spans belong to (`"spans"` mode only). */
+  anchor: TraceAnchor;
+  /** Function path spans and attributes are attributed to. */
+  functionPath: string;
+  /** Detail level; see {@link DatabaseInstrumentation}. */
+  mode: DatabaseInstrumentation;
+  /** Hand a finished span to the buffer + sink (`"spans"` mode only). */
+  record: (span: SpanEvent) => void;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey: string | undefined;
+  /**
+   * Caller-supplied accumulator for `"summary"` mode. The instrumenter only ever
+   * increments numbers on it; the shard reads it ONCE at the dispatch boundary
+   * and formats it with {@link formatTally}.
+   *
+   * Two properties fall out of that split. Per-call cost stays at a few integer
+   * increments — no object allocation, no lookup — which matters because this is
+   * on the path of every query. And because nothing is written through the
+   * dispatch's `SpanHandle`, the wide-event collector is never materialized, so
+   * a handler that instrumented nothing still doesn't trip the root-span gate.
+   */
+  tally: DatabaseTally;
+  /** Read lazily — the acting user is resolved per span. */
+  userId: () => string | undefined;
+}
+/**
+ * Wrap a `ctx.db` writer so its storage-touching methods are instrumented.
+ *
+ * Returns the database unchanged when `mode` is `"off"`, so the default-disabled
+ * path costs nothing — not even a proxy indirection.
+ *
+ * Implemented as a `Proxy` rather than by enumerating and rebinding methods:
+ * `DatabaseWriterLike` has optional members that a given backend may or may not
+ * implement, plus properties (`system`) and builder factories (`query`) that
+ * must pass through untouched. A proxy instruments exactly what it is asked to
+ * and is transparently correct for everything else, including members added
+ * later — an enumeration would silently stop covering them.
+ */
+declare const instrumentDatabase: <T extends object>(database: T, deps: DatabaseTelemetryDeps) => T;
+/** A zero'd tally for one dispatch. */
+declare const createDatabaseTally: () => DatabaseTally;
+/**
+ * Render the running tally as span attributes.
+ *
+ * Called ONCE per dispatch, from the shard's root-span recorder — not per query.
+ * Building this object on every call was pure waste on a hot path. It is a handful of keys, so the per-call cost is a small object
+ * assignment — the property that makes `"summary"` mode scale to any call count.
+ */
+declare const formatTally: (tally: DatabaseTally) => LogFields;
+/** Reserved per-function accumulator table. Auto-hidden from the data browser by the `__lunora` prefix. */
+declare const FUNCTION_METRICS_TABLE = "__lunora_metrics";
+/** Reserved coarse time-series table: per-function call/error counts bucketed by a fixed window. */
+declare const FUNCTION_METRICS_BUCKETS_TABLE = "__lunora_metrics_buckets";
+/** Reserved causal full-scan attribution table: per-(function, table) full-scan counts. */
+declare const FUNCTION_METRICS_SCANS_TABLE = "__lunora_metrics_scans";
+/** Reserved per-(table, index) hit-counter table backing the advisor dead-index lint. */
+declare const FUNCTION_METRICS_INDEX_TABLE = "__lunora_metrics_index";
+/**
+ * Width of one history bucket, in milliseconds. 60s gives a minute-resolution
+ * time series — fine-grained enough to chart bursts on the studio, coarse
+ * enough that a single function emits at most one row per minute. Exported so
+ * consumers (and tests) can align timestamps to the same grid.
+ */
+declare const FUNCTION_METRICS_BUCKET_MS = 6e4;
+/**
+ * Most recent buckets kept per function; older rows are trimmed after each
+ * write so the time series can't grow unbounded. 1440 minute-buckets ≈ 24h of
+ * history per function.
+ */
+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.
+ */
+declare const FUNCTION_METRICS_MAX_PATHS = 5e3;
+/**
+ * Upper bound on rows the admin reads materialize into DO memory at once. Even
+ * with the write-side `FUNCTION_METRICS_MAX_PATHS` cap in place, an existing
+ * shard could already hold a bloated accumulator (rows written before the cap
+ * landed), so the read path also clamps — a `SELECT *` with no LIMIT would
+ * otherwise load every row via `.toArray()` and risk OOMing the ~128MB DO when
+ * the studio Function Stats panel opens. Ordered reads keep the busiest/most
+ * recent rows; the tail past this limit is simply not returned to the panel.
+ */
+declare const FUNCTION_METRICS_READ_LIMIT = 1e3;
+/** One coarse time-series sample for a function: call/error counts within `[bucketMs, bucketMs + FUNCTION_METRICS_BUCKET_MS)`. */
+interface FunctionMetricBucket {
+  /** Epoch-ms floor of the bucket window. */
+  bucketMs: number;
+  /** Dispatches recorded in this window. */
+  calls: number;
+  /** Subset of `calls` that threw. */
+  errors: number;
+}
+/** One declared index a dispatch exercised (used to narrow a read). */
+interface IndexHit {
+  /** The declared index name. */
+  index: string;
+  /** The table the index is declared on. */
+  table: string;
+}
+/** One declared index's cumulative recorded read count (durable, non-decaying) — the advisor dead-index lint input. */
+interface FunctionMetricIndexHit {
+  /** The declared index name. */
+  index: string;
+  /** Recorded reads that used this index to narrow. */
+  reads: number;
+  /** The table the index is declared on. */
+  table: string;
+}
+/** Fields recorded for one completed dispatch. `errored` advances the failure counters. */
+interface RecordFunctionMetricInput {
+  /**
+   * Whether the dispatch failed on an optimistic-concurrency (OCC) write
+   * conflict — a compare-and-swap that lost to a concurrent commit. Advances
+   * the durable `conflicts` counter behind the write-contention advisor. A
+   * conflicted dispatch also `errored`, so conflicts are a subset of errors.
+   * Omitted/false on the common path, keeping the hot path unchanged.
+   */
+  conflicted?: boolean;
+  /** Wall-clock millis the handler took. */
+  durationMs: number;
+  /** Whether the dispatch threw. */
+  errored: boolean;
+  /** Most recent failure message, recorded only when `errored`. */
+  errorMessage?: string;
+  /**
+   * Distinct declared indexes this dispatch exercised (used to narrow a read),
+   * collected from the `onIndexUse` signal. Each entry bumps the
+   * per-`(table, index)` hit counter in `__lunora_metrics_index`, the durable
+   * producer behind the advisor dead-index lint. Omitted/empty when the
+   * dispatch used no declared index, keeping the hot path unchanged.
+   */
+  indexHits?: ReadonlyArray<IndexHit>;
+  /** The `&lt;file>:&lt;function>` identifier. */
+  path: string;
+  /**
+   * Distinct tables this dispatch full-scanned (read with no index / point
+   * lookup), collected from the `SCAN_DEP` reads. Each entry bumps the
+   * aggregate `scans` counter and the per-`(path, table)` attribution row.
+   * Omitted/empty when the dispatch didn't full-scan anything (the common
+   * indexed case), keeping the hot path to the same two upserts as before.
+   */
+  scannedTables?: ReadonlyArray<string>;
+  /** Epoch-ms the dispatch completed. */
+  ts: number;
+}
+/**
+ * Create the four reserved metrics tables. Idempotent, so the read and write
+ * paths can call it defensively. The accumulator table is keyed by `path` (one
+ * row per function); the bucket table by `(path, bucketMs)` (one row per
+ * function per window); the scans table by `(path, table)` (one row per
+ * function per full-scanned table); the index table by `(table, index)` (one
+ * row per declared index the app exercises).
+ *
+ * The accumulator's `scans` column is added via a guarded `ALTER TABLE` rather
+ * 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.
+ */
+declare const ensureFunctionMetricsTables: (sql: SqlExec) => void;
+/**
+ * Persist one completed dispatch: a single upsert into the accumulator row and
+ * one upsert into the current time bucket, then a bounded trim of old buckets
+ * for that path. Creates the tables first so callers needn't. This is the hot
+ * path — exactly two `INSERT … ON CONFLICT … DO UPDATE` statements plus a
+ * bounded `DELETE`, all keyed by primary key, so it stays cheap.
+ *
+ * When the dispatch full-scanned one or more tables (`scannedTables`), the
+ * aggregate `scans` counter on the accumulator row advances by the distinct
+ * table count and one extra `(path, table)` upsert fires per scanned table.
+ * Indexed dispatches (the common case) skip all of that and pay nothing.
+ */
+declare const recordFunctionMetric: (sql: SqlExec, input: RecordFunctionMetricInput) => void;
+/**
+ * Read the per-function full-scan attribution, grouped by function path. The
+ * returned map keys are `path`; each value is the function's full-scanned
+ * tables ordered by scan count (busiest scan first), so the causal "slow
+ * BECAUSE it scanned X" read can lead with the dominant table. Creates the
+ * table first so reads on a never-called shard return an empty map.
+ */
+declare const readFunctionMetricScans: (sql: SqlExec) => Map<string, FunctionScanAttribution[]>;
+/**
+ * Read the per-`(table, index)` hit counts — the advisor dead-index lint input.
+ * Each entry is a declared index and how many recorded reads used it to narrow
+ * (a cumulative, non-decaying count); the lint reconciles this against the schema
+ * to flag a declared index that appears with zero reads (or not at all) as dead. Ordered
+ * by table then index for stable output. Creates the table first so a read on a
+ * never-exercised shard returns `[]`.
+ */
+declare const readFunctionMetricIndexHits: (sql: SqlExec) => FunctionMetricIndexHit[];
+/**
+ * Fold a dispatch's distinct full-scanned tables into an in-memory attribution
+ * list, mirroring the per-`(path, table)` upsert {@link recordFunctionMetric}
+ * applies to the durable `__lunora_metrics_scans` table. Kept here, beside its
+ * SQL twin, so the one rule (one occurrence = +1 scan for that table, list
+ * re-sorted busiest-first) lives in a single module — the in-memory copy exists
+ * only for the warm-instance fallback when the durable read is unavailable.
+ * Mutates and returns `into`.
+ */
+declare const mergeScanAttribution: (into: FunctionScanAttribution[], scanned: ReadonlyArray<string>) => FunctionScanAttribution[];
+/**
+ * Read the persisted per-function accumulators as {@link FunctionCallStat}s,
+ * newest-called first. Creates the table first so reads on a never-called shard
+ * return `[]` instead of throwing. The shape is a superset of the legacy
+ * in-memory `getFunctionStats` rows — the additive `scans` total and
+ * `scannedTables` causal attribution are folded in here so a single read backs
+ * the Insights "missing index" / "full scan" signal.
+ */
+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 `[]`.
+ */
+declare const readFunctionMetricBuckets: (sql: SqlExec, path?: string) => (FunctionMetricBucket & {
+  path: string;
+})[];
+/**
+ * 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.
+ */
+declare const readFunctionMetricsTotals: (sql: SqlExec) => {
+  errors: number;
+  requests: number;
+};
+/**
+ * The Workers AI text model the Issue explainer uses when the caller does not
+ * override it. The fp8-fast instruct model the rest of the repo defaults to —
+ * the explainer is a short, grounded rewrite (not a reasoning task), so a
+ * latency-optimized build beats a larger one. Deliberately not the retired
+ * `@cf/meta/llama-3.1-8b-instruct`: a deprecated model-id makes `binding.run`
+ * throw, which would silently degrade every explain to `"ai-error"`.
+ */
+/**
+ * Fallback model id when neither the caller nor the request names one.
+ *
+ * A Workers AI id, which makes it the *host's* default rather than this
+ * package's — a second host runs different models and must be able to say so.
+ * `explainIssue` therefore takes `defaultModel`, and this constant is only what
+ * the Cloudflare host happens to pass. Kept exported so that host has a name to
+ * pass rather than a string literal.
+ */
+declare const DEFAULT_EXPLAIN_ISSUE_MODEL = "@cf/meta/llama-3.3-70b-instruct-fp8-fast";
+/**
+ * Structural projection of the Workers `AI` binding's `run` method — declared
+ * locally so `@lunora/do` needs no dependency edge on `@lunora/ai` (nor on
+ * `@cloudflare/workers-types`) to reach `env.AI`. Mirrors `AiBindingLike` in
+ * `@lunora/ai`.
+ */
+interface AiRunBinding {
+  run: (model: string, inputs: Record<string, unknown>, options?: Record<string, unknown>) => Promise<unknown>;
+}
+/** 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. */
+  culprit?: string;
+  /** Per-request model-id override; falls back to the caller's `defaultModel`, then {@link DEFAULT_EXPLAIN_ISSUE_MODEL}. */
+  model?: string;
+  /** A representative raw error message for the Issue — the fact the explanation is grounded in. Required. */
+  sampleMessage: string;
+  /** The Issue's human-readable title (first line of the sample message), for grounding context. */
+  title?: string;
+}
+/**
+ * Why the explainer fell back to the grounded hint alone. A closed union rather
+ * than a bare `string` so `degraded(reason)` rejects a typo'd sentinel at compile
+ * time instead of letting it fall through to the client's generic error copy.
+ * Mirrored by `ExplainIssueResult["reason"]` in `@lunora/studio`'s `lib/admin.ts`.
+ */
+type ExplainIssueDegradedReason = "ai-error" | "empty-response" | "no-ai-binding";
+/**
+ * The grounding facts both `__lunora_admin__:explainIssue` outcomes carry. Present
+ * whenever {@link findIssueSolution} recognized the message — offline,
+ * deterministic, and independent of whether the AI path ran at all.
+ *
+ * The hint BODY is deliberately not on the wire: the client derives it from the
+ * same catalog offline (that is the whole point of the grounded layer), so
+ * shipping it would be payload nothing reads.
+ */
+interface ExplainIssueGrounding {
+  /**
+   * The id of the matched catalog/platform solution the prompt was grounded in,
+   * absent when nothing recognized the message. The client renders a caveat on
+   * absence — an ungrounded explanation is a free-form model guess, not a
+   * catalog-backed one, and must not be presented as the latter.
+   */
+  groundedId?: string;
+}
+/**
+ * The `__lunora_admin__:explainIssue` result — a discriminated union on `degraded`
+ * rather than a bag of optionals, so each outcome's guaranteed fields are
+ * guaranteed in the type too. The AI `explanation` is best-effort: the degraded
+ * arm is returned when no `env.AI` binding is configured or the inference call
+ * failed, and the client falls back to its own grounded hint alone.
+ *
+ * Modelling this as one flat interface let a `degraded` result type-check without a
+ * `reason`, which the studio silently renders as the generic AI-error copy.
+ */
+/** The arm returned when no inference happened, or it failed. */
+interface ExplainIssueDegraded extends ExplainIssueGrounding {
+  /** The AI path was unavailable or failed — render the grounded hint instead. */
+  degraded: true;
+  /** Why the AI path degraded, for the client to surface. */
+  reason: ExplainIssueDegradedReason;
+}
+/** The arm returned when the model ran and produced text. */
+interface ExplainIssueSuccess extends ExplainIssueGrounding {
+  /** The AI path ran and produced text. */
+  degraded: false;
+  /** The AI-generated plain-language explanation. */
+  explanation: string;
+  /** The Workers AI model-id that produced {@link ExplainIssueSuccess.explanation}. */
+  model: string;
+}
+type ExplainIssueResult = ExplainIssueDegraded | ExplainIssueSuccess;
+/**
+ * Validate the `__lunora_admin__:explainIssue` payload. Requires a non-empty
+ * `sampleMessage` (the grounding fact); `title`, `culprit`, and `model` are
+ * optional context/overrides. Throws a 400 `LunoraError` on a bad shape.
+ *
+ * Every caller-supplied field that reaches the prompt is capped here — capping
+ * `sampleMessage` alone left `title`/`culprit` as an open door onto the same
+ * prompt budget.
+ */
+declare const parseExplainIssueArgs: (args: Record<string, unknown>) => ExplainIssueArgs;
+/**
+ * Run the full explain flow for one Issue: validate the payload, ground it in the
+ * catalog, and — when `binding` is a usable Workers AI binding — ask the model for
+ * a plain-language rewrite. Never throws for an AI-side failure; every such path
+ * returns the `degraded: true` arm carrying the grounded hint, so the caller
+ * always has something to render. Only a malformed payload throws (a 400).
+ *
+ * `binding` is `unknown` so the caller can hand over `env.AI` untyped — the shape
+ * check lives here rather than at each call site.
+ */
+declare const explainIssue: (binding: unknown, args: Record<string, unknown>, options?: {
+  defaultModel?: string;
+}) => Promise<ExplainIssueResult>;
+/** Reserved table holding one triage-state row per Issue fingerprint. Auto-hidden by the `__lunora` prefix. */
+declare const ISSUE_STATE_TABLE = "__lunora_issue_state__";
+/**
+ * Triage status of an Issue. `open` is the implicit default (no state row); a
+ * developer moves it to `resolved` (fixed, but a *new* matching error re-opens
+ * it — see {@link readIssueStates}'s consumer) or `ignored` (deliberately muted,
+ * and stays muted regardless of new occurrences).
+ */
+type IssueStatus = "ignored" | "open" | "resolved";
+/** Ordered severity a developer can tag an Issue with; drives the Studio badge palette. */
+type IssueSeverity = "critical" | "high" | "low" | "medium";
+/** The persisted triage state for one Issue fingerprint. */
+interface IssueState {
+  /** Free-form assignee (a userId or a name); absent when unassigned. */
+  assignee?: string;
+  /** Stable 16-char fingerprint hash — the same key `readErrorIssues` folds on. */
+  hash: string;
+  /** Developer-tagged severity; absent when untriaged. */
+  severity?: IssueSeverity;
+  /** Current triage status. */
+  status: IssueStatus;
+  /** Wall-clock millis the state was last changed — compared against an Issue's `lastSeen` to detect a regression. */
+  updatedAt: number;
+  /** Acting userId that last changed the state, when known. */
+  updatedBy?: string;
+}
+/** Patch applied by an admin write; every field is optional so a caller can change one facet at a time. */
+interface IssueStatePatch {
+  assignee?: null | string;
+  severity?: IssueSeverity | null;
+  status?: IssueStatus;
+}
+/** The valid {@link IssueStatus} values, for arg validation at the admin boundary. */
+declare const ISSUE_STATUSES: ReadonlyArray<IssueStatus>;
+/** The valid {@link IssueSeverity} values, for arg validation at the admin boundary. */
+declare const ISSUE_SEVERITIES: ReadonlyArray<IssueSeverity>;
+/**
+ * Apply a triage patch to one Issue, upserting its state row. A `null` in the
+ * patch clears the field (unassign, untag severity); an omitted field is left
+ * unchanged. Returns the resulting {@link IssueState} so the caller can echo it.
+ *
+ * Uses `ON CONFLICT(hash) DO UPDATE` with `COALESCE(?, column)` per optional
+ * field so a partial patch touches only what it names — except the explicit
+ * `null` sentinels for assignee/severity, which are threaded separately so a
+ * clear can win over `COALESCE`.
+ */
+declare const upsertIssueState: (sql: SqlExec, hash: string, patch: IssueStatePatch, updatedAt: number, updatedBy?: string) => IssueState;
+/**
+ * Severity of a buffered log entry — the full seven-tier `ctx.log` ramp
+ * (`trace`→`fatal`), not a console-shaped subset. The buffer used to fold the
+ * ramp onto four tiers, which made `trace` and `fatal` lines indistinguishable
+ * from `debug` and `error` in the Studio Logs panel; it now stores the level the
+ * caller actually logged at. Container-lifecycle entries only ever use
+ * `info`/`error`, which remain part of the union.
+ */
+type LogLevel = ContextLogLevel;
+/**
+ * One buffered log line. `functionPath` is the RPC that produced it (when the
+ * entry came from the RPC dispatch site); `timestamp` is `Date.now()` at the
+ * moment it was pushed. `instance`/`exitCode` are populated for container
+ * lifecycle entries: `instance` correlates the per-instance Durable Object id,
+ * `exitCode` carries the process exit code parsed out of a `stop` event.
+ */
+interface LogEntry {
+  exitCode?: number;
+  /** Structured fields from a `ctx.log.&lt;level>(message, fields)` / `ctx.log.with(fields)` call, when present. */
+  fields?: Record<string, unknown>;
+  functionPath?: string;
+  instance?: string;
+  level: LogLevel;
+  message: string;
+  timestamp: number;
+}
+/**
+ * A bounded, in-memory ring buffer of recent {@link LogEntry} records.
+ *
+ * In-memory only: like the metrics counters on `ShardDO`, the buffer is a field
+ * on the live Durable Object instance and so resets whenever the DO hibernates
+ * or restarts. It is a "recent activity on this instance" readout (for the
+ * studio's live log panel), NOT a durable log store or a transport.
+ * Production log shipping is the platform's job, not ours: use Cloudflare
+ * **Workers Logs** (retained, queryable in the studio), **Logpush** (stream
+ * to R2 / a SIEM / a log service), or a **Tail Worker** for programmatic
+ * capture. Lunora deliberately does not reimplement any of those — this buffer
+ * stays a tiny dev/ops readout. Capacity is fixed at construction; once full,
+ * the oldest entry is evicted to make room (FIFO), so memory stays bounded
+ * regardless of traffic.
+ */
+declare class LogBuffer {
+  /** Backing store, kept in insertion order (oldest first). */
+  private readonly buffer;
+  private readonly capacity;
+  constructor(capacity?: number);
+  /** Number of entries currently buffered. */
+  get size(): number;
+  /** Drop every buffered entry. */
+  clear(): void;
+  /**
+   * Snapshot of the buffered entries, **newest first** so the panel renders
+   * the most recent activity at the top without re-sorting. Returns a fresh
+   * array each call; the caller may mutate it freely.
+   */
+  entries(): LogEntry[];
+  /**
+   * Append an entry, evicting the oldest when at capacity so the buffer never
+   * grows past its bound.
+   */
+  push(entry: LogEntry): void;
+}
+/**
+ * One aggregated metric series: every measurement sharing a `(name, kind,
+ * attributes)` identity folded into a single running summary.
+ *
+ * All fields are maintained for every {@link MetricKind} — the fold is uniform
+ * and O(1), and letting the panel choose the meaningful projection per kind
+ * (counter → `sum`, gauge → `last`, histogram → `sum`/`count` for the mean, plus
+ * `min`/`max`) is cheaper and clearer than branching on kind at record time.
+ */
+interface MetricSeries {
+  /** The series' dimensions, if any — the attributes that made it distinct. */
+  attributes?: LogFields;
+  /** Number of measurements folded into this series. */
+  count: number;
+  /** Trace id of the most recent measurement that carried one — the series' exemplar, for linking to a trace. */
+  exemplarTraceId?: string;
+  /** Wall-clock millis of the first measurement folded in. */
+  firstTs: number;
+  /** Function path that recorded the series' most recent measurement. */
+  functionPath: string;
+  /** Instrument kind; decides which projection the panel shows. */
+  kind: MetricKind;
+  /** Most recent measured value — the current reading for a `gauge`. */
+  last: number;
+  /** Wall-clock millis of the most recent measurement. */
+  lastTs: number;
+  /** Largest measured value seen. */
+  max: number;
+  /** Smallest measured value seen. */
+  min: number;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Sum of measured values — a `counter`'s total, a `histogram`'s sum. */
+  sum: number;
+}
+/**
+ * A bounded map of running metric aggregates, keyed by series identity. Eviction
+ * is least-recently-*updated*: a re-recorded series moves back to the tail (Map
+ * insertion order), so the capacity bound sheds cold, high-cardinality series and
+ * keeps the ones still receiving traffic — the opposite of a raw ring, which
+ * would evict a hot counter's own history.
+ */
+declare class MetricBuffer {
+  private readonly capacity;
+  private readonly series;
+  constructor(capacity?: number);
+  /** Number of distinct series currently aggregated. */
+  get size(): number;
+  /** Drop every aggregated series. */
+  clear(): void;
+  /**
+   * Snapshot of the aggregated series, most-recently-updated first, each a fresh
+   * copy so a caller can't mutate the live aggregate. `series` is kept in
+   * update order (tail = newest), so one reverse yields newest-first.
+   */
+  entries(): MetricSeries[];
+  /** Fold one measurement into its series, creating or updating the aggregate. */
+  push(event: MetricEvent): void;
+}
+/** One time-bucket sample of a series: the aggregate over `[bucketMs, bucketMs + METRIC_HISTORY_BUCKET_MS)`. */
+interface MetricHistoryPoint {
+  /** Epoch-ms floor of the bucket window. */
+  bucketMs: number;
+  /** Measurements folded into this bucket. */
+  count: number;
+  /** Sample `traceId` of a measurement in this bucket, if one carried trace context — the exemplar. */
+  exemplarTraceId?: string;
+  /** Last measured value in the bucket — a gauge's reading at the window's end. */
+  last: number;
+  /** Largest value in the bucket. */
+  max: number;
+  /** Smallest value in the bucket. */
+  min: number;
+  /** Sum of values in the bucket — a counter's increment total, a histogram's sum. */
+  sum: number;
+}
+/** One series' durable history: its identity plus its time-ordered buckets, oldest first. */
+interface MetricHistorySeries {
+  attributes?: LogFields;
+  functionPath: string;
+  kind: MetricKind;
+  name: string;
+  /** Buckets in ascending `bucketMs` order, ready to chart as a line. */
+  points: MetricHistoryPoint[];
+  shardKey?: string;
+}
+/** {@link readMetricHistory} result: every tracked series with its buckets. */
+interface MetricHistoryResult {
+  series: MetricHistorySeries[];
+}
+/**
+ * Tunable caps for {@link recordMetricHistory}, threaded from the sink's
+ * `metricHistory` option. Each falls back to its module-constant default, so an
+ * omitted field keeps the historical behaviour.
+ */
+interface MetricHistoryOptions {
+  /** Distinct series tracked before a brand-new one is dropped (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;
+}
+/**
+ * Fold one measurement into its `(series, minute)` bucket. Runs per
+ * `ctx.metrics.*` call (unlike `function-metrics.ts`, which runs once per
+ * dispatch), so it's tuned for the in-minute repeat: a bucket this instance has
+ * already written is a single upsert (no reads), a bucket only in the DB costs one
+ * PK point-lookup + upsert, and only a genuinely new bucket also pays the
+ * distinct-series cap scan + retention trim. Still a durable SQLite write per
+ * measurement, so a hot loop recording thousands of points a second should
+ * pre-aggregate and record once (see `shared/metric-event.ts`). Creates the table
+ * first so callers needn't.
+ *
+ * `exemplarTraceId` (the recording dispatch's trace, when it had one) is stored on
+ * the bucket so the studio can link a chart point back to a trace. Latest wins:
+ * a later sample carrying a trace replaces an earlier bucket's exemplar.
+ *
+ * `options` tunes the distinct-series cap and retention window from the sink's
+ * `metricHistory` flag (see {@link MetricHistoryOptions}); each defaults to its
+ * module constant.
+ */
+declare const recordMetricHistory: (sql: SqlExec, event: MetricEvent, exemplarTraceId?: string, options?: MetricHistoryOptions) => void;
+/**
+ * Read the durable history, grouped into one {@link MetricHistorySeries} per
+ * series with its buckets in ascending time order.
+ *
+ * Rows are fetched most-recent-first (`bucket_ms DESC`) under the row cap, NOT
+ * `series_key`-ordered: all active series write the same recent minutes, so this
+ * windows every series to a recent slice fairly, instead of handing the
+ * alphabetically-first series its full 1440-bucket history and starving the rest
+ * once the cap is hit. Each series' points are re-sorted ascending below, since a
+ * trend line reads oldest→newest.
+ *
+ * `options.sinceMs`, when set, returns only buckets at or after this epoch-ms —
+ * the studio's time-window selector.
+ */
+declare const readMetricHistory: (sql: SqlExec, options?: {
+  sinceMs?: number;
+}) => MetricHistoryResult;
+/** One row of the `__lunora_metrics_queries` table, as returned by `readQueryMetrics`. */
+interface QueryStatEntry {
+  /** Total number of times this statement was executed. */
+  execCount: number;
+  /** Normalised SQL text (literals stripped, truncated). */
+  normalizedSql: string;
+  /** Total rows read across all executions (SELECT result sizes). */
+  rowsRead: number;
+  /** Total rows written across all executions. */
+  rowsWritten: number;
+  /** Total wall-clock milliseconds across all executions. */
+  totalDurationMs: number;
+}
+/** One statement's activity within a chosen time range. */
+interface QueryInsightEntry {
+  /** Mean milliseconds per execution across the range. */
+  avgDurationMs: number;
+  execCount: number;
+  normalizedSql: string;
+  /** Interpolated 50th percentile latency, in milliseconds. */
+  p50DurationMs: number;
+  /** Interpolated 95th percentile latency, in milliseconds. */
+  p95DurationMs: number;
+  rowsRead: number;
+  rowsWritten: number;
+  totalDurationMs: number;
+}
+/** One point on the throughput/latency charts. */
+interface QueryInsightBucket {
+  /** Mean milliseconds per execution in this window, across all statements. */
+  avgDurationMs: number;
+  /** Bucket start, epoch millis. */
+  bucketMs: number;
+  execCount: number;
+}
+/** What `getQueryInsights` returns. */
+interface QueryInsightsResult {
+  /** Time series across the whole range, all statements combined. */
+  buckets: QueryInsightBucket[];
+  /**
+   * True when the tracked-statement cap has been reached, so the caller can say
+   * "showing N of a capped set" rather than implying totality. Silent
+   * truncation reads as complete coverage when it is not.
+   */
+  capped: boolean;
+  entries: QueryInsightEntry[];
+  /** How many distinct statements the lifetime table is tracking. */
+  trackedStatements: number;
+}
+/**
+ * Per-statement activity within `rangeMs` of `now`, plus a combined time series.
+ *
+ * Reads the bucket table (not the lifetime one) so the numbers answer "what is
+ * hot right now"; the statement TEXT is joined back from the lifetime table,
+ * which is the only place it is stored.
+ */
+declare const readQueryInsights: (sql: SqlExec, rangeMs: number, now?: number) => QueryInsightsResult;
+/**
+ * Record one statement execution. 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.
+ */
+declare const recordQueryMetric: (sql: SqlExec, rawSql: string, durationMs: number, rowsRead: number, rowsWritten: number, now?: 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
+ * never-called shard returns `[]`.
+ */
+declare const readQueryMetrics: (sql: SqlExec) => QueryStatEntry[];
+/** Reserved append-only table backing the studio Logs tab. Auto-hidden from the data browser by the `__lunora` prefix. */
+declare const REQUEST_LOG_TABLE = "__lunora_reqlog__";
+/** Outcome of one dispatch — `ok` for a returned result, `error` for a thrown handler. */
+type RequestOutcome = "error" | "ok";
+/** One recorded `/rpc` dispatch, in monotonic `seq` order. */
+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;
+  /** 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. */
+  errorMessage?: string;
+  /** The `&lt;file>:&lt;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>;
+  /** `ok` for a returned result, `error` for a thrown handler. */
+  outcome: RequestOutcome;
+  /** Call args with leaf values redacted by default (keys/shape preserved); absent when no args were sent. */
+  redactedArgs?: unknown;
+  /** Monotonic per-shard cursor — strictly increasing, never reused. */
+  seq: number;
+  /** Shard key (the DO id name), or `undefined` for the unnamed `__root__` DO. */
+  shardKey?: string;
+  /** Count of subscriptions re-run by the write this dispatch triggered; `0` when none (or not measured at the dispatch site). */
+  subscriptionsReRun: number;
+  /** Tables the handler read (from the dependency tracker); empty when the reactive cache is off or the path read nothing. */
+  tablesRead: string[];
+  /** Tables the handler wrote (from the change tracker); empty for a read-only dispatch. */
+  tablesWritten: string[];
+  /** Wall-clock millis when the dispatch completed. */
+  ts: number;
+  /** Acting userId forwarded by the runtime, or `undefined` when anonymous. */
+  userId?: string;
+}
+/** Fields accepted when appending one request-log entry; `seq` is assigned by the table. */
+interface AppendRequestLogEntry {
+  cacheHit?: boolean;
+  durationMs: number;
+  errorMessage?: string;
+  functionPath: string;
+  identity?: Record<string, unknown>;
+  outcome: RequestOutcome;
+  redactedArgs?: unknown;
+  shardKey?: string;
+  subscriptionsReRun?: number;
+  tablesRead?: string[];
+  tablesWritten?: string[];
+  ts: number;
+  userId?: string;
+}
+/** Knobs the dispatch site threads into a request-log write. */
+interface RequestLogWriteOptions {
+  /** When `true` (development only), skip args/identity redaction so a developer sees raw values. Defaults to `false` (production-safe). */
+  captureRaw?: boolean;
+  /** Rows to keep after the append-time trim; defaults to {@link REQUEST_LOG_RETENTION}. The operator's `LUNORA_REQUEST_LOG_RETENTION` override. */
+  retention?: number;
+}
+/** 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). */
+  functionPathPrefix?: string;
+  /** Upper bound on returned rows, clamped to [1, 10000]. */
+  limit?: number;
+  /** Keep only `ok` / `error` outcomes. */
+  outcome?: RequestOutcome;
+  /** Exact shard-key match. */
+  shardKey?: string;
+  /** Only entries strictly after this cursor (forward paging). */
+  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. */
+interface RequestLogResult {
+  entries: RequestLogEntry[];
+}
+/**
+ * One grouped error **Issue**: many `error`-outcome request-log rows that share a
+ * fingerprint folded into a single triage row. The `hash` is the same stable key
+ * a cloud Incident groups on, so a local Issue and a cloud Incident are the same
+ * object.
+ */
+interface ErrorIssue {
+  /** Assignee (a userId or a name) from the persisted triage state; absent when unassigned. */
+  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. */
+  culprit: string;
+  /** Wall-clock millis of the oldest folded row. */
+  firstSeen: number;
+  /** Stable 16-char grouping hash over `functionPath :: bucket(message)`. */
+  hash: string;
+  /** Wall-clock millis of the newest folded row. */
+  lastSeen: number;
+  /** A representative raw error message — taken from the most recent folded row. */
+  sampleMessage: string;
+  /** Developer-tagged severity from the persisted triage state; absent when untriaged. */
+  severity?: IssueSeverity;
+  /**
+   * Wall-clock millis the persisted triage state was last changed; absent when
+   * the Issue has never been triaged. Compared against `lastSeen` to detect a
+   * regression (a new error after a resolve).
+   */
+  stateUpdatedAt?: number;
+  /**
+   * Triage status folded in from the persisted state (`open` by default). A
+   * `resolved` Issue whose `lastSeen` is newer than `stateUpdatedAt` is
+   * auto-reopened to `open` here (a regression), so a fresh occurrence never
+   * hides behind a stale resolution; `ignored` stays sticky by design.
+   */
+  status: IssueStatus;
+  /** Human-readable title (first line of the sample message, capped). */
+  title: string;
+}
+/** Payload of a `__lunora_admin__:getIssues` call: grouped error Issues, most-recently-active first. */
+interface IssuesResult {
+  issues: ErrorIssue[];
+}
+/** 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). */
+  functionPathPrefix?: string;
+  /** Upper bound on error rows scanned before grouping, clamped to [1, 10000]. */
+  limit?: number;
+  /** Exact shard-key match. */
+  shardKey?: string;
+  /** Keep only Issues in this triage status, applied AFTER the persisted-state fold + auto-reopen. */
+  status?: IssueStatus;
+  /** Exact acting-userId match. */
+  userId?: string;
+}
+/**
+ * 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.
+ */
+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.
+ */
+declare const appendRequestLogEntry: (sql: SqlExec, entry: AppendRequestLogEntry, options?: RequestLogWriteOptions) => void;
+/**
+ * Emit one structured request event to `console` so Cloudflare's Workers Logs /
+ * Logpush pipeline carries it to external sinks (SIEMs) — PLAN3 §3.3. This does
+ * 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.
+ *
+ * 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
+ * `source: "lunora"` / `type: "request"` envelope lets a consumer filter these
+ * events out of the raw Workers-trace firehose. `captureRaw` (dev only) skips
+ * redaction, mirroring the durable write. Best-effort by contract — the caller
+ * wraps it so a serialization hiccup can never fail the served request.
+ */
+declare const emitRequestLogEvent: (entry: AppendRequestLogEntry, options?: RequestLogWriteOptions) => void;
+/**
+ * The `ctx.log` event contract (shape + severity union) lives in
+ * `shared/log-event.ts` (inlined into each `dist`) so the DO that builds these
+ * events and the `@lunora/runtime` sink that consumes them agree by construction.
+ * `LogEventInput` is the DO's historical name for the shared `LogEvent`.
+ */
+type LogEventInput = LogEvent;
+/**
+ * Split a `ctx.log.&lt;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
+ * `console`-shaped calls are unchanged). Bound `.with(...)` fields merge under
+ * the per-call fields (per-call wins); the result is normalized to a fresh bag
+ * of JSON-safe primitives, or `undefined` when empty (see `normalizeLogFields`).
+ */
+declare const parseLogArgs: (args: unknown[], boundFields?: LogFields) => {
+  fields?: LogFields;
+  message: string;
+};
+/**
+ * Emit one application-log event from a `ctx.log.*` call to `console`, tagged
+ * `{ source: "lunora", type: "log" }` so the CLI / Vite formatter can pretty-print
+ * it in the dev terminal and a Logpush/SIEM consumer can filter it out of the
+ * raw Workers-trace firehose.
+ *
+ * Only the rendered `message` is emitted here, NOT the structured `args` array:
+ * the console event rides CF Workers Logs / Logpush to prod, and shipping raw,
+ * un-redacted arg objects on a `source: "lunora"` line a SIEM is told to trust
+ * would be a surprising PII/secret surface. The raw `args` stay on the in-process
+ * `sink.onLog` path (`recordUserLog`), which the operator opts into and controls.
+ * `message` already carries the developer's rendered values, exactly like a raw
+ * `console.log` line.
+ *
+ * `error`/`fatal` go to `console.error`, `warn` to `console.warn` (so they
+ * surface at the right level in the trace); every other level to `console.log`.
+ *
+ * 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;
+/**
+ * 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`.
+ */
+declare const readRequestLog: (sql: SqlExec, options?: ReadRequestLogOptions) => RequestLogEntry[];
+declare const readErrorIssues: (sql: SqlExec, options?: ReadIssuesOptions) => ErrorIssue[];
+/**
+ * Ordering/visual weight of a security finding — mirrors the studio's insight
+ * severities so the Security Advisor and the Performance Advisor (Insights) share
+ * one badge vocabulary. `error` sorts worst-first, then `warning`, then `info`.
+ */
+type SecurityFindingLevel = "error" | "info" | "warning";
+/**
+ * Which security heuristic fired. The detection stays free of presentation
+ * strings — the studio maps each kind to a localized title, explanation, and
+ * remediation hint — so the rule set is trivially unit-testable and the wire
+ * payload is tiny.
+ *
+ * `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.
+ *
+ * `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.
+ *
+ * `auth-secret-weak`: `AUTH_SECRET` / `BETTER_AUTH_SECRET` is set but shorter than 32 chars — too little entropy to sign session tokens safely. Pairs with `admin-token-weak`.
+ *
+ * `cors-wildcard-credentials`: `LUNORA_ALLOWED_ORIGINS` includes a `*` wildcard while `LUNORA_CORS_ALLOW_CREDENTIALS` is on — browsers reject the combination and it defeats the allowlist, so credentialed cross-origin requests are effectively unguarded.
+ *
+ * `security-headers-disabled`: the deployment set `LUNORA_SECURITY_HEADERS` off, so HSTS / CSP / nosniff / frame-options are not applied — a real exposure on a production worker.
+ *
+ * `csrf-disabled`: the deployment set `LUNORA_SECURITY_CSRF` off, so the cross-origin state-change guard is down — cookie-authenticated mutations are forgeable on a production worker.
+ *
+ * `cookies-insecure`: `BETTER_AUTH_URL` is a plaintext `http://` origin on a non-dev worker, so session cookies cannot carry the `Secure` attribute and ride in cleartext.
+ */
+type SecurityFindingKind = "admin-token-weak" | "auth-secret-weak" | "cookies-insecure" | "cors-wildcard-credentials" | "csrf-disabled" | "dev-args-unredacted" | "security-headers-disabled" | "ws-gate-open";
+/**
+ * One detected security issue. `detail` carries kind-specific context the studio
+ * may interpolate into the localized copy (e.g. the offending token length);
+ * absent when the kind needs none.
+ */
+interface SecurityFinding {
+  detail?: Record<string, unknown>;
+  kind: SecurityFindingKind;
+  level: SecurityFindingLevel;
+}
+/** Payload of a `__lunora_admin__:getSecurityAudit` call: every detected finding, worst-first. */
+interface SecurityAuditResult {
+  findings: SecurityFinding[];
+}
+/**
+ * Minimum `LUNORA_ADMIN_TOKEN` length considered safe against brute force. A
+ * short token gates the studio's destructive admin ops (writeRow, clearTable,
+ * pitrRestore, …), so a guessable one is a real exposure. 24 chars ≈ 128 bits
+ * for a random base64-ish token.
+ */
+declare const MIN_ADMIN_TOKEN_LENGTH = 24;
+/**
+ * Minimum `AUTH_SECRET` / `BETTER_AUTH_SECRET` length. better-auth signs session
+ * tokens with this secret; 32 chars (≈ `openssl rand -hex 32` → 32 bytes hex, or
+ * 192 bits of base64) is the floor below which the signing key is brute-forceable.
+ */
+declare const MIN_AUTH_SECRET_LENGTH = 32;
+/**
+ * Audit the Worker `env` for deployment-level security misconfigurations the
+ * Durable Object can observe directly. Pure and side-effect-free — same `env`,
+ * same findings — so the rules unit-test without a live shard.
+ *
+ * This is the server half of the studio's **Security Advisor**: CF's dashboard
+ * is infra-level and can't reason about lunora's admin/WS gates or its
+ * request-log redaction policy, so these are signals only lunora can surface.
+ * The audit is served behind the same admin gate as every other introspection
+ * RPC, so it only runs once a `LUNORA_ADMIN_TOKEN` is configured — which is why
+ * a *missing* token is never itself a finding here (introspection is simply off).
+ */
+declare const buildSecurityAudit: (rawEnv: unknown, options: {
+  dev: boolean;
+}) => SecurityAuditResult;
+/**
+ * One span in a folded trace, flattened for rendering: `depth` is its nesting
+ * level under the root and `offsetMs` its start relative to the trace start, so
+ * a waterfall row is a pure function of the record (indent by `depth`, bar from
+ * `offsetMs` to `offsetMs + durationMs`) with no client-side tree math.
+ */
+interface TraceSpan {
+  attributes?: LogFields;
+  /** Nesting level; the root span is 0. */
+  depth: number;
+  durationMs: number;
+  error?: {
+    message: string;
+    type: string;
+  };
+  name: string;
+  /** Start of this span relative to the trace's start, in ms. */
+  offsetMs: number;
+  ok: boolean;
+  parentSpanId: string;
+  spanId: string;
+}
+/** One folded trace: the dispatch plus every span recorded beneath it. */
+interface TraceSummary {
+  /** Wall-clock span of the whole trace (root start → last span end). */
+  durationMs: number;
+  functionPath: string;
+  /** False when the root or any descendant span errored. */
+  ok: boolean;
+  /** Display name of the trace — the root span's name. */
+  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: TraceSpan[];
+  startTs: number;
+  traceId: string;
+}
+/**
+ * A bounded, in-memory ring of recent {@link SpanEvent}s (oldest evicted first),
+ * mirroring `LogBuffer`. Spans arrive in *completion* order — a parent settles
+ * after its children — so ordering is imposed by {@link foldTraces} at read
+ * time rather than assumed here.
+ */
+declare class SpanBuffer {
+  private readonly buffer;
+  private readonly capacity;
+  constructor(capacity?: number);
+  /** Number of spans currently buffered. */
+  get size(): number;
+  /** Drop every buffered span. */
+  clear(): void;
+  /** Snapshot of the buffered spans in insertion order. Fresh array per call. */
+  entries(): SpanEvent[];
+  /**
+   * Whether any buffered span belongs to `traceId`. A membership test rather
+   * than `entries().some(...)` so the per-dispatch check that decides whether
+   * to record a root span doesn't copy the whole ring on every request.
+   */
+  hasTrace(traceId: string): boolean;
+  /** Append a span, evicting the oldest when at capacity. */
+  push(span: SpanEvent): void;
+}
+/** {@link foldTraces} result: the folded waterfalls plus the total distinct traces available before the `limit`. */
+interface FoldedTraces {
+  /**
+   * Distinct traces present in the buffer — the denominator for a "showing N of
+   * M" affordance. `traces.length` is `min(total, limit)`, so `total > traces.length`
+   * means older traces are held in the ring but not returned.
+   */
+  total: number;
+  /** The newest `limit` traces, folded into waterfalls. */
+  traces: TraceSummary[];
+}
+/**
+ * Group a flat span list into per-trace waterfalls, newest trace first, plus the
+ * total number of distinct traces available (so a caller can report truncation).
+ * @param spans Buffered spans, in arrival order.
+ * @param limit Maximum number of traces to return, newest first.
+ */
+declare const foldTraces: (spans: ReadonlyArray<SpanEvent>, limit?: number) => FoldedTraces;
+/** One record field whose `v.storage()` value points at an object key absent from the bucket. */
+interface DanglingReference {
+  /** The `v.storage()` column the dangling key was found in. */
+  column: string;
+  /** Primary key (`id`) of the owning row. */
+  id: string;
+  /** The object key the row references but which does not exist in the bucket. */
+  key: string;
+  /** The table the owning row lives in. */
+  table: string;
+}
+/**
+ * Result of {@link findDanglingReferences}: the dangling references discovered
+ * (record fields pointing at a missing object), plus `truncated` — `true` when a
+ * scan/result cap clipped the set, so the studio can log/surface that the view is
+ * partial. `scanned` is the total number of non-empty storage-field values
+ * examined, so the studio can show "checked N references".
+ */
+interface DanglingReferenceResult {
+  references: DanglingReference[];
+  scanned: number;
+  truncated: boolean;
+}
+/**
+ * Find every record storage-field value that points at an object key NOT present
+ * in `liveKeys` — a dangling reference (the record references a file the bucket no
+ * longer has). `storageColumns` is the schema-derived `{ table: [field, …] }` map
+ * the codegen subclass supplies (empty for the base, schema-free DO); `liveKeys`
+ * is the set of object keys that actually exist in the bucket (the caller passes
+ * the enumerated bucket listing). Scans only the declared storage columns — never
+ * the whole shard — and resolves each column to its physical/`__doc__` expression
+ * with the same injection-safe, bound-parameter discipline as `readTablePage`.
+ *
+ * Bounded: at most {@link DANGLING_SCAN_CAP} rows per column are examined and at
+ * most {@link DANGLING_RESULT_CAP} references returned; `truncated` flags either
+ * cap firing. An empty `storageColumns` (an app that models no storage refs)
+ * yields an empty, non-truncated result.
+ */
+declare const findDanglingReferences: (sql: SqlExec, storageColumns: Record<string, string[]>, liveKeys: Iterable<string>) => DanglingReferenceResult;
+/**
+ * The trace ids a dispatch's spans hang off: taken from the inbound
+ * `traceparent` when the runtime forwarded one (so the shard's spans join the
+ * worker's trace and any container's beneath it), else freshly minted so a
+ * dispatch with no inbound context — a subscription re-run, a server-initiated
+ * call — still produces a coherent, self-contained local trace.
+ */
+declare const resolveTraceAnchor: (traceparent: string | undefined) => {
+  rootSpanId: string;
+  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 };