@lunora/runtime 1.0.0-alpha.34 → 1.0.0-alpha.36

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { R2SqlClient } from '@lunora/bindings/r2sql';
 import { RankDirection, RankPageRow, DatabaseWriterLike } from '@lunora/do';
 export type { RankDirection as RankPageDirection, RankPageRowKey as RankPageKey, RankPageRow, ShardRankPageResult } from '@lunora/do';
+import { R2SqlClient } from '@lunora/bindings/r2sql';
 import { WorkflowsRestClient } from '@lunora/workflow';
 import { LunoraError as LunoraError$1, ErrorBody } from '@lunora/errors';
 /**
@@ -150,6 +150,24 @@ interface ExecutionContextLike {
  * receives a valid third argument.
  */
 declare const NOOP_EXECUTION_CONTEXT: ExecutionContextLike;
+/**
+ * Trace-sampling configuration — the `sampling` block on the worker's
+ * observability options.
+ */
+interface TraceSamplingConfig {
+  /**
+   * Always keep a whole trace that produced an error span (root or any child
+   * `ok: false`), regardless of the head decision — the tail bias that keeps
+   * failures observable under aggressive head sampling. Default `true`.
+   */
+  alwaysSampleErrors?: boolean;
+  /**
+   * Fraction of traces to keep by the deterministic head decision, in `[0, 1]`.
+   * `1` keeps every trace (the default), `0` drops every non-error trace, `0.1`
+   * keeps ~10%. Values outside the range are clamped by the decision helpers.
+   */
+  headRate?: number;
+}
 /** A timestamp as better-auth stores it: epoch-ms, an ISO string, or absent. */
 type AuthTimestamp = null | number | string;
 /**
@@ -426,6 +444,67 @@ interface AuthAdmin {
     userId: string;
   }) => Promise<AuthUser>;
 }
+/**
+ * Whether the recorded operation succeeded or failed (e.g. a rejected sign-in).
+ * Mirrors `@lunora/auth`'s `AuthAuditOutcome`.
+ */
+type AuthAuditOutcome = "failure" | "success";
+/**
+ * One recorded auth/security event, structurally mirroring `@lunora/auth`'s
+ * `AuthAuditEntry`. Duplicated here (like {@link import("./auth-admin-routes").AuthAdmin})
+ * so the runtime stays free of a hard `@lunora/auth` dependency — the host wires
+ * a structurally-compatible reader.
+ */
+interface AuthAuditEntry {
+  /** The acting user's email, when known. Absent for anonymous/pre-auth events. */
+  actorEmail?: string;
+  /** The acting user's id, when known. */
+  actorId?: string;
+  /** JSON-decoded extra context, with secrets/PII redacted at write time; absent when none was recorded. */
+  detail?: Record<string, unknown>;
+  /** Auth event type, e.g. `sign-in` / `password-change`. */
+  event: string;
+  /** Client IP the event originated from, when resolvable. */
+  ip?: string;
+  /** Whether the operation succeeded or failed. */
+  outcome: AuthAuditOutcome;
+  /** Monotonic per-database cursor — strictly increasing, never reused. */
+  seq: number;
+  /** Wall-clock millis when the event was recorded. */
+  ts: number;
+  /** Client User-Agent, when present on the request. */
+  userAgent?: string;
+}
+/**
+ * Filter / paging options forwarded to the reader, structurally mirroring
+ * `@lunora/auth`'s `ReadAuthAuditOptions`. `limit` is clamped by the reader
+ * (`readAuthAuditLog` bounds it to `[1, 10000]`).
+ */
+interface ReadAuthAuditQuery {
+  /** Return only events for this actor id. */
+  actorId?: string;
+  /** Return only events of this type. */
+  event?: string;
+  /** Max rows to return; clamped by the reader. */
+  limit?: number;
+  /** Return only events with `seq` strictly greater than this (forward paging). */
+  sinceSeq?: number;
+}
+/**
+ * The auth/security audit read plane backing the studio's "Security / audit"
+ * page. Unlike the shard-forwarded `__lunora_admin__:*` ops, the auth audit trail
+ * lives in the auth D1 database (via `@lunora/auth`'s `SqlExecutor`), so it is
+ * served at the worker. The host wires this — typically via `@lunora/auth`'s
+ * `createAuthAuditReader(d1Executor(env.DB))` — closing over that D1 binding; the
+ * runtime stays free of a hard `@lunora/auth` dependency. Omit the option and the
+ * RPC responds `AUTH_AUDIT_NOT_CONFIGURED`.
+ *
+ * The reader is a trusted server-side operator surface — the RPC gates it behind
+ * the worker's admin-bearer check before this is ever called.
+ */
+interface AuthAuditReader {
+  read: (options: ReadAuthAuditQuery) => Promise<AuthAuditEntry[]>;
+}
 /**
  * A compact, transport-safe description of one function argument — the runtime
  * read of a `v.*` validator's reflection tags (`kind` + `_meta`). The runtime
@@ -445,1177 +524,1628 @@ interface FunctionArgumentDescriptor {
   table?: string;
 }
 /**
- * Identity resolved from the inbound request by `WorkerOptions.resolveIdentity`.
- *
- * The `userId` field is special — it becomes `ctx.auth.userId` inside the
- * Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
- * forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
- *
- * Return `null` to signal that the request is anonymous; the runtime will
- * skip both `x-lunora-userid` and `x-lunora-identity` headers, and
- * `ctx.auth.userId` will be `undefined` on the shard side.
+ * Cloudflare Durable Object jurisdictions restrict where a DO runs and persists
+ * data, for data-residency / compliance regimes (GDPR, FedRAMP, US data
+ * residency). The set is open — Cloudflare adds values over time — so this is a
+ * widening union rather than a closed enum.
+ * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
  */
-interface ResolvedIdentity {
-  /** Arbitrary additional claims. Must be JSON-serialisable. */
-  [key: string]: unknown;
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
+ * Structural projection of the bits of `DurableObjectNamespace` the runtime
+ * needs. Real workers-types defines a much wider surface; this lets us pass
+ * unit-test doubles without coupling to `@cloudflare/workers-types`.
+ */
+interface ShardNamespaceLike {
+  get: (id: unknown) => {
+    fetch: (request: Request) => Promise<Response>;
+  };
   /**
-   * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
-   * absent), the runtime forwards it as the socket's credential expiry — the
-   * DO drops the socket once it lapses. Used only on the WebSocket path.
+   * `getByName` is the friendlier API but isn't on every workers-types
+   * release yet. We prefer it when available and fall back to
+   * `idFromName` + `get` for compatibility.
    */
-  exp?: number;
+  getByName?: (name: string) => {
+    fetch: (request: Request) => Promise<Response>;
+  };
+  idFromName: (name: string) => unknown;
   /**
-   * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
-   * both are present. Forwarded as the socket's expiry on the WebSocket path
-   * so the DO drops the socket once it lapses; omit for non-expiring sessions.
+   * Derive a jurisdiction-restricted subnamespace. Every ID and stub created
+   * from the returned namespace is pinned to `jurisdiction`. Optional because
+   * older workers-types releases (and unit-test doubles) may not expose it;
+   * {@link applyJurisdiction} fails closed when a jurisdiction is requested
+   * but this method is absent.
    */
-  expiresAtMs?: number;
-  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
-  userId: string;
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ShardNamespaceLike;
+}
+interface ResolvedShard {
+  fetch: (request: Request) => Promise<Response>;
 }
 /**
- * A verifier that turns an inbound request into a {@link ResolvedIdentity} (or
- * `null` for anonymous). Structurally identical to `WorkerOptions.resolveIdentity`,
- * so `.auth()`'s better-auth session resolver, a signed-preview-link verifier, a
- * per-tenant bearer check, an upstream-JWT reader, … are all just `IdentityResolver`s
- * — the identity layer is generic over every scheme, not coupled to any one.
+ * Return a jurisdiction-restricted view of `namespace`, or `namespace`
+ * unchanged when no jurisdiction is configured.
+ *
+ * Fail-closed: if a jurisdiction is requested but the binding does not expose
+ * `.jurisdiction()` (an older workers-types, or a misconfigured test double),
+ * this throws rather than silently routing to the un-pinned global namespace —
+ * silently dropping a residency constraint would let data land outside the
+ * compliance boundary the caller asked for.
  */
-type IdentityResolver = (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
-/** Error policy for {@link composeIdentityResolvers} when a participant resolver throws. */
-type ComposeIdentityResolversErrorMode = "fail-closed" | "skip";
-/** Options for {@link composeIdentityResolvers}. */
-interface ComposeIdentityResolversOptions {
-  /**
-   * What to do when a resolver throws. `"fail-closed"` (default, safe)
-   * re-throws so a broken verifier fails the request rather than silently
-   * falling through to a weaker one; `"skip"` swallows the error and tries the
-   * next resolver (use only when a resolver's failure genuinely means "not my
-   * scheme").
-   */
-  readonly onError?: ComposeIdentityResolversErrorMode;
+declare const applyJurisdiction: (namespace: ShardNamespaceLike, jurisdiction?: DurableObjectJurisdiction) => ShardNamespaceLike;
+/** Look up a shard stub by name, preferring `getByName` when present. */
+declare const resolveShard: (namespace: ShardNamespaceLike, shardKey: string) => ResolvedShard;
+/**
+ * Source of "which shard keys exist for a given table right now". Returning
+ * an empty array is valid — the coordinator will respond with the merge
+ * strategy's identity (empty array for `concat`, `0` for `sum`, etc.).
+ */
+interface ShardRegistry {
+  listShardKeys: (table: string) => Promise<ReadonlyArray<string>> | ReadonlyArray<string>;
 }
 /**
- * Compose several {@link IdentityResolver}s into one, first-match-wins: each is
- * tried in order and the first that returns a non-null identity short-circuits.
- * Generic over every scheme — the better-auth session resolver (obtained via the
- * builder's `derived.resolveIdentity` escape hatch) is just one entry in the list,
- * so composition never means losing it.
- *
- * A resolver that throws is handled per {@link ComposeIdentityResolversOptions.onError}
- * (default `"fail-closed"`: the error propagates).
+ * Static-map implementation. Useful for tests and for small deployments
+ * where shard keys are known up front (e.g. a fixed set of channel IDs).
  */
-declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
+declare const createStaticShardRegistry: (table_to_keys: Readonly<Record<string, ReadonlyArray<string>>>) => ShardRegistry;
 /**
- * A thin, generic helper over {@link composeIdentityResolvers} for the per-route case:
- * pick a resolver by `new URL(request.url).pathname`. Keys are matched by longest
- * path prefix; `"*"` is the fallback. Still fully generic — a route→resolver map,
- * with no portal / preview / tenant concepts baked in (those live in the app's
- * own resolvers).
- * @example
- * routeIdentityResolvers({ "/admin": adminResolver, "/partner": partnerResolver, "*": sessionResolver })
+ * Wire-serializable merge strategy. `topK.by` is a field name on the row
+ * (the runtime looks it up with a string key), not a closure.
+ *
+ * Aggregate-friendly variants for cross-shard `count` / `aggregate` /
+ * `groupBy` fan-outs:
+ *
+ * - `sum` — `count(*)`, `aggregate({ op: "sum" })` (sums numeric per-shard payloads).
+ * - `max` — `aggregate({ op: "max" })`.
+ * - `min` — `aggregate({ op: "min" })`.
+ * - `groupBy` — per-shard `GroupByEntry[]` payloads, reduced into one
+ * entry per distinct key tuple. `op` controls how values combine across
+ * shards: `sum` (default — works for `COUNT(*)` and `SUM`), `max`, `min`.
+ *
+ * `avg` is intentionally absent in v1 — a correct cross-shard average
+ * requires shipping `(sum, count)` per shard, not the post-shard mean.
+ * Use two separate fan-outs (`sum` + `count`) and divide in the caller.
+ *
+ * `rank` — cross-shard `rank()` over a partition that spans shards (e.g. a
+ * global leaderboard `.shardBy("userId")` with `rankIndex(partitionBy: [])`).
+ * Each shard's `__lunora_admin__:rankBefore` returns `{before, total}` (its
+ * local rows strictly-before the explicit key, plus its local partition
+ * total); the merge sums them into `{position: Σbefore + 1, total: Σtotal}` —
+ * the 1-based global position and global partition size.
  */
-declare const routeIdentityResolvers: (routes: Record<string, IdentityResolver>) => IdentityResolver;
-/** The result of validating a candidate identity against an {@link IdentityContractLike}. */
-type IdentityValidation = {
-  ok: true;
+type MergeStrategy = {
+  kind: "concat";
 } | {
-  error: string;
-  ok: false;
+  by: string;
+  direction?: "asc" | "desc";
+  k: number;
+  kind: "topK";
+} | {
+  kind: "first";
+} | {
+  kind: "max";
+} | {
+  kind: "min";
+} | {
+  kind: "rank";
+} | {
+  kind: "sum";
+} | {
+  kind: "groupBy";
+  op?: "max" | "min" | "sum";
 };
 /**
- * Structural view of `@lunora/server`'s `IdentityContract` (from `defineIdentity`).
- * Kept structural so `@lunora/runtime` stays free of an `@lunora/server` dependency.
- * Keep the `onInvalid` union and `validate`/`IdentityValidation` shapes in sync with
- * `@lunora/server`'s `IdentityContract` — they are projected by hand, not imported.
- * The generated worker entry passes the app's `defineIdentity(...)` result here;
- * the worker validates every resolver's returned claims against it at the trust
- * boundary before they become `ctx.auth`.
+ * Convenience: build the right wire-serializable {@link MergeStrategy} for a
+ * given aggregate read. The reader doesn't know which op the caller chose, so
+ * a fan-out wrapper passes the user's op + by-keys through this to derive the
+ * merge.
+ *
+ * - `count` → `sum`.
+ * - `aggregate({ op })` → `sum`/`max`/`min` (or throws for `avg`).
+ * - `groupBy({ by, agg })` → `groupBy({ op })` (defaults to `sum` since
+ * `groupBy`'s default reducer is `count`).
+ * @returns the derived {@link MergeStrategy}.
  */
-interface IdentityContractLike {
-  /** Reject policy applied when validation fails: downgrade to anonymous, or reject the request (401). */
-  readonly onInvalid: "anonymous" | "reject";
-  /** Validate resolver-returned claims against the declared contract. */
-  validate: (identity: Record<string, unknown>) => IdentityValidation;
-}
-/** One KV namespace as the studio's KV browser surfaces it. */
-interface KvNamespaceSummary {
-  /** The wrangler/env binding name, e.g. `"MY_KV"`. */
-  binding: string;
-}
-/** One key entry as the KV admin browser surfaces it. */
-interface KvKeyEntry {
-  /** Absolute expiration (Unix seconds), when set. */
-  expiration?: number;
-  /** Per-key metadata set at write time, or absent when none. */
-  metadata?: unknown;
-  /** The key name. */
-  name: string;
-}
-/** A paginated page of KV keys as the admin browser returns it. */
-interface KvKeyListResult {
-  /** Opaque cursor for the next page; absent when the listing is complete. */
-  cursor?: string;
-  /** The keys on this page. */
-  keys: KvKeyEntry[];
-  /** True when this is the final page. */
-  listComplete: boolean;
-}
-/** A KV value together with its stored metadata. */
-interface KvValueResult {
-  /** Per-key metadata, or `null` when none. */
-  metadata: unknown;
-  /** The stored value as a string, or `null` when the key is absent. */
-  value: null | string;
+declare const mergeStrategyForAggregate: (input: {
+  agg?: {
+    op?: "avg" | "count" | "max" | "min" | "sum";
+  };
+  kind: "groupBy";
+} | {
+  kind: "count";
+} | {
+  kind: "scalar";
+  op: "avg" | "count" | "max" | "min" | "sum";
+}) => MergeStrategy;
+interface FanOutSpec {
+  merge: MergeStrategy;
+  /** Table whose shard keys drive the fan-out. */
+  table: string;
 }
 /**
- * The introspector the worker wires for the studio's KV browser. Build it from
- * the env's bound KV namespaces. Omit it and the `/_lunora/admin/kv/*`
- * endpoints respond `KV_NOT_CONFIGURED`.
+ * Per-shard failure surfaced in the aggregate response's `errors` field. We
+ * never throw out of `fanOut` — slow/failed shards are *data*, not an
+ * exception, so callers can decide whether to retry or surface a partial
+ * UI.
  */
-interface KvIntrospector {
-  /** Delete a key from a namespace. No-op when the key is absent. */
-  deleteKey: (options: {
-    key: string;
-    namespace: string;
-  }) => Promise<void>;
-  /** Read a value (as text) and its metadata from a namespace key. */
-  getValue: (options: {
-    key: string;
-    namespace: string;
-  }) => Promise<KvValueResult>;
-  /** List keys in a namespace, optionally filtered by prefix and paginated. */
-  listKeys: (options: {
-    cursor?: string;
-    limit?: number;
-    namespace: string;
-    prefix?: string;
-  }) => Promise<KvKeyListResult>;
-  /** List the registered KV namespaces (binding names). */
-  listNamespaces: () => Promise<KvNamespaceSummary[]>;
-  /** Write a value (as text) with optional absolute expiration / relative TTL and metadata. */
-  putValue: (options: {
-    expiration?: number;
-    expirationTtl?: number;
-    key: string;
-    metadata?: unknown;
-    namespace: string;
-    value: string;
-  }) => Promise<void>;
+interface ShardError {
+  /** Human-readable; tests assert on `.includes("timeout")` and similar. */
+  message: string;
+  shardKey: string;
+  /** Set when the per-shard timeout fired. */
+  timedOut: boolean;
 }
-/**
- * Shared, bundler-inlined helpers for the structured `fields` a
- * `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call carries.
- *
- * Inlined (like {@link file://./otlp.ts}) so `@lunora/do`, `@lunora/runtime`,
- * `@lunora/config`, and `@lunora/studio` — which sit on different tiers with no
- * acceptable runtime dependency edge between them — share ONE implementation of
- * field rendering/normalization instead of the byte-identical copies they would
- * otherwise hand-mirror. Keep this genuinely zero-dependency (only built-ins) so
- * inlining into each `dist` stays sound.
- */
-/** Structured, filterable key/value fields attached to a `ctx.log` line. */
-type LogFields = Record<string, unknown>;
-/**
- * Severity of a `ctx.log.*` call. The five console method names (`log` is the
- * default level, distinct from `info`) plus `trace`/`fatal`, so the logger spans
- * the full OpenTelemetry severity ramp (`trace`→`fatal`).
- */
-type ContextLogLevel = "debug" | "error" | "fatal" | "info" | "log" | "trace" | "warn";
-/**
- * Per-event context handed to a sink alongside the event: lets a sink register
- * background work (a telemetry POST, a durable pipeline send) with the request's
- * `waitUntil` so it survives isolate teardown after the response returns. Absent
- * `waitUntil` (no request context) means the sink falls back to fire-and-forget.
- */
-interface LogSinkContext {
-  /** Keep a background promise alive past the response (the request's `waitUntil`). */
-  waitUntil?: (promise: Promise<unknown>) => void;
+interface FanOutResult<T = unknown> {
+  /** Merged value — type depends on the merge strategy. */
+  data: T;
+  errors: ReadonlyArray<ShardError>;
+  /** Shards that failed or timed out. */
+  failed: number;
+  /** Shards that returned successfully. */
+  ok: number;
 }
-/**
- * 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[];
+interface QueryCoordinatorOptions {
   /**
-   * 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.
+   * Maximum number of shard RPCs to issue in parallel. Defaults to 16 —
+   * keeps the 30-second Worker CPU budget healthy when fanning out to
+   * dozens of shards and avoids stampeding the DO namespace.
    */
-  fields?: LogFields;
-  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  maxConcurrency?: number;
+  /**
+   * Hard per-shard timeout in milliseconds. Defaults to 5000; a slow
+   * shard surfaces in `errors[]` rather than stalling the aggregate.
+   */
+  perShardTimeoutMs?: number;
+  /** Required — drives which shards to fan out to. */
+  registry: ShardRegistry;
+}
+interface FanOutRequest {
+  args?: Record<string, unknown>;
+  fanOut: FanOutSpec;
   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;
+  /** Forwarded to each shard fetch (auth, cookies, bookmark). */
+  headers?: Record<string, string>;
 }
 /**
- * The written-column contract: every field `pipelineLogSink` emits, mapped to the
- * column it is stored under by default (the identity mapping). Also the source of
- * truth for the {@link PipelineLogField} union. Mirrors the record built in
- * `pipelineLogSink` — the read side of the same contract.
- */
-declare const DEFAULT_COLUMNS: {
-  readonly fields: "fields";
-  readonly functionPath: "functionPath";
-  readonly level: "level";
-  readonly message: "message";
-  readonly shardKey: "shardKey";
-  readonly spanId: "spanId";
-  readonly traceId: "traceId";
-  readonly ts: "ts";
-  readonly userId: "userId";
-};
-/**
- * The canonical field names of one persisted log record — the keys
- * `pipelineLogSink` writes. Used as the {@link PipelineLogColumnMap} keys and the
- * {@link PipelineLogRow} shape, so the reader stays decoupled from whatever
- * physical column names the operator's Iceberg table happens to use.
+ * Cross-shard migration request. Unlike {@link FanOutRequest} there is no merge
+ * strategy — per-shard payloads are `MigrationRunResult`-shaped objects, not
+ * rows, so {@link QueryCoordinator.orchestrateMigration} rolls them up with the
+ * fixed semantics documented on {@link MigrationFanOutResult}.
+ *
+ * `functionPath` is the admin RPC to invoke on each shard
+ * (`__lunora_admin__:runMigration` or `:migrationStatus`); `headers` must carry
+ * the `Authorization` bearer header the shard's admin gate requires (the
+ * configured admin token), or every shard comes back as a 403 error.
  */
-type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
+interface MigrationFanOutRequest {
+  args?: Record<string, unknown>;
+  functionPath: string;
+  headers?: Record<string, string>;
+  /** Table whose live shard keys the migration runs across. */
+  table: string;
+}
+/** One shard's outcome: either the unwrapped admin `result` payload, or an error. */
+interface ShardMigrationOutcome {
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  /** The shard's admin `result`, peeled out of the `{ result }` envelope. */
+  result?: unknown;
+  shardKey: string;
+}
+interface MigrationFanOutResult {
+  /** Summed `changed` across shards whose result carried a numeric count. */
+  changed: number;
+  /** Shards that errored or timed out. */
+  failed: number;
+  /** Shards that returned a 2xx result. */
+  ok: number;
+  /** Summed `processed` across shards whose result carried a numeric count. */
+  processed: number;
+  /** Per-shard outcomes, in registry order. */
+  shards: ReadonlyArray<ShardMigrationOutcome>;
+  /**
+   * Rolled-up status. `"failed"` if any shard's runner reported failure;
+   * `"in_progress"` if any shard is incomplete or unreachable (the run stays
+   * resumable); `"completed"` only when every shard finished cleanly.
+   */
+  status: "completed" | "failed" | "in_progress";
+}
 /**
- * Field-to-column-name map. Defaults to the identity mapping (each field stored
- * under its own name, matching what `pipelineLogSink` writes). Override per-field
- * when the Iceberg schema renames a column; unspecified fields keep their
- * default. This is the single knob that lets one reader serve differently shaped
- * Data Catalog tables.
+ * Cross-shard rank request. Like {@link MigrationFanOutRequest} there is no
+ * caller-supplied merge — per-shard payloads are `{before, total}` objects, so
+ * {@link QueryCoordinator.orchestrateRank} rolls them up with the fixed
+ * `{position: Σbefore + 1, total: Σtotal}` semantics {@link mergeRank} defines.
+ *
+ * The key tuple (`partitionKey`/`sortValues`/`rowId`) is built off the row doc
+ * via `@lunora/do`'s `rankKeyFromDoc(index, doc)` and forwarded verbatim to
+ * each shard's `__lunora_admin__:rankBefore` admin RPC; `headers` must carry
+ * the admin bearer the shard's admin gate requires.
  */
-type PipelineLogColumnMap = Partial<Record<PipelineLogField, string>>;
-/** An opaque keyset cursor: the `ts` of the row after the last one returned. */
-interface PipelineLogCursor {
-  /** Epoch-millis boundary; the next page is every row strictly older than this. */
-  ts: number;
+interface RankFanOutRequest {
+  headers?: Record<string, string>;
+  /** Rank index name on `table`. */
+  index: string;
+  /** Canonical-JSON partition tuple — `encodePartitionKey(index.partitionBy, doc)`. */
+  partitionKey: string;
+  /** The `__id__` tiebreak value — `doc._id`. */
+  rowId: string;
+  /** Serialized sort-key values in `index.sortBy` order, as produced by `rankKeyFromDoc` (wire-safe + byte-matching the stored columns). */
+  sortValues: ReadonlyArray<unknown>;
+  /** Table whose live shard keys the rank fans out across. */
+  table: string;
 }
-/** Filters for one {@link PipelineLogReader} query. Every value is inlined safely (`lit`/`sql`). */
-interface PipelineLogQuery {
-  /** Continue after a previous page (keyset on `ts DESC`). Combined with the other filters. */
-  cursor?: PipelineLogCursor;
-  /** Match only this exact function path's records. Prefer `functionPathPrefix` for a namespace sweep. */
-  functionPath?: string;
-  /** Match records whose `functionPath` starts with this string (rendered as a `LIKE 'prefix%'`). */
-  functionPathPrefix?: string;
-  /** Match only this exact severity. When set, `minLevel` is ignored for the same field. */
-  level?: ContextLogLevel;
-  /** Max rows to return. Clamped to `[1, 10000]`; defaults to {@link DEFAULT_LOG_LIMIT}. */
-  limit?: number;
-  /** Severity floor: keep every level at or above this in {@link LOG_LEVEL_ORDER} (e.g. `warn` keeps warn, error, fatal). */
-  minLevel?: ContextLogLevel;
-  /** Match only this shard key. */
-  shardKey?: string;
-  /** Lower time bound, inclusive (`ts` at or after this), epoch-millis. */
-  sinceTs?: number;
-  /** Match only this trace id. */
-  traceId?: string;
-  /** Upper time bound, inclusive (`ts` at or before this), epoch-millis. */
-  untilTs?: number;
-  /** Match only this acting user id. */
-  userId?: string;
+interface RankFanOutResult {
+  /** Shards that errored or timed out. */
+  failed: number;
+  /** Shards that returned a 2xx `{before, total}`. */
+  ok: number;
+  /** `true` when at least one shard failed/timed out, so `position`/`total` are under-counts (failed shards' rows missing). A caller needing an exact global rank should treat this as an error, not trust the numbers. */
+  partial: boolean;
+  /** 1-based global position within the partition (`Σbefore + 1`). */
+  position: number;
+  /** Per-shard outcomes, in registry order. */
+  shards: ReadonlyArray<ShardRankOutcome>;
+  /** Global partition total (`Σtotal`). */
+  total: number;
+}
+/** One shard's rank outcome: its `{before, total}` payload, or an error. */
+interface ShardRankOutcome {
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  result?: {
+    before: number;
+    total: number;
+  };
+  shardKey: string;
 }
 /**
- * One decoded log record. Always keyed by the canonical {@link PipelineLogField}
- * names regardless of the physical columns (the reader remaps via `columnMap`),
- * so consumers never see the operator's storage names.
+ * Cross-shard ranked-pagination request. Like {@link RankFanOutRequest} there's
+ * no caller-supplied merge — the merge is the fixed k-way merge by the rank-key
+ * tuple. `take` is the global page size; `cursor` is the opaque composite cursor
+ * from the prior page's `continueCursor` (absent → first page). `partitionKey`,
+ * when set, pins a single partition (`encodePartitionKey(index.partitionBy, where)`),
+ * forwarded so each shard scopes its local slice to that partition.
+ *
+ * `directions` is the per-sort-key direction list (`index.sortBy[i].direction`)
+ * the coordinator's comparator needs to break ties the same way each shard's
+ * `ORDER BY` does. `partitionKey` and the `__id__` tiebreak are always ascending
+ * (matching the shard companion's btree), so only the sort columns vary.
  */
-interface PipelineLogRow {
-  /**
-   * Structured fields, when the record carried them. A `serializeFields` sink
-   * stores these as a JSON string, which the reader parses back to an object;
-   * a plain string that is not valid JSON is returned verbatim.
-   */
-  fields?: unknown;
-  /** Function path that emitted the line, e.g. `"messages:list"`. */
-  functionPath: string;
-  /** Severity the line was logged at. */
-  level: ContextLogLevel;
-  /** Rendered message. */
-  message: string;
-  /** Shard key for single-shard calls, when present. */
-  shardKey?: string;
-  /** Span id the line was emitted under, when present. */
-  spanId?: string;
-  /** Trace id the line belongs to, when present. */
-  traceId?: string;
-  /** Epoch-millis the line was emitted. */
-  ts: number;
-  /** Acting user id, when present. */
-  userId?: string;
+interface RankPageFanOutRequest {
+  /** Opaque composite cursor from the prior page's `continueCursor`. */
+  cursor?: null | string;
+  /** Per-sort-key directions, in `index.sortBy` order. Missing/short → ascending. */
+  directions?: ReadonlyArray<RankDirection>;
+  headers?: Record<string, string>;
+  /** Rank index name on `table`. */
+  index: string;
+  /** Optional partition pin forwarded to each shard's local `rankPage`. */
+  partitionKey?: string;
+  /** Table whose live shard keys the page fans out across. */
+  table: string;
+  /** Global page size; defaults to 100, capped at 1000 (matching the shard-local `rankPage`). */
+  take?: number;
 }
-/** One page of {@link PipelineLogRow}s, newest first, plus the cursor for the next page (absent means last page). */
-interface PipelineLogPage {
-  /** The cursor to pass as {@link PipelineLogQuery} `cursor` for the following page; absent when this is the last page. */
-  nextCursor?: PipelineLogCursor;
-  /** The rows, ordered `ts DESC` (newest first). At most `limit` of them. */
-  rows: PipelineLogRow[];
+/** One shard's `rankPage` outcome: its local ranked slice, or an error. */
+interface ShardRankPageOutcome {
+  /** The directions the shard ordered by (`index.sortBy[i].direction`); authoritative for the merge. */
+  directions?: ReadonlyArray<RankDirection>;
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  hasMore?: boolean;
+  rows?: ReadonlyArray<RankPageRow>;
+  shardKey: string;
 }
-/** Options for {@link createPipelineLogReader}. */
-interface PipelineLogReaderOptions {
+interface RankPageFanOutResult {
+  /** Opaque composite cursor for the next page, or `null` when the merge is exhausted. */
+  continueCursor: null | string;
+  /** Shards that errored or timed out. */
+  failed: number;
+  /** `true` when the global merge has no further rows. */
+  isDone: boolean;
+  /** Shards that returned a 2xx slice. */
+  ok: number;
+  /** The globally-ranked page of hydrated docs, in cross-shard rank order. */
+  page: ReadonlyArray<Record<string, unknown>>;
+  /** `true` when at least one shard failed/timed out, so the page may be missing that shard's rows. */
+  partial: boolean;
+  /** Per-shard outcomes, in registry order. */
+  shards: ReadonlyArray<ShardRankPageOutcome>;
+}
+interface QueryCoordinator {
+  fanOut: <T = unknown>(namespace: ShardNamespaceLike, request: FanOutRequest) => Promise<FanOutResult<T>>;
   /**
-   * Override any physical column name that diverges from the default (identity)
-   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
+   * Fan the `__lunora_admin__:applyCdc` admin RPC out by forwarding each
+   * pre-bucketed per-shard batch of CDC changes, rolling up the applied/failed
+   * counts. The replay half of point-in-time recovery.
    */
-  columnMap?: PipelineLogColumnMap;
+  orchestrateApplyCdc: (namespace: ShardNamespaceLike, request: ApplyCdcFanOutRequest) => Promise<ApplyCdcFanOutResult>;
+  /**
+   * Fan the `__lunora_admin__:cdcSync` admin RPC out to every live shard,
+   * each resumed from its own cursor in `request.cursors` (shardKey → seq).
+   * Returns the per-shard change pages plus their new cursors so the caller
+   * can checkpoint each shard independently — the streaming-export feed.
+   */
+  orchestrateCdcSync: (namespace: ShardNamespaceLike, request: CdcSyncFanOutRequest) => Promise<CdcSyncFanOutResult>;
+  /**
+   * Fan an export admin RPC out to every live shard, returning the
+   * per-shard `{rows}` payloads alongside any per-shard errors. Each shard
+   * returns a JSON envelope (not a streaming body) so this method is the
+   * collector — the worker assembles the NDJSON stream.
+   */
+  orchestrateExport: (namespace: ShardNamespaceLike, request: ExportFanOutRequest) => Promise<ExportFanOutResult>;
+  /**
+   * Fan an import admin RPC out by routing each row to its owning shard. The
+   * shard registry resolves which shards exist; rows whose table has a
+   * `shardBy(field)` are bucketed using that field's value as the shard key,
+   * other tables fall back to the runtime's default `__root__` shard.
+   */
+  orchestrateImport: (namespace: ShardNamespaceLike, request: ImportFanOutRequest) => Promise<ImportFanOutResult>;
+  /** Fan a migration admin RPC out to every live shard of a table and roll up the per-shard outcomes. */
+  orchestrateMigration: (namespace: ShardNamespaceLike, request: MigrationFanOutRequest) => Promise<MigrationFanOutResult>;
+  /**
+   * Fan the `__lunora_admin__:rankBefore` admin RPC out to every live shard of
+   * a table and roll up the per-shard `{before, total}` payloads into the
+   * global rank (`{position: Σbefore + 1, total: Σtotal}`). The cross-shard
+   * `rank()` path for a partition that spans shards.
+   */
+  orchestrateRank: (namespace: ShardNamespaceLike, request: RankFanOutRequest) => Promise<RankFanOutResult>;
+  /**
+   * Page a ranked query across every live shard of a `.shardBy(...)` table.
+   * Fans `__lunora_admin__:rankPage` out to each shard, gathers each shard's
+   * local ranked slice (rows tagged with their rank-key tuple), and k-way
+   * merges them by that tuple into one globally-ranked page of `take` rows.
+   * The opaque `continueCursor` is a composite of per-shard cursors so the
+   * next page resumes each shard strictly-after the last row the global page
+   * consumed from it — pages never drop or duplicate a row at a shard
+   * boundary. The cross-shard `rankPage()` path (PLAN5 §7.1 / PLAN2 #3).
+   */
+  orchestrateRankPage: (namespace: ShardNamespaceLike, request: RankPageFanOutRequest) => Promise<RankPageFanOutResult>;
+  /**
+   * Fan the `__lunora_admin__:getMetrics` admin RPC out to every live shard of
+   * a table and collect each shard's lifetime `requests` total into a per-shard
+   * `{ shardKey, requests }` distribution. The feed the studio's `hot_shard`
+   * advisor lint needs: a single shard's snapshot can't reveal cross-shard
+   * skew, so this fans the cheap metrics read out and returns the whole shard
+   * set's request volumes (a failed shard surfaces as `requests: 0`).
+   */
+  orchestrateShardTraffic: (namespace: ShardNamespaceLike, request: ShardTrafficFanOutRequest) => Promise<ShardTrafficFanOutResult>;
+  readonly registry: ShardRegistry;
+}
+/**
+ * Cross-shard export request. `tables` is the union of every table the caller
+ * wants exported (shard-local **or** global); `headers` carries the admin
+ * bearer the per-shard gate expects. Shard registries are queried for the
+ * complete set of live shards across all listed shard-local tables.
+ */
+interface ExportFanOutRequest {
+  args?: Record<string, unknown>;
+  headers?: Record<string, string>;
   /**
-   * The Iceberg namespace the `table` lives in (R2 Data Catalog database).
-   * Combined as `namespace.table` in the `FROM` clause; omit when `table`
-   * already carries its namespace.
+   * Tables driving the fan-out. Shards are derived from the union of each
+   * table's live shard keys — so an export of `["users","messages"]` reaches
+   * every shard that holds either table. Globals are skipped here; the
+   * worker reads them from D1 directly.
    */
-  namespace?: string;
-  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
-  table: string;
+  tables: ReadonlyArray<string>;
 }
-/** The reader surface: a single keyset-paginated {@link PipelineLogPage} query. */
-interface PipelineLogReader {
-  /** Run one filtered, keyset-paginated read and return a {@link PipelineLogPage}. */
-  query: (query?: PipelineLogQuery) => Promise<PipelineLogPage>;
+/** Per-shard export outcome. */
+interface ShardExportOutcome {
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  /** Rows from this shard, or undefined when an error occurred. */
+  rows?: ReadonlyArray<{
+    doc: Record<string, unknown>;
+    table: string;
+  }>;
+  shardKey: string;
+}
+interface ExportFanOutResult {
+  failed: number;
+  ok: number;
+  shards: ReadonlyArray<ShardExportOutcome>;
 }
-/** The written-column contract exposed publicly: canonical field to default physical column name. */
-declare const DEFAULT_LOG_COLUMNS: Readonly<Record<PipelineLogField, string>>;
-/** Default page size when a query omits `limit`. */
-declare const DEFAULT_LOG_LIMIT: number;
 /**
- * Build a durable-log reader over one R2 Data Catalog (Iceberg) table.
- *
- * The returned {@link PipelineLogReader} compiles each call to a safe
- * `SELECT ... WHERE ... ORDER BY ts DESC LIMIT n` (over-fetching by one) and
- * decodes the rows back to the canonical {@link PipelineLogRow} shape. All value
- * filters are escaped through `@lunora/bindings/r2sql`'s `sql`/`lit`; column
- * names come from `options.columnMap` (operator config), spliced with `raw`.
- * @param client An {@link R2SqlClient} (`createR2Sql({ accountId, apiToken, bucket })`).
- * @param options The target `table` (plus optional `namespace`) and any `columnMap` overrides.
+ * Cross-shard change-data-capture request. `tables` drives shard discovery (the
+ * union of their live shard keys, like export); `cursors` maps each shard key
+ * to the `seq` it was last read through (absent → from the beginning). `limit`
+ * caps each shard's page.
  */
-declare const createPipelineLogReader: (client: R2SqlClient, options: PipelineLogReaderOptions) => PipelineLogReader;
+interface CdcSyncFanOutRequest {
+  cursors?: Record<string, number>;
+  headers?: Record<string, string>;
+  limit?: number;
+  tables: ReadonlyArray<string>;
+}
+/** Per-shard CDC page: the changes plus the new cursor to resume this shard from. */
+interface ShardCdcOutcome {
+  changes?: ReadonlyArray<Record<string, unknown>>;
+  /** New per-shard cursor; on error it echoes the shard's prior cursor so a retry resumes cleanly. */
+  cursor: number;
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  shardKey: string;
+}
+interface CdcSyncFanOutResult {
+  failed: number;
+  ok: number;
+  shards: ReadonlyArray<ShardCdcOutcome>;
+}
 /**
- * Wire constants for the durable log archive, shared between the server route
- * (`@lunora/runtime`'s `log-archive-admin-routes`) and the Studio Archive feed
- * (`@lunora/studio`). Kept here — not in `@lunora/runtime` — because the studio
- * is a browser bundle that must not import a runtime *value* (which would drag
- * the DO/R2-SQL runtime into the browser). This file is dependency-free and
- * bundler-inlined into each consumer, so both sides share one source of truth
- * with no dependency edge.
+ * Cross-shard import request. Rows have already been bucketed by the runtime
+ * into one batch per shard key — the coordinator's job is to forward each
+ * batch and roll up the per-shard insert counts + errors.
  */
+interface ImportFanOutRequest {
+  /**
+   * Per-shard batches keyed by shard key. Each entry will be POSTed as the
+   * `rows` arg of `__lunora_admin__:importShard`. The shard's
+   * starting-line-number for error attribution is carried in `startLine`.
+   */
+  batches: ReadonlyArray<{
+    rows: ReadonlyArray<{
+      doc: Record<string, unknown>;
+      table: string;
+    }>;
+    shardKey: string;
+    startLine?: number;
+  }>;
+  headers?: Record<string, string>;
+}
+interface ShardImportOutcome {
+  error?: {
+    message: string;
+    timedOut: boolean;
+  };
+  result?: {
+    conflicts: number;
+    errors: ReadonlyArray<{
+      code: string;
+      line: number;
+      message: string;
+      table: string;
+    }>;
+    inserted: Record<string, number>;
+  };
+  shardKey: string;
+}
+interface ImportFanOutResult {
+  /** Total conflicts (skipped `_id`s) across shards. */
+  conflicts: number;
+  /** Errors merged across all per-shard outcomes. */
+  errors: ReadonlyArray<{
+    code: string;
+    line: number;
+    message: string;
+    table: string;
+  }>;
+  failed: number;
+  /** Per-table summed insert counts. */
+  inserted: Record<string, number>;
+  ok: number;
+  shards: ReadonlyArray<ShardImportOutcome>;
+}
 /**
- * The error `code` the archive route returns (400) when the operator has wired
- * no archive table (`logArchive`) or the `R2_SQL_*` credentials are missing. The
- * Studio keys its "not configured" empty state off this exact value.
+ * Cross-shard CDC replay request (point-in-time recovery). Changes are
+ * pre-bucketed by the runtime into one batch per shard key — the coordinator
+ * forwards each batch to `__lunora_admin__:applyCdc` and rolls up the counts.
  */
-declare const LOG_ARCHIVE_NOT_CONFIGURED = "LOG_ARCHIVE_NOT_CONFIGURED";
-/** The route the studio's `queryLogArchive` client method POSTs to. */
-declare const LOG_ARCHIVE_PATH = "/_lunora/admin/logs/archive";
+interface ApplyCdcFanOutRequest {
+  batches: ReadonlyArray<{
+    changes: ReadonlyArray<Record<string, unknown>>;
+    shardKey: string;
+  }>;
+  headers?: Record<string, string>;
+}
+interface ApplyCdcFanOutResult {
+  /** Total changes applied across shards. */
+  applied: number;
+  failed: number;
+  ok: number;
+}
 /**
- * The app-level archive config the worker passes through: which Data Catalog
- * table the Pipeline writes log records to (the read-side of `pipelineLogSink`),
- * plus optional namespace / physical-column overrides. The R2 SQL *credentials*
- * are NOT here — they live on `env` (`R2_SQL_*`), read per request.
+ * Cross-shard traffic request. Like {@link MigrationFanOutRequest} there is no
+ * caller-supplied merge — each shard's `__lunora_admin__:getMetrics` payload
+ * carries its own lifetime `requests` total, and {@link rollUpShardTraffic}
+ * collects them into one `{ shardKey, requests }` entry per shard. `headers`
+ * must carry the admin bearer the per-shard `getMetrics` gate requires.
+ *
+ * `table` drives shard discovery: the registry's live shard keys for the table
+ * are the shards fanned out to. This is the feed the studio's `hot_shard`
+ * runtime advisor consumes to compute cross-shard skew — a single shard's
+ * snapshot can't, so the panel fans this out on demand.
  */
-interface LogArchiveConfig {
-  /** Override any physical column name that diverges from the {@link createPipelineLogReader} default mapping. */
-  columnMap?: PipelineLogColumnMap;
-  /** The Iceberg namespace (R2 Data Catalog database) the table lives in; omit when `table` already carries it. */
-  namespace?: string;
-  /** The Iceberg table the Pipeline writes log records to (e.g. `"logs"`). */
+interface ShardTrafficFanOutRequest {
+  headers?: Record<string, string>;
+  /** Table whose live shard keys the traffic fan-out runs across. */
   table: string;
 }
+/** One shard's traffic total, mirroring the advisor's `AdvisorShardTraffic` (sans the optional `group`). */
+interface ShardTrafficEntry {
+  /** Lifetime request count read off the shard's `getMetrics` snapshot; `0` for a shard that failed/timed out. */
+  requests: number;
+  /** The shard key (the DO id name); `""` for the unnamed root shard. */
+  shardKey: string;
+}
+interface ShardTrafficFanOutResult {
+  /** Shards that errored or timed out (their `requests` are reported as `0`). */
+  failed: number;
+  /** Shards that returned a 2xx `getMetrics` snapshot. */
+  ok: number;
+  /**
+   * Per-shard request totals, in registry order. Shaped to plug straight into
+   * the advisor's `LintContext.shardTraffic` so the `hot_shard` lint can
+   * compute the cross-shard share. A failed shard still appears (with
+   * `requests: 0`) so callers see the full shard set.
+   */
+  shards: ReadonlyArray<ShardTrafficEntry>;
+}
+declare const createQueryCoordinator: (options: QueryCoordinatorOptions) => QueryCoordinator;
 /**
- * Build the {@link LogArchiveConfig} from `env` for the generated worker entry —
- * the zero-config seam the codegen `createWorker({ logArchive })` wiring uses,
- * mirroring how the R2 SQL *credentials* already come from `env` (`R2_SQL_*`).
- *
- * Returns `undefined` unless `LUNORA_LOG_ARCHIVE_TABLE` is set, so the studio
- * Archive feed stays "not configured" until the operator opts in by naming the
- * Data Catalog table (+ optional `LUNORA_LOG_ARCHIVE_NAMESPACE`). `columnMap`
- * overrides aren't env-expressible — a hand-written worker passes `logArchive`
- * to `createWorker` directly for those.
+ * One change in the export stream — a clean projection of the raw op-log CDC
+ * record that preserves `seq` (for ordering / idempotency downstream) and the
+ * post-image `doc`. A delete carries no `doc`; the primary key survives in `id`.
  */
-declare const resolveLogArchiveFromEnv: (environment: unknown) => LogArchiveConfig | undefined;
+interface ExportChange {
+  doc?: Record<string, unknown>;
+  id?: string;
+  op: "delete" | "insert" | "update" | "upsert";
+  seq?: number;
+  table: string;
+  ts?: number;
+}
+/** One shard's batch handed to a sink. `cursor` is the new watermark this batch advances the shard to on ack. */
+interface ExportBatch {
+  changes: ReadonlyArray<ExportChange>;
+  cursor: number;
+  shardKey: string;
+  sink: string;
+}
 /**
- * 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.
+ * An export sink. `deliver` MUST reject (throw) when the batch was not durably
+ * accepted downstream — a resolved promise is treated as an acknowledgement and
+ * advances the cursor. Build one with {@link defineExportSink}, or use the
+ * built-in {@link webhookExportSink} / {@link r2Sink}.
  */
-type MetricKind = "counter" | "gauge" | "histogram";
+interface ExportSink {
+  deliver: (batch: ExportBatch) => Promise<void>;
+  name: string;
+}
 /**
- * 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.
+ * Durable per-shard cursor store, keyed by sink name. Mirrors the
+ * `__lunora_source_cursor` watermark from CDC-in: the last op-log `seq` each
+ * shard was delivered through. Injected so the tap stays testable and workerd-safe
+ * — {@link createMemoryCursorStore} for tests, {@link createKvCursorStore} for a
+ * deployment.
  */
-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"`. */
+interface ExportCursorStore {
+  read: (sink: string) => Promise<Record<string, number>>;
+  write: (sink: string, cursors: Record<string, number>) => Promise<void>;
+}
+/** A shard the tap could not drain this pass (sink failure or shard error); its cursor was left un-advanced for retry. */
+interface ExportTapFailure {
+  error: string;
+  shardKey: string;
+}
+/** Outcome of one drain pass. */
+interface ExportTapResult {
+  /** The persisted per-shard cursor map after this pass. */
+  cursors: Record<string, number>;
+  /** Total changes acknowledged by the sink this pass. */
+  delivered: number;
+  /** Shards left un-advanced (retry pending). Their presence does not stall other shards or the shard's writes. */
+  failures: ReadonlyArray<ExportTapFailure>;
+  /** `true` when any shard returned a full page (more changes likely remain) or any shard failed — the caller should schedule another pass. */
+  hasMore: boolean;
+  /** Number of shards inspected this pass. */
+  shards: number;
+}
+/** Options for one {@link runExportTap} drain pass. */
+interface RunExportTapOptions {
+  /** Cross-shard coordinator providing the op-log change feed. */
+  coordinator: QueryCoordinator;
+  /** Durable cursor store (per-shard watermark). */
+  cursorStore: ExportCursorStore;
+  /** Headers forwarded to each shard (identity / admin bearer). */
+  headers?: Record<string, string>;
+  /** Base backoff in ms for the first retry (doubles each attempt, capped at `maxBackoffMs`). Defaults to `100`. */
+  initialBackoffMs?: number;
+  /** Per-shard page size. */
+  limit?: number;
+  /** Cap on the exponential backoff delay. Defaults to `5000`. */
+  maxBackoffMs?: number;
+  /** Retries after the first delivery attempt before a shard is left for the next pass. Defaults to `3`. */
+  maxRetries?: number;
+  /** The shard DO namespace to fan the feed across. */
+  shardDO: ShardNamespaceLike;
+  /** The sink to deliver to. */
+  sink: ExportSink;
+  /** Injected sleep (defaults to a real timer) so tests drive backoff deterministically. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Tables driving shard discovery (union of their live shard keys). */
+  tables: ReadonlyArray<string>;
+}
+/**
+ * Project a raw op-log CDC record (`{ id, op, seq, table, ts, doc? }`) into a
+ * clean {@link ExportChange}. Mirrors `./connector-cdc`'s `flattenCdcChange` but
+ * PRESERVES `seq` / `id` / `ts` so a downstream warehouse can order and dedupe.
+ */
+declare const sanitizeChange: (raw: Record<string, unknown>) => ExportChange;
+/**
+ * Run one drain pass of the export tap for a single sink. Reads the durable
+ * cursor, pulls the op-log change feed, delivers each shard's ordered batch (with
+ * retry/backoff), advances only the cursors of shards the sink acknowledged, and
+ * persists the merged cursor map. Idempotent to schedule repeatedly (cron / admin
+ * poke); `hasMore` signals whether another pass is warranted immediately.
+ */
+declare const runExportTap: (options: RunExportTapOptions) => Promise<ExportTapResult>;
+/**
+ * Define a custom export sink. A thin identity wrapper that validates the shape
+ * and gives call sites a named factory symmetric with `defineExportSink` in the
+ * plan. The `deliver` contract: resolve on durable acceptance, reject otherwise.
+ */
+declare const defineExportSink: (config: ExportSink) => ExportSink;
+/** `fetch`-like signature so the webhook sink is testable without a real network. */
+type FetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+}) => Promise<{
+  ok: boolean;
+  status: number;
+}>;
+/**
+ * Built-in webhook sink: POST the shard's changes as an NDJSON body to `url`. A
+ * non-2xx response rejects, so the tap retries + applies backpressure. Idempotency
+ * headers (`x-lunora-sink`, `x-lunora-shard`, `x-lunora-cursor`) let the receiver
+ * dedupe an at-least-once replay.
+ */
+declare const webhookExportSink: (config: {
+  fetchImpl?: FetchLike;
+  headers?: Record<string, string>;
   name: string;
-  /** Shard key for single-shard calls; absent for the unnamed root DO. */
-  shardKey?: string;
-  /** Wall-clock millis when the measurement was recorded. */
-  ts: number;
-  /**
-   * The measured value: the increment for a `counter`, the current reading for
-   * a `gauge`, the observed sample for a `histogram`.
-   */
-  value: number;
+  url: string;
+}) => ExportSink;
+/** Minimal R2 bucket surface the sink needs (structurally compatible with an `R2Bucket` binding). */
+interface R2PutLike {
+  put: (key: string, value: string, options?: {
+    httpMetadata?: {
+      contentType?: string;
+    };
+  }) => Promise<unknown>;
 }
 /**
- * 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.
+ * Built-in R2 sink: write each shard's changes as an NDJSON object under
+ * `&lt;prefix>/&lt;shardKey>/&lt;cursor>.ndjson`. The cursor in the key makes each object
+ * content-addressed by watermark, so an at-least-once replay overwrites the same
+ * key rather than duplicating (idempotent at the object level). A `put` rejection
+ * propagates so the tap retries.
  */
-interface SpanEvent {
-  /**
-   * Structured attributes the caller attached, already normalized to a fresh
-   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
-   * line's `fields`. Absent when the caller passed none.
-   */
-  attributes?: LogFields;
-  /** Wall-clock duration of the span body, in milliseconds. */
-  durationMs: number;
-  /**
-   * Populated when the span body threw. `type` is the error's constructor name
-   * (or its `LunoraError` code); `message` is the human-readable string and may
-   * include user input, so sinks shipping to third parties should scrub it.
-   */
-  error?: {
-    message: string;
-    type: string;
-  };
-  /**
-   * Function path the span was created under, e.g. `"messages:list"`. A span
-   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
-   * `runAction` carries the OUTER entrypoint's path, since the composed call
-   * reuses its context — the same attribution rule `ctx.log` follows.
-   */
-  functionPath: string;
-  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+declare const r2Sink: (config: {
+  bucket: R2PutLike;
   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".
+  prefix?: string;
+}) => ExportSink;
+/** In-memory cursor store for tests. `snapshot` exposes the persisted cursors for assertions. */
+declare const createMemoryCursorStore: () => ExportCursorStore & {
+  snapshot: () => Record<string, Record<string, number>>;
+};
+/** Minimal KV surface the cursor store needs (structurally compatible with a `KVNamespace` binding). */
+interface KvLike {
+  get: (key: string, type: "json") => Promise<unknown>;
+  put: (key: string, value: string) => Promise<unknown>;
+}
+/**
+ * KV-backed durable cursor store. The watermark key mirrors the CDC-in
+ * convention (`__lunora_source_cursor`): `__lunora_source_cursor:export:&lt;sink>`.
+ * A missing / malformed value reads as the empty map (drain from the beginning),
+ * so a fresh sink or a corrupted key can never crash the pass.
+ */
+declare const createKvCursorStore: (kv: KvLike, options?: {
+  keyPrefix?: string;
+}) => ExportCursorStore;
+declare const HEALTH_PATH = "/_lunora/health";
+declare const HEALTH_READY_PATH = "/_lunora/health/ready";
+/** Which probe(s) a check participates in. `both` (the default) runs on the aggregate probe and the readiness gate. */
+type HealthProbeKind = "both" | "liveness" | "readiness";
+/** The verdict a single probe returns. `message` is runtime-authored and must never echo a secret, env value, or user binding name. */
+interface HealthProbeResult {
+  healthy: boolean;
+  /** Optional runtime-authored detail (e.g. "binding unreachable"). Included only in the `admin` posture. */
+  message?: string;
+}
+/** One registered health check over a binding or subsystem. */
+interface HealthProbe {
+  /**
+   * The async probe. It must be cheap and self-contained; a thrown error is
+   * treated as an unhealthy result (fail-closed) so a probe bug never 500s the
+   * endpoint.
+   */
+  check: () => Promise<HealthProbeResult> | HealthProbeResult;
+  /**
+   * A critical dependency flips the aggregate `/_lunora/health` probe to `503`
+   * when unhealthy. A non-critical one only degrades the reported status.
+   */
+  critical?: boolean;
+  /** Which probe(s) this check runs on. Defaults to `"both"`. */
+  kind?: HealthProbeKind;
+  /** Stable check name surfaced in the report (e.g. `"durable-object"`, `"d1"`). Not a secret. */
+  name: string;
+}
+/** Auth posture for the health endpoints. `"public"` (default) is unauthenticated + message-redacted; `"admin"` requires a valid admin bearer. */
+type HealthAuthPosture = "admin" | "public";
+/** One check's line in the response body. */
+interface HealthCheckReport {
+  critical: boolean;
+  /** Present only in the `admin` posture. */
+  message?: string;
+  name: string;
+  status: "down" | "up";
+}
+/** The health response body. Deliberately minimal — status, per-check up/down, and static app metadata only. */
+interface HealthBody {
+  appName: string;
+  appVersion: string;
+  checks: HealthCheckReport[];
+  status: "degraded" | "healthy" | "unhealthy";
+  timestamp: string;
+}
+/** Injected dependencies for the health routes. Probes are resolved per-request so they can read the invocation `env` (bindings only exist at request time). */
+interface HealthRouteDeps {
+  /** Static application name surfaced in the body. Not a secret. */
+  appName?: string;
+  /** Static application version surfaced in the body. Not a secret. */
+  appVersion?: string;
+  /** Auth posture. Defaults to `"public"`. */
+  auth?: HealthAuthPosture;
+  /**
+   * Cache the last computed report for this many ms so an orchestrator polling
+   * every few seconds does not hammer the bindings. Defaults to `0` (no cache).
    */
-  parentSpanId: string;
+  cacheTtlMs?: number;
+  /** Admin-bearer predicate, consulted only when `auth === "admin"`. */
+  isAdmin: (request: Request) => boolean;
   /**
-   * 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.
+   * Resolve the probes for this invocation from its `env`. Called once per
+   * request; the returned probes are registered on a fresh `HealthCheck`
+   * registry so the report reflects the live bindings.
    */
-  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;
+  resolveProbes: (env: unknown) => ReadonlyArray<HealthProbe>;
 }
+/** Build the health + readiness route map merged into the worker's internal route table. */
+declare const buildHealthRoutes: (deps: HealthRouteDeps) => Record<string, (request: Request, env: unknown) => Promise<Response>>;
 /**
- * Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
- * fan-outs set `fanOut` with the table being aggregated, shard count, and
- * per-shard failure count.
+ * Structural probe of a Durable Object namespace's reachability: resolve the
+ * default shard stub and issue a cheap request. ANY response (even a `404` for
+ * an unknown path) proves the DO answered; only a thrown error means the object
+ * is unreachable. Never inspects the response body, so it cannot leak state.
  */
-interface ObservabilityEvent {
-  /** Wall-clock duration of the dispatch, in milliseconds. */
-  durationMs: number;
+declare const durableObjectProbe: (name: string, namespace: {
+  get: (id: unknown) => {
+    fetch: (request: Request) => Promise<Response>;
+  };
+  idFromName: (id: string) => unknown;
+}, shardKey: string) => HealthProbe;
+/**
+ * Active probe of a D1 database: run `SELECT 1`. Healthy when it resolves. The
+ * binding is passed structurally (only `.prepare().first()` is used) so the
+ * runtime stays free of a hard `@cloudflare/workers-types` dependency.
+ */
+declare const d1Probe: (name: string, database: {
+  prepare: (sql: string) => {
+    first: () => Promise<unknown>;
+  };
+}) => HealthProbe;
+/**
+ * Presence check for a binding whose remote health cannot be probed cheaply (R2,
+ * queues, Hyperdrive). A bound, well-shaped value reports healthy; the check does
+ * NOT perform a billable remote op. Non-critical by default: a presence gap
+ * degrades the status without forcing a `503`.
+ */
+declare const presenceProbe: (name: string, bound: boolean) => HealthProbe;
+/**
+ * Identity resolved from the inbound request by `WorkerOptions.resolveIdentity`.
+ *
+ * The `userId` field is special — it becomes `ctx.auth.userId` inside the
+ * Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
+ * forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
+ *
+ * Return `null` to signal that the request is anonymous; the runtime will
+ * skip both `x-lunora-userid` and `x-lunora-identity` headers, and
+ * `ctx.auth.userId` will be `undefined` on the shard side.
+ */
+interface ResolvedIdentity {
+  /** Arbitrary additional claims. Must be JSON-serialisable. */
+  [key: string]: unknown;
   /**
-   * Populated on `ok === false`. `code`/`status` mirror the LunoraError
-   * taxonomy; `message` is the human-readable string (may include user
-   * input — sinks that ship to third parties should scrub it).
+   * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
+   * absent), the runtime forwards it as the socket's credential expiry — the
+   * DO drops the socket once it lapses. Used only on the WebSocket path.
    */
-  error?: {
-    code: string;
-    message: string;
-    status: number;
-  };
+  exp?: number;
   /**
-   * Populated for fan-out dispatches.
-   * `shards` is the total fan-out cardinality; `failed` counts shards that
-   * timed out or returned an error (the same `errors[]` the response body
-   * carries to the caller).
+   * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
+   * both are present. Forwarded as the socket's expiry on the WebSocket path
+   * so the DO drops the socket once it lapses; omit for non-expiring sessions.
    */
-  fanOut?: {
-    failed: number;
-    shards: number;
-    table: string;
-  };
-  /** Function path being invoked, e.g. `"messages:list"`. */
-  functionPath: string;
-  /** True when the dispatch completed without throwing. */
-  ok: boolean;
-  /** Shard key for single-shard calls; absent for fan-outs. */
-  shardKey?: string;
+  expiresAtMs?: number;
+  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
+  userId: string;
+}
+/**
+ * A verifier that turns an inbound request into a {@link ResolvedIdentity} (or
+ * `null` for anonymous). Structurally identical to `WorkerOptions.resolveIdentity`,
+ * so `.auth()`'s better-auth session resolver, a signed-preview-link verifier, a
+ * per-tenant bearer check, an upstream-JWT reader, … are all just `IdentityResolver`s
+ * — the identity layer is generic over every scheme, not coupled to any one.
+ */
+type IdentityResolver = (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
+/** Error policy for {@link composeIdentityResolvers} when a participant resolver throws. */
+type ComposeIdentityResolversErrorMode = "fail-closed" | "skip";
+/** Options for {@link composeIdentityResolvers}. */
+interface ComposeIdentityResolversOptions {
   /**
-   * W3C trace context for this dispatch, generated once at dispatch entry (32-
-   * and 16-hex). A sink (e.g. `otlpSink`) reuses these for the dispatch's span
-   * instead of minting fresh ids, and the runtime propagates them to the shard
-   * as a `traceparent` so a container the handler calls can stitch its spans
-   * under the same trace. Absent on paths that don't originate a trace (a sink
-   * falls back to random ids).
+   * What to do when a resolver throws. `"fail-closed"` (default, safe)
+   * re-throws so a broken verifier fails the request rather than silently
+   * falling through to a weaker one; `"skip"` swallows the error and tries the
+   * next resolver (use only when a resolver's failure genuinely means "not my
+   * scheme").
    */
-  spanId?: string;
-  traceId?: string;
+  readonly onError?: ComposeIdentityResolversErrorMode;
 }
 /**
- * The `ctx.log` observability contract lives in `shared/` (inlined into each
- * `dist`) so the DO that builds the events and the runtime sink that consumes
- * them agree by construction rather than by hand-mirrored duplication. Re-exported
- * here under the runtime's historical names.
+ * Compose several {@link IdentityResolver}s into one, first-match-wins: each is
+ * tried in order and the first that returns a non-null identity short-circuits.
+ * Generic over every scheme — the better-auth session resolver (obtained via the
+ * builder's `derived.resolveIdentity` escape hatch) is just one entry in the list,
+ * so composition never means losing it.
  *
- * `LogLevel` is the canonical `ctx.log` severity union (the five console tiers
- * plus `trace`/`fatal`); `ObservabilitySinkContext` is the shared per-event sink
- * context (a `waitUntil` to keep a background send alive past the response).
+ * A resolver that throws is handled per {@link ComposeIdentityResolversOptions.onError}
+ * (default `"fail-closed"`: the error propagates).
  */
-type LogLevel = ContextLogLevel;
-type ObservabilitySinkContext = LogSinkContext;
+declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
 /**
- * The hook contract. Methods are optional so a sink can opt into only the
- * events it cares about; the runtime no-ops the others.
+ * A thin, generic helper over {@link composeIdentityResolvers} for the per-route case:
+ * pick a resolver by `new URL(request.url).pathname`. Keys are matched by longest
+ * path prefix; `"*"` is the fallback. Still fully generic — a route→resolver map,
+ * with no portal / preview / tenant concepts baked in (those live in the app's
+ * own resolvers).
+ * @example
+ * routeIdentityResolvers({ "/admin": adminResolver, "/partner": partnerResolver, "*": sessionResolver })
  */
-interface ObservabilitySink {
-  /** Invoked once per `ctx.log.*` call from a function handler. */
-  onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
-  /**
-   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
-   * upstream, so counter values are deltas for the destination to sum.
-   */
-  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
-  /** Invoked once per dispatched RPC (single-shard or fan-out). */
-  onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
-  /**
-   * Invoked once per `ctx.trace(name, fn)` span, when the span body settles.
-   * Distinct from `onRpc`: that is the one SERVER span per dispatch, this is the
-   * INTERNAL spans a handler creates beneath it.
-   */
-  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
+declare const routeIdentityResolvers: (routes: Record<string, IdentityResolver>) => IdentityResolver;
+/** The result of validating a candidate identity against an {@link IdentityContractLike}. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
+/**
+ * Structural view of `@lunora/server`'s `IdentityContract` (from `defineIdentity`).
+ * Kept structural so `@lunora/runtime` stays free of an `@lunora/server` dependency.
+ * Keep the `onInvalid` union and `validate`/`IdentityValidation` shapes in sync with
+ * `@lunora/server`'s `IdentityContract` — they are projected by hand, not imported.
+ * The generated worker entry passes the app's `defineIdentity(...)` result here;
+ * the worker validates every resolver's returned claims against it at the trust
+ * boundary before they become `ctx.auth`.
+ */
+interface IdentityContractLike {
+  /** Reject policy applied when validation fails: downgrade to anonymous, or reject the request (401). */
+  readonly onInvalid: "anonymous" | "reject";
+  /** Validate resolver-returned claims against the declared contract. */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/** One KV namespace as the studio's KV browser surfaces it. */
+interface KvNamespaceSummary {
+  /** The wrangler/env binding name, e.g. `"MY_KV"`. */
+  binding: string;
+}
+/** One key entry as the KV admin browser surfaces it. */
+interface KvKeyEntry {
+  /** Absolute expiration (Unix seconds), when set. */
+  expiration?: number;
+  /** Per-key metadata set at write time, or absent when none. */
+  metadata?: unknown;
+  /** The key name. */
+  name: string;
+}
+/** A paginated page of KV keys as the admin browser returns it. */
+interface KvKeyListResult {
+  /** Opaque cursor for the next page; absent when the listing is complete. */
+  cursor?: string;
+  /** The keys on this page. */
+  keys: KvKeyEntry[];
+  /** True when this is the final page. */
+  listComplete: boolean;
+}
+/** A KV value together with its stored metadata. */
+interface KvValueResult {
+  /** Per-key metadata, or `null` when none. */
+  metadata: unknown;
+  /** The stored value as a string, or `null` when the key is absent. */
+  value: null | string;
 }
 /**
- * Invoke `sink.onRpc` with the given event, swallowing any error the sink
- * throws. Use at the dispatch boundary; the runtime should never see a
- * sink-originating throw bubble up past this point. `context.waitUntil`, when
- * supplied, lets a network sink keep its send alive past the response.
+ * The introspector the worker wires for the studio's KV browser. Build it from
+ * the env's bound KV namespaces. Omit it and the `/_lunora/admin/kv/*`
+ * endpoints respond `KV_NOT_CONFIGURED`.
  */
-declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
+interface KvIntrospector {
+  /** Delete a key from a namespace. No-op when the key is absent. */
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  /** Read a value (as text) and its metadata from a namespace key. */
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResult>;
+  /** List keys in a namespace, optionally filtered by prefix and paginated. */
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResult>;
+  /** List the registered KV namespaces (binding names). */
+  listNamespaces: () => Promise<KvNamespaceSummary[]>;
+  /** Write a value (as text) with optional absolute expiration / relative TTL and metadata. */
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
 /**
- * Invoke `sink.onLog` with the given log event, swallowing any error the sink
- * throws. The same failure model as {@link emitRpcEvent}: a buggy log sink must
- * never break the handler that emitted the line.
+ * 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.
  */
-declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
+/** Structured, filterable key/value fields attached to a `ctx.log` line. */
+type LogFields = Record<string, unknown>;
 /**
- * Cloudflare Durable Object jurisdictions restrict where a DO runs and persists
- * data, for data-residency / compliance regimes (GDPR, FedRAMP, US data
- * residency). The set is open — Cloudflare adds values over time — so this is a
- * widening union rather than a closed enum.
- * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+ * 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 DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+type ContextLogLevel = "debug" | "error" | "fatal" | "info" | "log" | "trace" | "warn";
 /**
- * Structural projection of the bits of `DurableObjectNamespace` the runtime
- * needs. Real workers-types defines a much wider surface; this lets us pass
- * unit-test doubles without coupling to `@cloudflare/workers-types`.
+ * Per-event context handed to a sink alongside the event: lets a sink register
+ * background work (a telemetry POST, a durable pipeline send) with the request's
+ * `waitUntil` so it survives isolate teardown after the response returns. Absent
+ * `waitUntil` (no request context) means the sink falls back to fire-and-forget.
  */
-interface ShardNamespaceLike {
-  get: (id: unknown) => {
-    fetch: (request: Request) => Promise<Response>;
-  };
-  /**
-   * `getByName` is the friendlier API but isn't on every workers-types
-   * release yet. We prefer it when available and fall back to
-   * `idFromName` + `get` for compatibility.
-   */
-  getByName?: (name: string) => {
-    fetch: (request: Request) => Promise<Response>;
-  };
-  idFromName: (name: string) => unknown;
+interface LogSinkContext {
   /**
-   * Derive a jurisdiction-restricted subnamespace. Every ID and stub created
-   * from the returned namespace is pinned to `jurisdiction`. Optional because
-   * older workers-types releases (and unit-test doubles) may not expose it;
-   * {@link applyJurisdiction} fails closed when a jurisdiction is requested
-   * but this method is absent.
-   */
-  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ShardNamespaceLike;
-}
-interface ResolvedShard {
-  fetch: (request: Request) => Promise<Response>;
+   * Resolves this request's detected OTLP resource attributes (`service.version`,
+   * `cloud.region`, …) on demand, or absent when the host does not detect any.
+   *
+   * Deliberately a resolved, allowlisted bag behind a thunk rather than the raw
+   * `env` and `Request` the host detected them from: this context is fanned out
+   * to **every** registered sink, including user-authored ones, so anything
+   * reachable here should be assumed to end up in someone's debug log — and raw
+   * `env` is every secret binding, while a raw `Request` carries the caller's
+   * `Authorization` and `Cookie`. The thunk keeps detection lazy (a sink that
+   * does not want resource attributes pays nothing) and hosts are expected to
+   * memoize it per request.
+   */
+  resourceAttributes?: () => Record<string, boolean | number | string>;
+  /** Keep a background promise alive past the response (the request's `waitUntil`). */
+  waitUntil?: (promise: Promise<unknown>) => void;
 }
 /**
- * Return a jurisdiction-restricted view of `namespace`, or `namespace`
- * unchanged when no jurisdiction is configured.
- *
- * Fail-closed: if a jurisdiction is requested but the binding does not expose
- * `.jurisdiction()` (an older workers-types, or a misconfigured test double),
- * this throws rather than silently routing to the un-pinned global namespace —
- * silently dropping a residency constraint would let data land outside the
- * compliance boundary the caller asked for.
- */
-declare const applyJurisdiction: (namespace: ShardNamespaceLike, jurisdiction?: DurableObjectJurisdiction) => ShardNamespaceLike;
-/** Look up a shard stub by name, preferring `getByName` when present. */
-declare const resolveShard: (namespace: ShardNamespaceLike, shardKey: string) => ResolvedShard;
-/**
- * Source of "which shard keys exist for a given table right now". Returning
- * an empty array is valid — the coordinator will respond with the merge
- * strategy's identity (empty array for `concat`, `0` for `sum`, etc.).
+ * One application log line emitted from a function handler via `ctx.log`.
+ * Produced per `ctx.log.*` call (unlike a per-dispatch RPC summary).
  */
-interface ShardRegistry {
-  listShardKeys: (table: string) => Promise<ReadonlyArray<string>> | ReadonlyArray<string>;
+interface LogEvent {
+  /** Raw arguments passed to the `ctx.log.*` call, in order. */
+  args: unknown[];
+  /**
+   * Structured fields the caller attached (`ctx.log.info(message, fields)` or a
+   * bound `ctx.log.with(fields)` child), already normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). Absent for a plain
+   * console-style call.
+   */
+  fields?: LogFields;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Display string — the message, or the console-style args rendered and space-joined. */
+  message: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Span id of the RPC this line was emitted under (trace correlation), or absent. */
+  spanId?: string;
+  /** Trace id this line belongs to (from the inbound `traceparent`), or absent. */
+  traceId?: string;
+  /** Wall-clock millis when the line was emitted. */
+  ts: number;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
 }
 /**
- * Static-map implementation. Useful for tests and for small deployments
- * where shard keys are known up front (e.g. a fixed set of channel IDs).
+ * The written-column contract: every field `pipelineLogSink` emits, mapped to the
+ * column it is stored under by default (the identity mapping). Also the source of
+ * truth for the {@link PipelineLogField} union. Mirrors the record built in
+ * `pipelineLogSink` — the read side of the same contract.
  */
-declare const createStaticShardRegistry: (table_to_keys: Readonly<Record<string, ReadonlyArray<string>>>) => ShardRegistry;
+declare const DEFAULT_COLUMNS: {
+  readonly fields: "fields";
+  readonly functionPath: "functionPath";
+  readonly level: "level";
+  readonly message: "message";
+  readonly shardKey: "shardKey";
+  readonly spanId: "spanId";
+  readonly traceId: "traceId";
+  readonly ts: "ts";
+  readonly userId: "userId";
+};
 /**
- * Wire-serializable merge strategy. `topK.by` is a field name on the row
- * (the runtime looks it up with a string key), not a closure.
- *
- * Aggregate-friendly variants for cross-shard `count` / `aggregate` /
- * `groupBy` fan-outs:
- *
- * - `sum` — `count(*)`, `aggregate({ op: "sum" })` (sums numeric per-shard payloads).
- * - `max` — `aggregate({ op: "max" })`.
- * - `min` — `aggregate({ op: "min" })`.
- * - `groupBy` — per-shard `GroupByEntry[]` payloads, reduced into one
- * entry per distinct key tuple. `op` controls how values combine across
- * shards: `sum` (default — works for `COUNT(*)` and `SUM`), `max`, `min`.
- *
- * `avg` is intentionally absent in v1 — a correct cross-shard average
- * requires shipping `(sum, count)` per shard, not the post-shard mean.
- * Use two separate fan-outs (`sum` + `count`) and divide in the caller.
- *
- * `rank` — cross-shard `rank()` over a partition that spans shards (e.g. a
- * global leaderboard `.shardBy("userId")` with `rankIndex(partitionBy: [])`).
- * Each shard's `__lunora_admin__:rankBefore` returns `{before, total}` (its
- * local rows strictly-before the explicit key, plus its local partition
- * total); the merge sums them into `{position: Σbefore + 1, total: Σtotal}` —
- * the 1-based global position and global partition size.
+ * The canonical field names of one persisted log record — the keys
+ * `pipelineLogSink` writes. Used as the {@link PipelineLogColumnMap} keys and the
+ * {@link PipelineLogRow} shape, so the reader stays decoupled from whatever
+ * physical column names the operator's Iceberg table happens to use.
  */
-type MergeStrategy = {
-  kind: "concat";
-} | {
-  by: string;
-  direction?: "asc" | "desc";
-  k: number;
-  kind: "topK";
-} | {
-  kind: "first";
-} | {
-  kind: "max";
-} | {
-  kind: "min";
-} | {
-  kind: "rank";
-} | {
-  kind: "sum";
-} | {
-  kind: "groupBy";
-  op?: "max" | "min" | "sum";
-};
+type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
 /**
- * Convenience: build the right wire-serializable {@link MergeStrategy} for a
- * given aggregate read. The reader doesn't know which op the caller chose, so
- * a fan-out wrapper passes the user's op + by-keys through this to derive the
- * merge.
- *
- * - `count` → `sum`.
- * - `aggregate({ op })` → `sum`/`max`/`min` (or throws for `avg`).
- * - `groupBy({ by, agg })` → `groupBy({ op })` (defaults to `sum` since
- * `groupBy`'s default reducer is `count`).
- * @returns the derived {@link MergeStrategy}.
+ * Field-to-column-name map. Defaults to the identity mapping (each field stored
+ * under its own name, matching what `pipelineLogSink` writes). Override per-field
+ * when the Iceberg schema renames a column; unspecified fields keep their
+ * default. This is the single knob that lets one reader serve differently shaped
+ * Data Catalog tables.
  */
-declare const mergeStrategyForAggregate: (input: {
-  agg?: {
-    op?: "avg" | "count" | "max" | "min" | "sum";
-  };
-  kind: "groupBy";
-} | {
-  kind: "count";
-} | {
-  kind: "scalar";
-  op: "avg" | "count" | "max" | "min" | "sum";
-}) => MergeStrategy;
-interface FanOutSpec {
-  merge: MergeStrategy;
-  /** Table whose shard keys drive the fan-out. */
-  table: string;
+type PipelineLogColumnMap = Partial<Record<PipelineLogField, string>>;
+/** An opaque keyset cursor: the `ts` of the row after the last one returned. */
+interface PipelineLogCursor {
+  /** Epoch-millis boundary; the next page is every row strictly older than this. */
+  ts: number;
+}
+/** Filters for one {@link PipelineLogReader} query. Every value is inlined safely (`lit`/`sql`). */
+interface PipelineLogQuery {
+  /** Continue after a previous page (keyset on `ts DESC`). Combined with the other filters. */
+  cursor?: PipelineLogCursor;
+  /** Match only this exact function path's records. Prefer `functionPathPrefix` for a namespace sweep. */
+  functionPath?: string;
+  /** Match records whose `functionPath` starts with this string (rendered as a `LIKE 'prefix%'`). */
+  functionPathPrefix?: string;
+  /** Match only this exact severity. When set, `minLevel` is ignored for the same field. */
+  level?: ContextLogLevel;
+  /** Max rows to return. Clamped to `[1, 10000]`; defaults to {@link DEFAULT_LOG_LIMIT}. */
+  limit?: number;
+  /** Severity floor: keep every level at or above this in {@link LOG_LEVEL_ORDER} (e.g. `warn` keeps warn, error, fatal). */
+  minLevel?: ContextLogLevel;
+  /** Match only this shard key. */
+  shardKey?: string;
+  /** Lower time bound, inclusive (`ts` at or after this), epoch-millis. */
+  sinceTs?: number;
+  /** Match only this trace id. */
+  traceId?: string;
+  /** Upper time bound, inclusive (`ts` at or before this), epoch-millis. */
+  untilTs?: number;
+  /** Match only this acting user id. */
+  userId?: string;
 }
 /**
- * Per-shard failure surfaced in the aggregate response's `errors` field. We
- * never throw out of `fanOut` — slow/failed shards are *data*, not an
- * exception, so callers can decide whether to retry or surface a partial
- * UI.
+ * One decoded log record. Always keyed by the canonical {@link PipelineLogField}
+ * names regardless of the physical columns (the reader remaps via `columnMap`),
+ * so consumers never see the operator's storage names.
  */
-interface ShardError {
-  /** Human-readable; tests assert on `.includes("timeout")` and similar. */
+interface PipelineLogRow {
+  /**
+   * Structured fields, when the record carried them. A `serializeFields` sink
+   * stores these as a JSON string, which the reader parses back to an object;
+   * a plain string that is not valid JSON is returned verbatim.
+   */
+  fields?: unknown;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Rendered message. */
   message: string;
-  shardKey: string;
-  /** Set when the per-shard timeout fired. */
-  timedOut: boolean;
+  /** Shard key for single-shard calls, when present. */
+  shardKey?: string;
+  /** Span id the line was emitted under, when present. */
+  spanId?: string;
+  /** Trace id the line belongs to, when present. */
+  traceId?: string;
+  /** Epoch-millis the line was emitted. */
+  ts: number;
+  /** Acting user id, when present. */
+  userId?: string;
 }
-interface FanOutResult<T = unknown> {
-  /** Merged value — type depends on the merge strategy. */
-  data: T;
-  errors: ReadonlyArray<ShardError>;
-  /** Shards that failed or timed out. */
-  failed: number;
-  /** Shards that returned successfully. */
-  ok: number;
+/** One page of {@link PipelineLogRow}s, newest first, plus the cursor for the next page (absent means last page). */
+interface PipelineLogPage {
+  /** The cursor to pass as {@link PipelineLogQuery} `cursor` for the following page; absent when this is the last page. */
+  nextCursor?: PipelineLogCursor;
+  /** The rows, ordered `ts DESC` (newest first). At most `limit` of them. */
+  rows: PipelineLogRow[];
 }
-interface QueryCoordinatorOptions {
+/** Options for {@link createPipelineLogReader}. */
+interface PipelineLogReaderOptions {
   /**
-   * Maximum number of shard RPCs to issue in parallel. Defaults to 16 —
-   * keeps the 30-second Worker CPU budget healthy when fanning out to
-   * dozens of shards and avoids stampeding the DO namespace.
+   * Override any physical column name that diverges from the default (identity)
+   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
    */
-  maxConcurrency?: number;
+  columnMap?: PipelineLogColumnMap;
   /**
-   * Hard per-shard timeout in milliseconds. Defaults to 5000; a slow
-   * shard surfaces in `errors[]` rather than stalling the aggregate.
+   * The Iceberg namespace the `table` lives in (R2 Data Catalog database).
+   * Combined as `namespace.table` in the `FROM` clause; omit when `table`
+   * already carries its namespace.
    */
-  perShardTimeoutMs?: number;
-  /** Required — drives which shards to fan out to. */
-  registry: ShardRegistry;
+  namespace?: string;
+  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
 }
-interface FanOutRequest {
-  args?: Record<string, unknown>;
-  fanOut: FanOutSpec;
-  functionPath: string;
-  /** Forwarded to each shard fetch (auth, cookies, bookmark). */
-  headers?: Record<string, string>;
+/** The reader surface: a single keyset-paginated {@link PipelineLogPage} query. */
+interface PipelineLogReader {
+  /** Run one filtered, keyset-paginated read and return a {@link PipelineLogPage}. */
+  query: (query?: PipelineLogQuery) => Promise<PipelineLogPage>;
 }
+/** The written-column contract exposed publicly: canonical field to default physical column name. */
+declare const DEFAULT_LOG_COLUMNS: Readonly<Record<PipelineLogField, string>>;
+/** Default page size when a query omits `limit`. */
+declare const DEFAULT_LOG_LIMIT: number;
 /**
- * Cross-shard migration request. Unlike {@link FanOutRequest} there is no merge
- * strategy — per-shard payloads are `MigrationRunResult`-shaped objects, not
- * rows, so {@link QueryCoordinator.orchestrateMigration} rolls them up with the
- * fixed semantics documented on {@link MigrationFanOutResult}.
+ * Build a durable-log reader over one R2 Data Catalog (Iceberg) table.
  *
- * `functionPath` is the admin RPC to invoke on each shard
- * (`__lunora_admin__:runMigration` or `:migrationStatus`); `headers` must carry
- * the `Authorization` bearer header the shard's admin gate requires (the
- * configured admin token), or every shard comes back as a 403 error.
+ * The returned {@link PipelineLogReader} compiles each call to a safe
+ * `SELECT ... WHERE ... ORDER BY ts DESC LIMIT n` (over-fetching by one) and
+ * decodes the rows back to the canonical {@link PipelineLogRow} shape. All value
+ * filters are escaped through `@lunora/bindings/r2sql`'s `sql`/`lit`; column
+ * names come from `options.columnMap` (operator config), spliced with `raw`.
+ * @param client An {@link R2SqlClient} (`createR2Sql({ accountId, apiToken, bucket })`).
+ * @param options The target `table` (plus optional `namespace`) and any `columnMap` overrides.
  */
-interface MigrationFanOutRequest {
-  args?: Record<string, unknown>;
-  functionPath: string;
-  headers?: Record<string, string>;
-  /** Table whose live shard keys the migration runs across. */
+declare const createPipelineLogReader: (client: R2SqlClient, options: PipelineLogReaderOptions) => PipelineLogReader;
+/**
+ * Wire constants for the durable log archive, shared between the server route
+ * (`@lunora/runtime`'s `log-archive-admin-routes`) and the Studio Archive feed
+ * (`@lunora/studio`). Kept here — not in `@lunora/runtime` — because the studio
+ * is a browser bundle that must not import a runtime *value* (which would drag
+ * the DO/R2-SQL runtime into the browser). This file is dependency-free and
+ * bundler-inlined into each consumer, so both sides share one source of truth
+ * with no dependency edge.
+ */
+/**
+ * The error `code` the archive route returns (400) when the operator has wired
+ * no archive table (`logArchive`) or the `R2_SQL_*` credentials are missing. The
+ * Studio keys its "not configured" empty state off this exact value.
+ */
+declare const LOG_ARCHIVE_NOT_CONFIGURED = "LOG_ARCHIVE_NOT_CONFIGURED";
+/** The route the studio's `queryLogArchive` client method POSTs to. */
+declare const LOG_ARCHIVE_PATH = "/_lunora/admin/logs/archive";
+/**
+ * The app-level archive config the worker passes through: which Data Catalog
+ * table the Pipeline writes log records to (the read-side of `pipelineLogSink`),
+ * plus optional namespace / physical-column overrides. The R2 SQL *credentials*
+ * are NOT here — they live on `env` (`R2_SQL_*`), read per request.
+ */
+interface LogArchiveConfig {
+  /** Override any physical column name that diverges from the {@link createPipelineLogReader} default mapping. */
+  columnMap?: PipelineLogColumnMap;
+  /** The Iceberg namespace (R2 Data Catalog database) the table lives in; omit when `table` already carries it. */
+  namespace?: string;
+  /** The Iceberg table the Pipeline writes log records to (e.g. `"logs"`). */
   table: string;
 }
-/** One shard's outcome: either the unwrapped admin `result` payload, or an error. */
-interface ShardMigrationOutcome {
-  error?: {
-    message: string;
-    timedOut: boolean;
-  };
-  /** The shard's admin `result`, peeled out of the `{ result }` envelope. */
-  result?: unknown;
-  shardKey: string;
-}
-interface MigrationFanOutResult {
-  /** Summed `changed` across shards whose result carried a numeric count. */
-  changed: number;
-  /** Shards that errored or timed out. */
-  failed: number;
-  /** Shards that returned a 2xx result. */
-  ok: number;
-  /** Summed `processed` across shards whose result carried a numeric count. */
-  processed: number;
-  /** Per-shard outcomes, in registry order. */
-  shards: ReadonlyArray<ShardMigrationOutcome>;
-  /**
-   * Rolled-up status. `"failed"` if any shard's runner reported failure;
-   * `"in_progress"` if any shard is incomplete or unreachable (the run stays
-   * resumable); `"completed"` only when every shard finished cleanly.
-   */
-  status: "completed" | "failed" | "in_progress";
-}
 /**
- * Cross-shard rank request. Like {@link MigrationFanOutRequest} there is no
- * caller-supplied merge — per-shard payloads are `{before, total}` objects, so
- * {@link QueryCoordinator.orchestrateRank} rolls them up with the fixed
- * `{position: Σbefore + 1, total: Σtotal}` semantics {@link mergeRank} defines.
+ * Build the {@link LogArchiveConfig} from `env` for the generated worker entry —
+ * the zero-config seam the codegen `createWorker({ logArchive })` wiring uses,
+ * mirroring how the R2 SQL *credentials* already come from `env` (`R2_SQL_*`).
  *
- * The key tuple (`partitionKey`/`sortValues`/`rowId`) is built off the row doc
- * via `@lunora/do`'s `rankKeyFromDoc(index, doc)` and forwarded verbatim to
- * each shard's `__lunora_admin__:rankBefore` admin RPC; `headers` must carry
- * the admin bearer the shard's admin gate requires.
+ * Returns `undefined` unless `LUNORA_LOG_ARCHIVE_TABLE` is set, so the studio
+ * Archive feed stays "not configured" until the operator opts in by naming the
+ * Data Catalog table (+ optional `LUNORA_LOG_ARCHIVE_NAMESPACE`). `columnMap`
+ * overrides aren't env-expressible — a hand-written worker passes `logArchive`
+ * to `createWorker` directly for those.
  */
-interface RankFanOutRequest {
-  headers?: Record<string, string>;
-  /** Rank index name on `table`. */
-  index: string;
-  /** Canonical-JSON partition tuple — `encodePartitionKey(index.partitionBy, doc)`. */
-  partitionKey: string;
-  /** The `__id__` tiebreak value — `doc._id`. */
-  rowId: string;
-  /** Serialized sort-key values in `index.sortBy` order, as produced by `rankKeyFromDoc` (wire-safe + byte-matching the stored columns). */
-  sortValues: ReadonlyArray<unknown>;
-  /** Table whose live shard keys the rank fans out across. */
-  table: string;
-}
-interface RankFanOutResult {
-  /** Shards that errored or timed out. */
-  failed: number;
-  /** Shards that returned a 2xx `{before, total}`. */
-  ok: number;
-  /** `true` when at least one shard failed/timed out, so `position`/`total` are under-counts (failed shards' rows missing). A caller needing an exact global rank should treat this as an error, not trust the numbers. */
-  partial: boolean;
-  /** 1-based global position within the partition (`Σbefore + 1`). */
-  position: number;
-  /** Per-shard outcomes, in registry order. */
-  shards: ReadonlyArray<ShardRankOutcome>;
-  /** Global partition total (`Σtotal`). */
-  total: number;
-}
-/** One shard's rank outcome: its `{before, total}` payload, or an error. */
-interface ShardRankOutcome {
-  error?: {
-    message: string;
-    timedOut: boolean;
-  };
-  result?: {
-    before: number;
-    total: number;
-  };
-  shardKey: string;
-}
+declare const resolveLogArchiveFromEnv: (environment: unknown) => LogArchiveConfig | undefined;
+/**
+ * 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";
 /**
- * Cross-shard ranked-pagination request. Like {@link RankFanOutRequest} there's
- * no caller-supplied merge — the merge is the fixed k-way merge by the rank-key
- * tuple. `take` is the global page size; `cursor` is the opaque composite cursor
- * from the prior page's `continueCursor` (absent → first page). `partitionKey`,
- * when set, pins a single partition (`encodePartitionKey(index.partitionBy, where)`),
- * forwarded so each shard scopes its local slice to that partition.
+ * One measurement recorded from a function handler.
  *
- * `directions` is the per-sort-key direction list (`index.sortBy[i].direction`)
- * the coordinator's comparator needs to break ties the same way each shard's
- * `ORDER BY` does. `partitionKey` and the `__id__` tiebreak are always ascending
- * (matching the shard companion's btree), so only the sort columns vary.
+ * 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 RankPageFanOutRequest {
-  /** Opaque composite cursor from the prior page's `continueCursor`. */
-  cursor?: null | string;
-  /** Per-sort-key directions, in `index.sortBy` order. Missing/short → ascending. */
-  directions?: ReadonlyArray<RankDirection>;
-  headers?: Record<string, string>;
-  /** Rank index name on `table`. */
-  index: string;
-  /** Optional partition pin forwarded to each shard's local `rankPage`. */
-  partitionKey?: string;
-  /** Table whose live shard keys the page fans out across. */
-  table: string;
-  /** Global page size; defaults to 100, capped at 1000 (matching the shard-local `rankPage`). */
-  take?: number;
+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 shard's `rankPage` outcome: its local ranked slice, or an error. */
-interface ShardRankPageOutcome {
-  /** The directions the shard ordered by (`index.sortBy[i].direction`); authoritative for the merge. */
-  directions?: ReadonlyArray<RankDirection>;
+interface SpanEvent {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * Populated when the span body threw. `type` is the error's constructor name
+   * (or its `LunoraError` code); `message` is the human-readable string and may
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
   error?: {
     message: string;
-    timedOut: boolean;
+    type: string;
   };
-  hasMore?: boolean;
-  rows?: ReadonlyArray<RankPageRow>;
-  shardKey: string;
-}
-interface RankPageFanOutResult {
-  /** Opaque composite cursor for the next page, or `null` when the merge is exhausted. */
-  continueCursor: null | string;
-  /** Shards that errored or timed out. */
-  failed: number;
-  /** `true` when the global merge has no further rows. */
-  isDone: boolean;
-  /** Shards that returned a 2xx slice. */
-  ok: number;
-  /** The globally-ranked page of hydrated docs, in cross-shard rank order. */
-  page: ReadonlyArray<Record<string, unknown>>;
-  /** `true` when at least one shard failed/timed out, so the page may be missing that shard's rows. */
-  partial: boolean;
-  /** Per-shard outcomes, in registry order. */
-  shards: ReadonlyArray<ShardRankPageOutcome>;
-}
-interface QueryCoordinator {
-  fanOut: <T = unknown>(namespace: ShardNamespaceLike, request: FanOutRequest) => Promise<FanOutResult<T>>;
   /**
-   * Fan the `__lunora_admin__:applyCdc` admin RPC out by forwarding each
-   * pre-bucketed per-shard batch of CDC changes, rolling up the applied/failed
-   * counts. The replay half of point-in-time recovery.
+   * 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.
    */
-  orchestrateApplyCdc: (namespace: ShardNamespaceLike, request: ApplyCdcFanOutRequest) => Promise<ApplyCdcFanOutResult>;
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
   /**
-   * Fan the `__lunora_admin__:cdcSync` admin RPC out to every live shard,
-   * each resumed from its own cursor in `request.cursors` (shardKey → seq).
-   * Returns the per-shard change pages plus their new cursors so the caller
-   * can checkpoint each shard independently — the streaming-export feed.
+   * 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".
    */
-  orchestrateCdcSync: (namespace: ShardNamespaceLike, request: CdcSyncFanOutRequest) => Promise<CdcSyncFanOutResult>;
+  parentSpanId: string;
   /**
-   * Fan an export admin RPC out to every live shard, returning the
-   * per-shard `{rows}` payloads alongside any per-shard errors. Each shard
-   * returns a JSON envelope (not a streaming body) so this method is the
-   * collector — the worker assembles the NDJSON stream.
+   * 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.
    */
-  orchestrateExport: (namespace: ShardNamespaceLike, request: ExportFanOutRequest) => Promise<ExportFanOutResult>;
+  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;
+}
+/**
+ * Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
+ * fan-outs set `fanOut` with the table being aggregated, shard count, and
+ * per-shard failure count.
+ */
+interface ObservabilityEvent {
+  /** Wall-clock duration of the dispatch, in milliseconds. */
+  durationMs: number;
   /**
-   * Fan an import admin RPC out by routing each row to its owning shard. The
-   * shard registry resolves which shards exist; rows whose table has a
-   * `shardBy(field)` are bucketed using that field's value as the shard key,
-   * other tables fall back to the runtime's default `__root__` shard.
+   * Populated on `ok === false`. `code`/`status` mirror the LunoraError
+   * taxonomy; `message` is the human-readable string (may include user
+   * input — sinks that ship to third parties should scrub it).
    */
-  orchestrateImport: (namespace: ShardNamespaceLike, request: ImportFanOutRequest) => Promise<ImportFanOutResult>;
-  /** Fan a migration admin RPC out to every live shard of a table and roll up the per-shard outcomes. */
-  orchestrateMigration: (namespace: ShardNamespaceLike, request: MigrationFanOutRequest) => Promise<MigrationFanOutResult>;
+  error?: {
+    code: string;
+    message: string;
+    status: number;
+  };
   /**
-   * Fan the `__lunora_admin__:rankBefore` admin RPC out to every live shard of
-   * a table and roll up the per-shard `{before, total}` payloads into the
-   * global rank (`{position: Σbefore + 1, total: Σtotal}`). The cross-shard
-   * `rank()` path for a partition that spans shards.
+   * Populated for fan-out dispatches.
+   * `shards` is the total fan-out cardinality; `failed` counts shards that
+   * timed out or returned an error (the same `errors[]` the response body
+   * carries to the caller).
    */
-  orchestrateRank: (namespace: ShardNamespaceLike, request: RankFanOutRequest) => Promise<RankFanOutResult>;
+  fanOut?: {
+    failed: number;
+    shards: number;
+    table: string;
+  };
+  /** Function path being invoked, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Host of the inbound request (e.g. `"api.example.com"`). */
+  host?: string;
+  /** HTTP method of the inbound request (e.g. `"POST"`). */
+  method?: string;
+  /** True when the dispatch completed without throwing. */
+  ok: boolean;
   /**
-   * Page a ranked query across every live shard of a `.shardBy(...)` table.
-   * Fans `__lunora_admin__:rankPage` out to each shard, gathers each shard's
-   * local ranked slice (rows tagged with their rank-key tuple), and k-way
-   * merges them by that tuple into one globally-ranked page of `take` rows.
-   * The opaque `continueCursor` is a composite of per-shard cursors so the
-   * next page resumes each shard strictly-after the last row the global page
-   * consumed from it — pages never drop or duplicate a row at a shard
-   * boundary. The cross-shard `rankPage()` path (PLAN5 §7.1 / PLAN2 #3).
+   * Span id of the upstream caller extracted from the inbound `traceparent`,
+   * when present. This becomes the OTLP `parentSpanId` for the dispatch span so
+   * collector waterfalls show the worker span nested under the upstream caller.
+   */
+  parentSpanId?: string;
+  /** URL path of the inbound request (e.g. `"/_lunora/rpc"`). */
+  path?: string;
+  /** Port of the inbound request, when available. */
+  port?: number;
+  /** URL scheme of the inbound request (e.g. `"https"`). */
+  scheme?: string;
+  /** Shard key for single-shard calls; absent for fan-outs. */
+  shardKey?: string;
+  /**
+   * W3C trace context for this dispatch, generated once at dispatch entry (32-
+   * and 16-hex). A sink (e.g. `otlpSink`) reuses these for the dispatch's span
+   * instead of minting fresh ids, and the runtime propagates them to the shard
+   * as a `traceparent` so a container the handler calls can stitch its spans
+   * under the same trace. Absent on paths that don't originate a trace (a sink
+   * falls back to random ids).
    */
-  orchestrateRankPage: (namespace: ShardNamespaceLike, request: RankPageFanOutRequest) => Promise<RankPageFanOutResult>;
+  spanId?: string;
   /**
-   * Fan the `__lunora_admin__:getMetrics` admin RPC out to every live shard of
-   * a table and collect each shard's lifetime `requests` total into a per-shard
-   * `{ shardKey, requests }` distribution. The feed the studio's `hot_shard`
-   * advisor lint needs: a single shard's snapshot can't reveal cross-shard
-   * skew, so this fans the cheap metrics read out and returns the whole shard
-   * set's request volumes (a failed shard surfaces as `requests: 0`).
+   * W3C trace flags for this dispatch (the sampled flag, bit 0). Carried from
+   * the upstream `traceparent` or set by the runtime's head-sampling decision.
    */
-  orchestrateShardTraffic: (namespace: ShardNamespaceLike, request: ShardTrafficFanOutRequest) => Promise<ShardTrafficFanOutResult>;
-  readonly registry: ShardRegistry;
+  traceFlags?: number;
+  traceId?: string;
+  /** Inbound `User-Agent` header, when available. */
+  userAgent?: string;
 }
 /**
- * Cross-shard export request. `tables` is the union of every table the caller
- * wants exported (shard-local **or** global); `headers` carries the admin
- * bearer the per-shard gate expects. Shard registries are queried for the
- * complete set of live shards across all listed shard-local tables.
+ * The `ctx.log` observability contract lives in `shared/` (inlined into each
+ * `dist`) so the DO that builds the events and the runtime sink that consumes
+ * them agree by construction rather than by hand-mirrored duplication. Re-exported
+ * here under the runtime's historical names.
+ *
+ * `LogLevel` is the canonical `ctx.log` severity union (the five console tiers
+ * plus `trace`/`fatal`); `ObservabilitySinkContext` is the shared per-event sink
+ * context (a `waitUntil` to keep a background send alive past the response).
  */
-interface ExportFanOutRequest {
-  args?: Record<string, unknown>;
-  headers?: Record<string, string>;
+type LogLevel = ContextLogLevel;
+type ObservabilitySinkContext = LogSinkContext;
+/**
+ * The hook contract. Methods are optional so a sink can opt into only the
+ * events it cares about; the runtime no-ops the others.
+ */
+interface ObservabilitySink {
+  /**
+   * **Opt-in, EXPERIMENTAL, default `false`.** When `true`, each `ctx.trace`
+   * span the Durable Object records is ALSO emitted as a Cloudflare **custom
+   * span** (`tracing.enterSpan` from `cloudflare:workers`, GA 2026-06-16) so it
+   * nests inside CF's native binding/fetch/handler trace tree on the hosted
+   * path — a deeper waterfall in Cloudflare's own trace viewer.
+   *
+   * Capability-probed: a safe no-op off-Cloudflare, on a compat date predating
+   * custom spans, or when the trace is unsampled. This ONLY ADDS a CF-side span;
+   * it never replaces {@link ObservabilitySink.onSpan}, which stays the source
+   * of truth and drives the local studio waterfall.
+   *
+   * **Workerd-validated (partial).** The `tracing.enterSpan` bridge is confirmed
+   * available and side-effect-free inside a real Durable Object under
+   * `@cloudflare/vitest-pool-workers` — the body runs without throwing,
+   * `span.isTraced` is a real boolean, and `onSpan`'s recorded tree is byte-for-byte
+   * identical with the flag on vs off. Still EXPERIMENTAL because the harness is
+   * unsampled (`isTraced === false`), so CF's own EXPORTED parent-linking of the
+   * custom span under the DO's ambient span is not yet observable there.
+   *
+   * **Double-export caveat.** Leave this off unless you understand the trade:
+   * with it on, a deployment that also ships `onSpan` to a collector via
+   * `otlpSink` AND lets Cloudflare export its trace tree will emit the same
+   * logical span down two pipelines. Enable it only when you want the CF-native
+   * nesting and have accounted for that overlap.
+   *
+   * Pass this on the SAME sink object you give both `createWorker` and
+   * `createShardDO` — the DO reads the flag when building `ctx.trace`.
+   */
+  fuseCloudflareTraces?: boolean;
+  /** Invoked once per `ctx.log.*` call from a function handler. */
+  onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
+   * upstream, so counter values are deltas for the destination to sum.
+   */
+  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
+  /** Invoked once per dispatched RPC (single-shard or fan-out). */
+  onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
   /**
-   * Tables driving the fan-out. Shards are derived from the union of each
-   * table's live shard keys — so an export of `["users","messages"]` reaches
-   * every shard that holds either table. Globals are skipped here; the
-   * worker reads them from D1 directly.
+   * Invoked once per `ctx.trace(name, fn)` span, when the span body settles.
+   * Distinct from `onRpc`: that is the one SERVER span per dispatch, this is the
+   * INTERNAL spans a handler creates beneath it.
    */
-  tables: ReadonlyArray<string>;
-}
-/** Per-shard export outcome. */
-interface ShardExportOutcome {
-  error?: {
-    message: string;
-    timedOut: boolean;
-  };
-  /** Rows from this shard, or undefined when an error occurred. */
-  rows?: ReadonlyArray<{
-    doc: Record<string, unknown>;
-    table: string;
-  }>;
-  shardKey: string;
-}
-interface ExportFanOutResult {
-  failed: number;
-  ok: number;
-  shards: ReadonlyArray<ShardExportOutcome>;
+  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
 }
 /**
- * Cross-shard change-data-capture request. `tables` drives shard discovery (the
- * union of their live shard keys, like export); `cursors` maps each shard key
- * to the `seq` it was last read through (absent → from the beginning). `limit`
- * caps each shard's page.
+ * Invoke `sink.onRpc` with the given event, swallowing any error the sink
+ * throws. Use at the dispatch boundary; the runtime should never see a
+ * sink-originating throw bubble up past this point. `context.waitUntil`, when
+ * supplied, lets a network sink keep its send alive past the response.
+ *
+ * `sampling` applies the trace-sampling verdict to this dispatch's SERVER span:
+ * the event is dropped unless the trace was head-sampled or (with errors
+ * force-kept) this dispatch errored — the tail bias. A dispatch with no
+ * `traceId` (a fan-out aggregation, which mints none) is always kept, and an
+ * absent `sampling` keeps everything, so both are backward-compatible.
  */
-interface CdcSyncFanOutRequest {
-  cursors?: Record<string, number>;
-  headers?: Record<string, string>;
-  limit?: number;
-  tables: ReadonlyArray<string>;
-}
-/** Per-shard CDC page: the changes plus the new cursor to resume this shard from. */
-interface ShardCdcOutcome {
-  changes?: ReadonlyArray<Record<string, unknown>>;
-  /** New per-shard cursor; on error it echoes the shard's prior cursor so a retry resumes cleanly. */
-  cursor: number;
-  error?: {
-    message: string;
-    timedOut: boolean;
-  };
-  shardKey: string;
-}
-interface CdcSyncFanOutResult {
-  failed: number;
-  ok: number;
-  shards: ReadonlyArray<ShardCdcOutcome>;
-}
+declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: ObservabilityEvent, context?: ObservabilitySinkContext, sampling?: TraceSamplingConfig) => void;
 /**
- * Cross-shard import request. Rows have already been bucketed by the runtime
- * into one batch per shard key — the coordinator's job is to forward each
- * batch and roll up the per-shard insert counts + errors.
+ * Invoke `sink.onLog` with the given log event, swallowing any error the sink
+ * throws. The same failure model as {@link emitRpcEvent}: a buggy log sink must
+ * never break the handler that emitted the line.
  */
-interface ImportFanOutRequest {
-  /**
-   * Per-shard batches keyed by shard key. Each entry will be POSTed as the
-   * `rows` arg of `__lunora_admin__:importShard`. The shard's
-   * starting-line-number for error attribution is carried in `startLine`.
-   */
-  batches: ReadonlyArray<{
-    rows: ReadonlyArray<{
-      doc: Record<string, unknown>;
-      table: string;
-    }>;
-    shardKey: string;
-    startLine?: number;
-  }>;
-  headers?: Record<string, string>;
+declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
+/** Procedure kinds that can be exposed over REST (`stream` cannot — it is a WebSocket surface). */
+type RestFunctionKind = "action" | "mutation" | "query";
+/**
+ * The `.expose({ rest: true })` tag stamped onto a registered procedure (runtime,
+ * as `fn.expose`) or discovered from its builder chain (codegen, onto the
+ * `FunctionIR`). Presence of `rest === true` is the ONLY thing that opts a
+ * procedure into the surface — everything is default-closed.
+ */
+interface RestExposure {
+  rest?: boolean;
 }
-interface ShardImportOutcome {
-  error?: {
-    message: string;
-    timedOut: boolean;
-  };
-  result?: {
-    conflicts: number;
-    errors: ReadonlyArray<{
-      code: string;
-      line: number;
-      message: string;
-      table: string;
-    }>;
-    inserted: Record<string, number>;
-  };
-  shardKey: string;
+/** One resolved REST endpoint: the transport method + URL path a procedure is reachable at. */
+interface RestSurfaceEntry {
+  functionPath: string;
+  kind: RestFunctionKind;
+  method: "GET" | "POST";
+  name: string;
+  namespace: string;
+  path: string;
 }
-interface ImportFanOutResult {
-  /** Total conflicts (skipped `_id`s) across shards. */
-  conflicts: number;
-  /** Errors merged across all per-shard outcomes. */
-  errors: ReadonlyArray<{
-    code: string;
-    line: number;
-    message: string;
-    table: string;
-  }>;
-  failed: number;
-  /** Per-table summed insert counts. */
-  inserted: Record<string, number>;
-  ok: number;
-  shards: ReadonlyArray<ShardImportOutcome>;
+/**
+ * Resolve the full REST surface from a list of procedures, filtering to the ones
+ * opted in via `.expose({ rest: true })`. The single source of truth both the
+ * runtime router and the OpenAPI emitter derive from — a `stream` procedure or a
+ * malformed path is skipped. Ordered by path for stable enumeration.
+ */
+declare const describeRestSurface: (procedures: ReadonlyArray<{
+  exposure?: RestExposure;
+  functionPath: string;
+  kind: "action" | "mutation" | "query" | "stream";
+}>) => RestSurfaceEntry[];
+/** The bits of a registered function the REST router reads: its kind and its `.expose` tag. */
+interface RestRegistryEntry {
+  expose?: RestExposure;
+  kind: "action" | "mutation" | "query" | "stream";
 }
+/** Registry map (structurally the generated `LUNORA_FUNCTIONS`, narrowed to what REST needs). */
+type RestRegistryLike = Record<string, RestRegistryEntry>;
+/** Dispatch one exposed procedure through the shared RPC path (auth + RLS + validators enforced at the shard). Returns the shard `Response`. */
+type RestInvoke = (parameters: {
+  args: Record<string, unknown>;
+  env: unknown;
+  functionPath: string;
+  request: Request;
+  shardKey?: string;
+  /** The request's `waitUntil`, so dispatch telemetry survives isolate teardown. */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}) => Promise<Response>;
 /**
- * Cross-shard CDC replay request (point-in-time recovery). Changes are
- * pre-bucketed by the runtime into one batch per shard key — the coordinator
- * forwards each batch to `__lunora_admin__:applyCdc` and rolls up the counts.
+ * Optional per-request rate-limit gate for the public surface. Returns a `429`
+ * `Response` when the request is limited (the router returns it verbatim), or
+ * `undefined` to let the call through. Built in `create-worker` over
+ * `@lunora/ratelimit`.
  */
-interface ApplyCdcFanOutRequest {
-  batches: ReadonlyArray<{
-    changes: ReadonlyArray<Record<string, unknown>>;
-    shardKey: string;
+type RestRateLimit = (request: Request, functionPath: string) => Promise<Response | undefined> | Response | undefined;
+/**
+ * A built REST route. Takes the same `(request, env, url, context)` shape as the
+ * runtime's internal route table so it can be spread straight into it; `url` is
+ * unused here (the route re-parses it) and `context` is read only for its
+ * `waitUntil`, which keeps dispatch telemetry alive past the response.
+ */
+type RestRoute = (request: Request, env: unknown, url?: URL, context?: {
+  waitUntil?: (promise: Promise<unknown>) => void;
+}) => Promise<Response>;
+interface RestRouteDeps {
+  /** The generated function registry — the source of which procedures are exposed. */
+  functions: RestRegistryLike;
+  /** The shared RPC dispatch (bound in `create-worker`). */
+  invoke: RestInvoke;
+  /** Optional rate-limit gate for the public surface. */
+  rateLimit?: RestRateLimit;
+  /** JSON body reader with the shared size cap. */
+  readJsonBody: (request: Request) => Promise<Record<string, unknown>>;
+}
+/**
+ * The resolved REST surface for a registry — the ordered list of exposed
+ * `{ functionPath, method, path, kind }`. Exported so a contract test can assert
+ * the runtime surface equals the published OpenAPI (both derive from the same
+ * `shared/rest-surface` helper).
+ */
+declare const restSurfaceFromRegistry: (functions: RestRegistryLike) => ReturnType<typeof describeRestSurface>;
+/** Read `shardKey` from `?shardKey=` or the `x-lunora-shard-key` header; `undefined` routes to the default shard. */
+declare const readShardKey: (url: URL, request: Request) => string | undefined;
+/**
+ * Decode GET args from the query string. Each value is parsed as JSON when it
+ * looks like a JSON scalar/array/object (so `?limit=10` → number, `?ids=[1,2]` →
+ * array), else kept as a string. `shardKey` is reserved for routing and excluded.
+ */
+declare const argsFromQuery: (url: URL) => Record<string, unknown>;
+/**
+ * Build the REST route map merged into the worker's internal route table. One
+ * exact-path entry per exposed procedure — so the surface is closed by
+ * construction. A `query` handler accepts `GET` (args from the query string) and
+ * `POST` (args from a JSON body); a `mutation` / `action` accepts `POST` only.
+ */
+declare const buildRestRoutes: (deps: RestRouteDeps) => Record<string, RestRoute>;
+/** Structural view of a `@lunora/ratelimit` `RateLimiter` — only the `.limit()` call, so the runtime needs no hard dependency. */
+interface RateLimiterLike {
+  limit: (name: string, args?: {
+    key?: string;
+  }) => Promise<{
+    ok: boolean;
+    retryAfter: number;
   }>;
-  headers?: Record<string, string>;
-}
-interface ApplyCdcFanOutResult {
-  /** Total changes applied across shards. */
-  applied: number;
-  failed: number;
-  ok: number;
 }
 /**
- * Cross-shard traffic request. Like {@link MigrationFanOutRequest} there is no
- * caller-supplied merge — each shard's `__lunora_admin__:getMetrics` payload
- * carries its own lifetime `requests` total, and {@link rollUpShardTraffic}
- * collects them into one `{ shardKey, requests }` entry per shard. `headers`
- * must carry the admin bearer the per-shard `getMetrics` gate requires.
- *
- * `table` drives shard discovery: the registry's live shard keys for the table
- * are the shards fanned out to. This is the feed the studio's `hot_shard`
- * runtime advisor consumes to compute cross-shard skew — a single shard's
- * snapshot can't, so the panel fans this out on demand.
+ * Adapt a `@lunora/ratelimit` limiter into a {@link RestRateLimit} gate for the
+ * public REST surface (plan 167). Pass the limiter and the rate name to charge;
+ * `key` isolates the limit per caller (IP / user / API key — defaults to the
+ * `cf-connecting-ip` header, else a shared bucket). A denied request becomes a
+ * `429` with a `Retry-After` header (seconds, ceil of the limiter's ms). The
+ * runtime imports nothing from `@lunora/ratelimit` — build the limiter in the
+ * worker entry and pass it here.
  */
-interface ShardTrafficFanOutRequest {
-  headers?: Record<string, string>;
-  /** Table whose live shard keys the traffic fan-out runs across. */
-  table: string;
-}
-/** One shard's traffic total, mirroring the advisor's `AdvisorShardTraffic` (sans the optional `group`). */
-interface ShardTrafficEntry {
-  /** Lifetime request count read off the shard's `getMetrics` snapshot; `0` for a shard that failed/timed out. */
-  requests: number;
-  /** The shard key (the DO id name); `""` for the unnamed root shard. */
-  shardKey: string;
-}
-interface ShardTrafficFanOutResult {
-  /** Shards that errored or timed out (their `requests` are reported as `0`). */
-  failed: number;
-  /** Shards that returned a 2xx `getMetrics` snapshot. */
-  ok: number;
-  /**
-   * Per-shard request totals, in registry order. Shaped to plug straight into
-   * the advisor's `LintContext.shardTraffic` so the `hot_shard` lint can
-   * compute the cross-shard share. A failed shard still appears (with
-   * `requests: 0`) so callers see the full shard set.
-   */
-  shards: ReadonlyArray<ShardTrafficEntry>;
-}
-declare const createQueryCoordinator: (options: QueryCoordinatorOptions) => QueryCoordinator;
+declare const createRestRateLimit: (limiter: RateLimiterLike, options: {
+  key?: (request: Request, functionPath: string) => string | undefined;
+  name: string;
+}) => RestRateLimit;
 /** Per-header overrides for {@link SecurityHeadersOptions}. `false` omits the header. */
 interface SecurityHeadersOptions {
   /**
@@ -1756,6 +2286,68 @@ declare const handleCorsPreflight: (request: Request, resolved: ResolvedSecurity
  * hibernation handshake.
  */
 declare const decorateResponse: (response: Response, request: Request, resolved: ResolvedSecurity) => Response;
+/**
+ * Who is allowed to hand this worker a trace to join.
+ *
+ * Continuing an inbound W3C `traceparent` is what makes a distributed waterfall
+ * stitch end to end, but the header is caller-supplied: on a public worker,
+ * trusting it lets anyone choose which trace their spans and `ctx.log` lines land
+ * in, and — because `shared/sampling` derives the head verdict from the trace id —
+ * choose their own sampling outcome. Whether that matters is a *deployment*
+ * question ("can an untrusted client reach this worker directly?"), which no
+ * amount of request inspection can answer on its own.
+ *
+ * So rather than ask users to hand-roll a security predicate, this module ships
+ * the answers that are actually sound, named:
+ *
+ * ```ts
+ * createWorker({ trustInboundTraceContext: true });            // nothing untrusted can reach this worker
+ * createWorker({ trustInboundTraceContext: "mtls" });          // only edge-verified client certs
+ * createWorker({ trustInboundTraceContext: (request) => … });  // anything else
+ * ```
+ *
+ * **Behind a gateway, mesh, or Cloudflare Access, `true` is the answer.** If the
+ * worker is genuinely unreachable except through that front door, every caller
+ * has already passed it and there is nothing left to discriminate on. Check that
+ * it really is unreachable — a `*.workers.dev` route left enabled, or a hostname
+ * outside the Access policy, is a second front door with no gate on it.
+ *
+ * There is deliberately no `"cloudflare-access"` signal. Recognising Access by its
+ * `cf-access-jwt-assertion` header only tests that a header is present, which is
+ * redundant when the worker is properly fronted (`true` already covers it) and
+ * forgeable in one `curl` when it is not. Verifying the assertion for real means a
+ * JWKS fetch and an audience check — `@lunora/cloudflare-access` does exactly
+ * that, and it is async, so it belongs in `resolveIdentity` rather than on the
+ * dispatch path. Pass a predicate if you want to wire it in yourself.
+ *
+ * Everything resolves to one predicate at worker construction, so the per-request
+ * cost is a single call.
+ *
+ * The custom form receives only the `Request`, deliberately: handing user code the
+ * Worker `env` would put every secret binding behind a telemetry callback, the
+ * same boundary `LogSinkContext` was just narrowed to avoid. A predicate that
+ * needs to compare against a binding should close over it — build the worker per
+ * request from an options factory, the pattern `createLunoraHandler` already uses.
+ */
+/**
+ * A named trust signal — a per-request property that, on its own, establishes the
+ * caller is one whose trace context may be adopted.
+ *
+ * - `"mtls"` — the caller presented a client certificate that **Cloudflare
+ * verified at the edge**. `cf.tlsClientAuth` is platform-injected request
+ * metadata, not a header, so a caller cannot write it: the check carries its own
+ * proof and holds regardless of how the worker is exposed.
+ *
+ * Signals live here only when they meet that bar. A property a client can set for
+ * itself is not a signal; see the module doc on why Cloudflare Access is absent.
+ */
+type TraceTrustSignal = "mtls";
+/**
+ * How much of the inbound trace context to trust. `false` (the default) ignores
+ * it entirely; `true` trusts every caller, which is right when nothing untrusted
+ * can reach the worker.
+ */
+type TrustInboundTraceContext = boolean | TraceTrustSignal | ((request: Request) => boolean);
 /**
  * Wire-format RPC envelope. Posted to `POST /_lunora/rpc`.
  *
@@ -1917,6 +2509,17 @@ interface FunctionDescriptor {
 interface FunctionRegistryEntry {
   /** The function's `v.*` args validator map; read structurally for the signature view. */
   args?: unknown;
+  /**
+   * Opt-in public-surface tag set by the `.expose({ rest: true })` builder
+   * modifier (plan 167). Present only on procedures deliberately published over
+   * REST; the runtime builds a `/_lunora/rest/&lt;namespace>/&lt;fn>` route for each,
+   * routing THROUGH the procedure so auth/RLS/validators are enforced. Rides
+   * along on the registered function's identity (like `fn.x402` / `fn.rls`), so
+   * reading it needs no change to the generated registry shape.
+   */
+  expose?: {
+    readonly rest?: boolean;
+  };
   /**
    * The generated registry carries `"stream"` alongside query/mutation/action;
    * the discovery endpoint surfaces the latter three only (a `stream` function
@@ -2206,6 +2809,81 @@ interface BackupManifest {
   scheduledTime: number;
   tables?: string;
 }
+/**
+ * Health / readiness probe configuration (plan 177). Everything is optional; the
+ * runtime always registers its default binding probes, so the endpoints work
+ * with `health: {}` (or the field omitted). Nothing here is a secret — `appName`
+ * / `appVersion` are the only strings echoed in the body, and per-check messages
+ * are surfaced only under the `"admin"` posture.
+ */
+interface HealthOptions {
+  /** Application name surfaced in the health body. Defaults to `"lunora"`. */
+  appName?: string;
+  /** Application version surfaced in the health body. Defaults to `"0.0.0"`. */
+  appVersion?: string;
+  /**
+   * Auth posture. `"public"` (default) serves the probe unauthenticated with
+   * per-check messages redacted; `"admin"` requires a valid admin bearer and
+   * includes the (runtime-authored) messages.
+   */
+  auth?: "admin" | "public";
+  /** Cache the computed report for this many ms so a frequent poller does not re-run every probe. Defaults to `0`. */
+  cacheTtlMs?: number;
+  /** Skip the auto-registered D1 / R2 / queue / Hyperdrive binding probes (keep only the DO probe + `probes`). Defaults to `false`. */
+  disableBindingProbes?: boolean;
+  /** Extra bespoke probes appended to the auto-registered set (e.g. a downstream API reachability check). */
+  probes?: ReadonlyArray<HealthProbe>;
+}
+/**
+ * One registered device subscription as surfaced by the gated
+ * `__lunora_admin__:listPushSubscriptions` admin RPC (backing the Studio
+ * Notifications page). Structurally mirrors `@lunora/notify`'s
+ * `PushSubscriptionDevice` — the runtime carries NO `@lunora/notify` dependency,
+ * so the shape is declared here and matched by duck typing (the studio reuses the
+ * canonical `@lunora/notify` type). Delivery secrets (Web Push `keys`, FCM
+ * `token`) are never part of this shape.
+ */
+interface NotifySubscriptionDevice {
+  /** Unix-ms creation time. */
+  createdAt: number;
+  /** Web Push service endpoint URL (web-push only). */
+  endpoint?: string;
+  /** Stable identifier used as the store key. */
+  id: string;
+  /** The delivery channel this subscription targets (`"web-push"` / `"fcm"`). */
+  kind: string;
+  /** Last delivery error message, when `lastStatus` is `failed`/`expired`. */
+  lastError?: string;
+  /** Unix-ms time of the most recent register/send touch. */
+  lastSeenAt: number;
+  /** Last-known delivery outcome (`"ok"` / `"failed"` / `"expired"`). */
+  lastStatus?: string;
+  /** Arbitrary app metadata (device name, locale, topics, …). */
+  metadata?: Record<string, unknown>;
+  /** Owning user id, or `null`/absent when anonymous. */
+  userId?: null | string;
+}
+/**
+ * The minimal read surface the worker needs off an `@lunora/notify` subscription
+ * store to serve `__lunora_admin__:listPushSubscriptions`: just `list`. Codegen
+ * binds this from the app's `defineNotify({ store })` (`store(env)`), so the
+ * worker reads registered devices through the very store the handlers write to.
+ * Structural (not a `@lunora/notify` import) to keep the runtime dependency-free.
+ */
+interface NotifySubscriptionStoreLike {
+  /**
+   * List every stored subscription. Declared with NO parameter so a concrete
+   * `@lunora/notify` `SubscriptionStore` — whose `list(filter?)` narrows `kind`
+   * to the `"web-push" | "fcm"` union — assigns cleanly under
+   * `strictFunctionTypes` (an extra optional parameter on the source is fine).
+   * The RPC handler applies the `{ kind, userId }` filter in-memory, so no typed
+   * filter needs to cross this dependency-free structural boundary.
+   */
+  list: () => Promise<ReadonlyArray<NotifySubscriptionDevice & {
+    keys?: unknown;
+    token?: unknown;
+  }>>;
+}
 interface WorkerOptions {
   /**
    * An additional, async authorization gate for the `/_lunora/admin/*` plane
@@ -2265,6 +2943,17 @@ interface WorkerOptions {
    * every `/auth/*` endpoint responds `AUTH_NOT_CONFIGURED`.
    */
   authAdmin?: AuthAdmin;
+  /**
+   * The auth/security audit read plane backing the studio's "Security / audit"
+   * page (the `__lunora_admin__:getAuthAuditLog` admin RPC). The audit trail
+   * lives in the auth D1 database (via `@lunora/auth`'s `SqlExecutor`), not in a
+   * shard's DO SQLite, so — unlike the other `__lunora_admin__:*` ops — the RPC
+   * is served here at the worker, admin-gated, through this reader. Wire it with
+   * `@lunora/auth`'s `createAuthAuditReader(d1Executor(env.DB))`. Omit it and the
+   * RPC responds `AUTH_AUDIT_NOT_CONFIGURED`; a caller without a valid admin
+   * bearer always gets `ADMIN_FORBIDDEN` first (default-closed).
+   */
+  authAuditReader?: AuthAuditReader;
   /**
    * Base path the auth routes are mounted under (default `/api/auth`). Used
    * to classify which inbound paths are auth ATTEMPTS for the app-level
@@ -2377,11 +3066,27 @@ interface WorkerOptions {
   d1?: unknown;
   /** Default shard key used when an envelope omits one. */
   defaultShardKey?: string;
+  /**
+   * Durable per-shard cursor store for the continuous CDC export tap (plan 170),
+   * mirroring the CDC-in `__lunora_source_cursor` watermark. Build a KV-backed
+   * one with `createKvCursorStore(env.CDC_CURSORS)`. Required (alongside
+   * {@link WorkerOptions.exportSinks}) for the `POST /_lunora/admin/export-tap/run`
+   * drain route; absent → the route reports `EXPORT_TAP_NOT_CONFIGURED`.
+   */
+  exportCursorStore?: ExportCursorStore;
   /**
    * Stream `.global()` rows for the admin export endpoint. When omitted,
    * the export endpoint covers only shard-local tables.
    */
   exportGlobals?: GlobalExportFunction;
+  /**
+   * Named continuous-export sinks (plan 170) the CDC tap drains the op-log change
+   * feed to. Build with `webhookSink({...})`, `r2Sink({...})`, or a custom
+   * `defineExportSink({...})`. Paired with {@link WorkerOptions.exportCursorStore}
+   * to enable the `POST /_lunora/admin/export-tap/run` drain route (at-least-once,
+   * ordered per shard, resumable). Absent / empty → the route reports not-configured.
+   */
+  exportSinks?: Record<string, ExportSink>;
   /**
    * The generated `LUNORA_FUNCTIONS` map (from `_generated/functions.ts`). When
    * set, the worker exposes the admin-gated `GET /_lunora/admin/functions`
@@ -2398,6 +3103,17 @@ interface WorkerOptions {
    * respond `GLOBALS_NOT_CONFIGURED`.
    */
   globalIntrospector?: GlobalIntrospector;
+  /**
+   * Health / readiness probe configuration (plan 177). When present (or left as
+   * the default — probes are always registered), the worker serves
+   * `GET /_lunora/health` (aggregate; `503` when a critical dependency is down)
+   * and `GET /_lunora/health/ready` (readiness gate). The runtime auto-registers
+   * probes for the shard Durable Object (reachability, critical), any D1 binding
+   * (`SELECT 1`, critical), and R2 / queue / Hyperdrive bindings (presence,
+   * non-critical); `probes` adds bespoke checks. The body never leaks secrets —
+   * see {@link HealthOptions}.
+   */
+  health?: HealthOptions;
   /**
    * Router for HTTP actions (`httpRouter()` from `@lunora/server`, a hono app).
    * Consulted for requests that miss the explicit {@link WorkerOptions.routes}
@@ -2462,6 +3178,17 @@ interface WorkerOptions {
    * overrides). Absent → the Archive feed reports "not configured".
    */
   logArchive?: LogArchiveConfig;
+  /**
+   * The `@lunora/notify` device-subscription store, bound from the request
+   * `env` by codegen from the app's `lunora/notify.ts` `defineNotify({ store })`.
+   * Backs the gated `__lunora_admin__:listPushSubscriptions` admin RPC (the
+   * Studio Notifications page): the worker reads registered devices — endpoint /
+   * kind / last-send status / delivery errors — through the SAME store the
+   * handlers register into. Delivery secrets (Web Push keys, FCM token) are
+   * stripped before the devices leave the worker. Absent (no store configured)
+   * ⇒ the RPC returns an empty device list rather than erroring.
+   */
+  notifySubscriptionStore?: NotifySubscriptionStoreLike;
   /**
    * Optional telemetry sink. When supplied, the worker emits one
    * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
@@ -2553,6 +3280,16 @@ interface WorkerOptions {
    * bucket rows; when omitted, every row routes to the default shard.
    */
   resolveTableSharding?: AdminTableResolver;
+  /**
+   * Optional per-request rate-limit gate for the opt-in public REST surface
+   * (plan 167). Invoked with the inbound request + the target `functionPath`
+   * BEFORE the procedure is dispatched; return a `429` `Response` to reject
+   * (returned verbatim, `Retry-After` included) or `undefined` to allow. Build it
+   * over `@lunora/ratelimit` in the worker entry — the runtime stays free of a
+   * hard `@lunora/ratelimit` dependency. Only consulted for REST calls; typed RPC
+   * is unaffected.
+   */
+  restRateLimit?: RestRateLimit;
   /**
    * Map of routes for custom HTTP handlers (auth callbacks etc.). Keys can
    * be either `"METHOD path"` (e.g. `"GET /healthz"`) or just `"path"`
@@ -2560,6 +3297,25 @@ interface WorkerOptions {
    * first.
    */
   routes?: Record<string, Route>;
+  /**
+   * Trace-sampling policy for the observability pipeline, mirroring Cloudflare
+   * Workers' `head_sampling_rate`. Governs only trace spans (the per-dispatch
+   * SERVER span and the `ctx.trace` INTERNAL spans beneath it) — never metrics
+   * or `ctx.log` lines.
+   *
+   * The decision is deterministic per trace: a stable value derived from the
+   * `traceId` is compared to `headRate`, so the same trace is kept or dropped
+   * as a whole on the worker and on every shard/container it fans out to (no
+   * half traces). The head decision is propagated to shards via the
+   * `traceparent` sampled flag, so they drop the matching `ctx.trace` spans
+   * coherently.
+   *
+   * With `alwaysSampleErrors` (default `true`), a trace that produced an error
+   * span is kept whole regardless of the head decision — the tail bias, so
+   * failures are never sampled away even at an aggressive `headRate`. Omit the
+   * option (or leave `headRate` at its default `1`) to keep every trace.
+   */
+  sampling?: TraceSamplingConfig;
   /**
    * Namespace binding for the `SchedulerDO` (typically `env.SCHEDULER`). When
    * set, the worker exposes the admin-gated `/_lunora/admin/scheduled`
@@ -2627,6 +3383,39 @@ interface WorkerOptions {
    * endpoint. When omitted, the sync feed covers only shard-local tables.
    */
   syncGlobals?: GlobalCdcSyncFunction;
+  /**
+   * Who may hand this worker a trace to join. Controls whether an inbound W3C
+   * `traceparent` is continued — adopting its trace id, parenting this
+   * dispatch's span under the upstream span, and carrying its `tracestate` to
+   * the shard. **Default: off.**
+   *
+   * ```ts
+   * trustInboundTraceContext: true             // nothing untrusted can reach this worker
+   * trustInboundTraceContext: "mtls"           // only edge-verified client certificates
+   * trustInboundTraceContext: (request) => …   // anything else
+   * ```
+   *
+   * Off by default because the header is caller-supplied: on a worker an
+   * untrusted client can reach directly, trusting it lets anyone choose which
+   * trace their spans and `ctx.log` lines join — grafting entries into another
+   * tenant's waterfall in a shared collector — and, because the head-sampling
+   * verdict is derived from the trace id, choose their own sampling outcome.
+   * (Error traces are unaffected either way: the tail bias is evaluated from
+   * the worker's own decision, never the caller's.)
+   *
+   * Turn it on when something you control — a gateway, service mesh, or
+   * Cloudflare Access — sets `traceparent` itself; a proxy that only _forwards_
+   * the client's header is not such a thing. Behind a front door like that,
+   * `true` is the answer, because every caller has already passed it. Confirm
+   * the worker really is unreachable otherwise — a `*.workers.dev` route left
+   * enabled is a second front door with no gate on it.
+   *
+   * Leaving this unset logs a one-time hint if an inbound trace is actually
+   * dropped; setting it explicitly to `false` keeps the behaviour and silences
+   * that.
+   * @see {@link TrustInboundTraceContext} for what each signal proves.
+   */
+  trustInboundTraceContext?: TrustInboundTraceContext;
   /**
    * Read-only introspector for Vectorize indexes, backing the studio's vector
    * browser via `GET /_lunora/admin/vector/indexes` and
@@ -2711,9 +3500,12 @@ interface LunoraWorker {
    * @param options Call options mirroring the RPC envelope.
    * @param options.shardKey Routes to a specific shard (omitted → the worker's
    * `defaultShardKey`).
+   * @param options.waitUntil The host's `waitUntil`, so dispatch telemetry
+   * whose export is deferred (a gzipped OTLP body) survives isolate teardown.
    */
   serverQuery: (request: Request, env: unknown, reference: unknown, args?: Record<string, unknown>, options?: {
     shardKey?: string;
+    waitUntil?: (promise: Promise<unknown>) => void;
   }) => Promise<Response>;
 }
 /**
@@ -2962,6 +3754,15 @@ declare class LunoraError extends LunoraError$1 {
   });
   toResponse(): Response;
 }
+/** A JS attribute value the encoder maps onto an OTLP `AnyValue`. */
+type OtlpAttributeValue = boolean | number | string;
+/**
+ * A `Resource.attributes` bag — the process-level identity (`service.name`,
+ * `service.version`, `cloud.region`, …) attached to every exported signal.
+ * Lives here rather than in either exporter because both packages build one and
+ * `wrapResource*` consumes it.
+ */
+type OtlpResourceAttributes = Record<string, OtlpAttributeValue>;
 /** Shared shape for sinks that can be limited to error events only. */
 interface OnlyErrorsOption {
   /** When true, only events with `ok === false` are forwarded. */
@@ -3162,6 +3963,28 @@ interface PipelineLogSinkOptions {
 declare const pipelineLogSink: (options: PipelineLogSinkOptions) => ObservabilitySink;
 /** Options for {@link otlpSink}. */
 interface OtlpSinkOptions extends OnlyErrorsOption {
+  /**
+   * Value of the `deployment.environment` resource attribute (e.g.
+   * `"production"`, `"staging"`, `"development"`).
+   */
+  deploymentEnvironment?: string;
+  /**
+   * When `true`, the sink attaches the resource attributes the **host** detected
+   * for the current request, merged *under* any explicit option so those always
+   * win on collision. In a Worker that is `service.version`,
+   * `deployment.environment`, `cloud.provider`, and `cloud.region` (the colo).
+   *
+   * The sink never inspects `env` or the request itself — detection happens once
+   * per request in the runtime and arrives pre-resolved on the sink context (see
+   * `LogSinkContext.resourceAttributes`), so no sink is ever handed raw bindings.
+   *
+   * Events that originate inside a shard (`ctx.log`, `ctx.trace`, `ctx.metrics`)
+   * carry no host-detected attributes today — the shard has no `env` of its own —
+   * so they export with the explicit options only. Set the values you need
+   * explicitly if you require them to match across worker and shard spans of the
+   * same trace.
+   */
+  detectResources?: boolean;
   /**
    * The OTLP-over-HTTP collector base endpoint (e.g.
    * `https://collector.example.com`). Following the OTel base-endpoint
@@ -3176,11 +3999,29 @@ interface OtlpSinkOptions extends OnlyErrorsOption {
    * default and may be overridden here.
    */
   headers?: Record<string, string>;
+  /**
+   * Additional resource attributes to attach to every exported signal. These
+   * ride alongside the built-in `service.name` and any convenience fields
+   * (`serviceVersion`, `deploymentEnvironment`, etc.). A key that collides with
+   * a built-in resource attribute wins; use this for custom dimensions like
+   * `deployment.region`, `host.name`, or `service.instance.id`.
+   */
+  resourceAttributes?: OtlpResourceAttributes;
   /**
    * Value of the `service.name` resource attribute on every exported span and
    * log — the logical service the telemetry belongs to. Defaults to `lunora`.
    */
   serviceName?: string;
+  /**
+   * Value of the `service.namespace` resource attribute, useful when multiple
+   * services share the same `service.name` under a tenant or team boundary.
+   */
+  serviceNamespace?: string;
+  /**
+   * Value of the `service.version` resource attribute (e.g. a git sha or
+   * release tag).
+   */
+  serviceVersion?: string;
   /**
    * Convenience bearer token: when set, an `Authorization: Bearer` header
    * carrying it is added to every POST (overriding any authorization in
@@ -3225,4 +4066,4 @@ declare const otlpSink: (options: OtlpSinkOptions) => ObservabilitySink;
  */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
 declare const VERSION: string;
-export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_LOG_COLUMNS, DEFAULT_LOG_LIMIT, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, LOG_ARCHIVE_NOT_CONFIGURED, LOG_ARCHIVE_PATH, type ListAuthUsersOptions, type LogArchiveConfig, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MetricEvent, type MetricKind, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogColumnMap, type PipelineLogCursor, type PipelineLogField, type PipelineLogPage, type PipelineLogQuery, type PipelineLogReader, type PipelineLogReaderOptions, type PipelineLogRow, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type SpanEvent, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createPipelineLogReader, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLogArchiveFromEnv, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_LOG_COLUMNS, DEFAULT_LOG_LIMIT, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportBatch, type ExportChange, type ExportCursorStore, type ExportFanOutRequest, type ExportFanOutResult, type ExportSink, type ExportTapFailure, type ExportTapResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, HEALTH_PATH, HEALTH_READY_PATH, type HealthAuthPosture, type HealthBody, type HealthCheckReport, type HealthProbe, type HealthProbeKind, type HealthProbeResult, type HealthRouteDeps, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, LOG_ARCHIVE_NOT_CONFIGURED, LOG_ARCHIVE_PATH, type ListAuthUsersOptions, type LogArchiveConfig, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MetricEvent, type MetricKind, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type NotifySubscriptionDevice, type NotifySubscriptionStoreLike, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpResourceAttributes, type OtlpSinkOptions, type PipelineLike, type PipelineLogColumnMap, type PipelineLogCursor, type PipelineLogField, type PipelineLogPage, type PipelineLogQuery, type PipelineLogReader, type PipelineLogReaderOptions, type PipelineLogRow, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type RateLimiterLike, type ResolvedSecurity, type ResolvedShard, type RestInvoke, type RestRateLimit, type RestRegistryEntry, type RestRegistryLike, type RestRoute, type RestRouteDeps, type Route, type RpcContext, type RpcEnvelope, type RunExportTapOptions, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type SpanEvent, type StorageListFunction as StorageListFn, type StorageObject, type TraceSamplingConfig, type TraceTrustSignal, type TrustInboundTraceContext, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, argsFromQuery, buildHealthRoutes, buildRestRoutes, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createKvCursorStore, createLunoraHandler, createMemoryCursorStore, createPipelineLogReader, createQueryCoordinator, createRestRateLimit, createStaticShardRegistry, createWorker, d1Probe, decorateResponse, defineExportSink, defineRpcEnvelope, durableObjectProbe, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, presenceProbe, r2Sink, readShardKey, resolveLogArchiveFromEnv, resolveLunoraOptions, resolveSecurity, resolveShard, restSurfaceFromRegistry, routeIdentityResolvers, runExportTap, sanitizeChange, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookExportSink, webhookSink, withFrameworkWorker };