@lunora/runtime 1.0.0-alpha.33 → 1.0.0-alpha.35

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,139 +524,968 @@ 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>;
+interface ShardError {
+  /** Human-readable; tests assert on `.includes("timeout")` and similar. */
+  message: string;
+  shardKey: string;
+  /** Set when the per-shard timeout fired. */
+  timedOut: boolean;
+}
+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;
+}
+interface QueryCoordinatorOptions {
+  /**
+   * 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.
+   */
+  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;
+  /** Forwarded to each shard fetch (auth, cookies, bookmark). */
+  headers?: Record<string, string>;
+}
+/**
+ * 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.
+ */
+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";
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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 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 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;
+}
+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.
+   */
+  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>;
+  /**
+   * 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.
+   */
+  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>;
+}
+/**
+ * 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.
+ */
+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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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 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;
+/**
+ * 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`.
+ */
+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;
+}
+/**
+ * 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}.
+ */
+interface ExportSink {
+  deliver: (batch: ExportBatch) => Promise<void>;
+  name: string;
+}
+/**
+ * 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 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;
+  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>;
+}
+/**
+ * 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.
+ */
+declare const r2Sink: (config: {
+  bucket: R2PutLike;
+  name: string;
+  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).
+   */
+  cacheTtlMs?: number;
+  /** Admin-bearer predicate, consulted only when `auth === "admin"`. */
+  isAdmin: (request: Request) => boolean;
+  /**
+   * 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.
+   */
+  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>>;
+/**
+ * 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.
+ */
+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;
+  /**
+   * 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.
+   */
+  exp?: number;
+  /**
+   * 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.
+   */
+  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 {
+  /**
+   * 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;
+}
+/**
+ * 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).
+ */
+declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
+/**
+ * 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 })
+ */
+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;
+}
+/**
+ * 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`.
+ */
+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;
@@ -648,974 +1556,548 @@ interface LogEvent {
   /** Function path that emitted the line, e.g. `"messages:list"`. */
   functionPath: string;
   /** Severity the line was logged at. */
-  level: ContextLogLevel;
-  /** Display string — the message, or the console-style args rendered and space-joined. */
-  message: string;
-  /** Shard key for single-shard calls; absent for the unnamed root DO. */
-  shardKey?: string;
-  /** Span id of the RPC this line was emitted under (trace correlation), or absent. */
-  spanId?: string;
-  /** Trace id this line belongs to (from the inbound `traceparent`), or absent. */
-  traceId?: string;
-  /** Wall-clock millis when the line was emitted. */
-  ts: number;
-  /** Acting userId, or absent when anonymous. */
-  userId?: string;
-}
-/**
- * The 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.
- */
-type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
-/**
- * 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.
- */
-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;
-}
-/**
- * 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 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;
-}
-/** 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[];
-}
-/** Options for {@link createPipelineLogReader}. */
-interface PipelineLogReaderOptions {
-  /**
-   * Override any physical column name that diverges from the default (identity)
-   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
-   */
-  columnMap?: PipelineLogColumnMap;
-  /**
-   * 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.
-   */
-  namespace?: string;
-  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
-  table: 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;
-/**
- * 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.
- */
-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;
-}
-/**
- * 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.
- */
-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";
-/**
- * One measurement recorded from a function handler.
- *
- * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
- * pre-aggregation, so counters carry **delta** temporality and a collector sums
- * them. That keeps the sink model identical to logs and spans (one event, one
- * export) at the cost of chattiness in a hot loop, where the handler should sum
- * locally and record once.
- */
-interface MetricEvent {
-  /**
-   * Structured attributes the caller attached, normalized to a fresh bag of
-   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
-   * dimensions — keep them low-cardinality; an id-valued attribute creates a
-   * distinct time series per id.
-   *
-   * Caller-controlled, so they MAY contain user input and they DO egress to
-   * whatever destination the sink ships to — the same caveat as a log line's
-   * `fields` and a span's `error.message`. Scrub upstream if that matters.
-   */
-  attributes?: LogFields;
-  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
-  functionPath: string;
-  /** Instrument kind; see {@link MetricKind}. */
-  kind: MetricKind;
-  /** Instrument name, e.g. `"orders.placed"`. */
-  name: string;
+  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;
-  /** Wall-clock millis when the measurement was recorded. */
+  /** 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;
-  /**
-   * The measured value: the increment for a `counter`, the current reading for
-   * a `gauge`, the observed sample for a `histogram`.
-   */
-  value: number;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
 }
 /**
- * One span produced by a `ctx.trace(name, fn)` call, or the synthetic root span
- * the shard records for the dispatch itself so a waterfall has a bar to hang
- * its children under.
- *
- * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
- * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
- * no reformatting.
+ * 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.
  */
-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"`. */
-  name: string;
-  /** True when the span body returned without throwing. */
-  ok: boolean;
-  /**
-   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
-   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
-   * no inbound trace context is parented to a locally-minted root, so this is
-   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
-   * carries `""`, meaning "nothing above me in this trace".
-   */
-  parentSpanId: string;
-  /**
-   * True for the synthetic span representing the **dispatch itself**, which the
-   * shard records so a waterfall has a bar for the request to hang its
-   * `ctx.trace` spans under.
-   *
-   * Named for what it is rather than "root": it is not the root of the
-   * collector-side trace — the worker's own RPC span sits above it — and it is
-   * never exported to a sink, because the runtime already emits that dispatch
-   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
-   * the outermost span, which is why the fold prefers it as a trace's anchor.
-   */
-  dispatch?: boolean;
-  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+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.
+ */
+type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
+/**
+ * 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.
+ */
+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;
-  /** 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. */
+  /** 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-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.
+ * 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 ObservabilityEvent {
-  /** Wall-clock duration of the dispatch, in milliseconds. */
-  durationMs: number;
-  /**
-   * 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).
-   */
-  error?: {
-    code: string;
-    message: string;
-    status: number;
-  };
+interface PipelineLogRow {
   /**
-   * 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).
+   * 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.
    */
-  fanOut?: {
-    failed: number;
-    shards: number;
-    table: string;
-  };
-  /** Function path being invoked, e.g. `"messages:list"`. */
+  fields?: unknown;
+  /** Function path that emitted the line, 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. */
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Rendered message. */
+  message: string;
+  /** Shard key for single-shard calls, when present. */
   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).
-   */
+  /** 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;
 }
-/**
- * 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).
- */
-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 {
-  /** 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;
+/** 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[];
 }
-/**
- * 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.
- */
-declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: ObservabilityEvent, context?: ObservabilitySinkContext) => 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.
- */
-declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
-/**
- * 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/
- */
-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>;
-  };
+/** Options for {@link createPipelineLogReader}. */
+interface PipelineLogReaderOptions {
   /**
-   * `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.
+   * Override any physical column name that diverges from the default (identity)
+   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
    */
-  getByName?: (name: string) => {
-    fetch: (request: Request) => Promise<Response>;
-  };
-  idFromName: (name: string) => unknown;
+  columnMap?: PipelineLogColumnMap;
   /**
-   * 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.
+   * 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.
    */
-  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ShardNamespaceLike;
+  namespace?: string;
+  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
 }
-interface ResolvedShard {
-  fetch: (request: Request) => Promise<Response>;
+/** 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;
 /**
- * Return a jurisdiction-restricted view of `namespace`, or `namespace`
- * unchanged when no jurisdiction is configured.
+ * Build a durable-log reader over one R2 Data Catalog (Iceberg) table.
  *
- * 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.
+ * 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.
  */
-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;
+declare const createPipelineLogReader: (client: R2SqlClient, options: PipelineLogReaderOptions) => PipelineLogReader;
 /**
- * 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.).
+ * 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.
  */
-interface ShardRegistry {
-  listShardKeys: (table: string) => Promise<ReadonlyArray<string>> | ReadonlyArray<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 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 createStaticShardRegistry: (table_to_keys: Readonly<Record<string, ReadonlyArray<string>>>) => ShardRegistry;
+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";
 /**
- * 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.
+ * 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;
+}
+/**
+ * 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_*`).
  *
- * `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.
+ * 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.
  */
-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";
-};
+declare const resolveLogArchiveFromEnv: (environment: unknown) => LogArchiveConfig | undefined;
 /**
- * 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.
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
  *
- * - `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}.
+ * - `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.
  */
-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 MetricKind = "counter" | "gauge" | "histogram";
 /**
- * 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 measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
  */
-interface ShardError {
-  /** Human-readable; tests assert on `.includes("timeout")` and similar. */
-  message: string;
-  shardKey: string;
-  /** Set when the per-shard timeout fired. */
-  timedOut: boolean;
-}
-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;
-}
-interface QueryCoordinatorOptions {
+interface MetricEvent {
   /**
-   * 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.
+   * 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.
    */
-  maxConcurrency?: number;
+  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;
   /**
-   * Hard per-shard timeout in milliseconds. Defaults to 5000; a slow
-   * shard surfaces in `errors[]` rather than stalling the aggregate.
+   * 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.
    */
-  perShardTimeoutMs?: number;
-  /** Required — drives which shards to fan out to. */
-  registry: ShardRegistry;
-}
-interface FanOutRequest {
-  args?: Record<string, unknown>;
-  fanOut: FanOutSpec;
-  functionPath: string;
-  /** Forwarded to each shard fetch (auth, cookies, bookmark). */
-  headers?: Record<string, string>;
-}
-/**
- * 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.
- */
-interface MigrationFanOutRequest {
-  args?: Record<string, unknown>;
-  functionPath: string;
-  headers?: Record<string, string>;
-  /** Table whose live shard keys the migration runs across. */
-  table: string;
+  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 outcome: either the unwrapped admin `result` payload, or an error. */
-interface ShardMigrationOutcome {
+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;
   };
-  /** 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.
+   * 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.
    */
-  status: "completed" | "failed" | "in_progress";
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
 }
 /**
- * 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.
+ * 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 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 {
+interface ObservabilityEvent {
+  /** Wall-clock duration of the dispatch, in milliseconds. */
+  durationMs: number;
+  /**
+   * 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).
+   */
   error?: {
+    code: string;
     message: string;
-    timedOut: boolean;
+    status: number;
   };
-  result?: {
-    before: number;
-    total: 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).
+   */
+  fanOut?: {
+    failed: number;
+    shards: number;
+    table: string;
   };
-  shardKey: 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;
+  /**
+   * 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).
+   */
+  spanId?: string;
+  traceId?: string;
 }
 /**
- * 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.
+ * 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.
  *
- * `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.
+ * `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 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 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;
-}
-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.
-   */
-  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>;
+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 {
   /**
-   * 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.
+   * **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`.
    */
-  orchestrateRank: (namespace: ShardNamespaceLike, request: RankFanOutRequest) => Promise<RankFanOutResult>;
+  fuseCloudflareTraces?: boolean;
+  /** Invoked once per `ctx.log.*` call from a function handler. */
+  onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
   /**
-   * 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).
+   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
+   * upstream, so counter values are deltas for the destination to sum.
    */
-  orchestrateRankPage: (namespace: ShardNamespaceLike, request: RankPageFanOutRequest) => Promise<RankPageFanOutResult>;
+  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
+  /** Invoked once per dispatched RPC (single-shard or fan-out). */
+  onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
   /**
-   * 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`).
+   * 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.
    */
-  orchestrateShardTraffic: (namespace: ShardNamespaceLike, request: ShardTrafficFanOutRequest) => Promise<ShardTrafficFanOutResult>;
-  readonly registry: ShardRegistry;
+  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
 }
 /**
- * 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.
+ * 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 ExportFanOutRequest {
-  args?: Record<string, unknown>;
-  headers?: Record<string, string>;
-  /**
-   * 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.
-   */
-  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>;
-}
+declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: ObservabilityEvent, context?: ObservabilitySinkContext, sampling?: TraceSamplingConfig) => 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.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 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 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";
 /**
- * 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.
+ * 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 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 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;
-}
-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>;
+/** 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;
 }
 /**
- * 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.
+ * 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.
  */
-interface ApplyCdcFanOutRequest {
-  batches: ReadonlyArray<{
-    changes: ReadonlyArray<Record<string, unknown>>;
-    shardKey: string;
-  }>;
-  headers?: Record<string, string>;
+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";
 }
-interface ApplyCdcFanOutResult {
-  /** Total changes applied across shards. */
-  applied: number;
-  failed: number;
-  ok: number;
+/** 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;
+}) => Promise<Response>;
+/**
+ * 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`.
+ */
+type RestRateLimit = (request: Request, functionPath: string) => Promise<Response | undefined> | Response | undefined;
+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, (request: Request, env: unknown) => Promise<Response>>;
+/** 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;
+  }>;
 }
 /**
- * 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 {
   /**
@@ -1917,6 +2399,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 +2699,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 +2833,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 +2956,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 +2993,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 +3068,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 +3170,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 +3187,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`
@@ -3225,4 +3871,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 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 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, 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 };