@lunora/runtime 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,2426 @@
+import { RankDirection, RankPageRow, DatabaseWriterLike } from '@lunora/do';
+export type { RankDirection as RankPageDirection, RankPageRowKey as RankPageKey, RankPageRow, ShardRankPageResult } from '@lunora/do';
+import { WorkflowsRestClient } from '@lunora/workflow';
+/**
+* Turn-key incremental-sync source helpers for warehouse connectors
+* (Fivetran custom functions, Airbyte incremental sources).
+*
+* The runtime's admin `/_lunora/admin/connector/sync` endpoint returns a
+* {@link ConnectorSyncPage}: a flat list of change records since an opaque
+* cursor, a `nextCursor` to resume from, and a `hasMore` flag. These helpers
+* reshape that page into the response envelopes the two ecosystems expect, so a
+* connector wrapper stays a few lines.
+*
+* {@link toFivetranResponse} produces the `{ state, insert, update, delete,
+* hasMore, schema }` object a Fivetran connector function returns from its
+* handler. {@link toAirbyteMessages} produces an ordered array of Airbyte
+* protocol messages (a `RECORD` per row, a trailing `STATE` carrying the cursor),
+* the line-delimited stream an Airbyte incremental source emits.
+*
+* Both consume the SAME page, so a single endpoint feeds either ecosystem.
+*/
+/**
+* One change record in a {@link ConnectorSyncPage}. Mirrors a row of the CDC log
+* the shard / D1 change feed produces: an `op` (insert / update / delete), the
+* owning `table`, and the document. `op` is normalised to the three warehouse
+* verbs; an unknown / absent op is treated as `"upsert"` (insert-or-update),
+* which is the safe default for change feeds that don't distinguish the two.
+*/
+interface ConnectorChange {
+  /** The full document. For a delete, may carry only the primary key. */
+  doc: Record<string, unknown>;
+  /** Change verb. `upsert` collapses insert+update for feeds that don't separate them. */
+  op: "delete" | "insert" | "update" | "upsert";
+  /** Source table this change belongs to. */
+  table: string;
+}
+/**
+* A page of changes the connector endpoint returns. `nextCursor` is an opaque
+* token the consumer stores and re-posts verbatim to resume; never parse it.
+* `hasMore` is `true` while the source has further pages past this one — keep
+* paging until it is `false` (caught up).
+*/
+interface ConnectorSyncPage {
+  changes: ReadonlyArray<ConnectorChange>;
+  hasMore: boolean;
+  /** Opaque resume token. Treat as a black box; store and re-send unchanged. */
+  nextCursor: string;
+}
+/**
+* Fivetran connector-function response envelope. A Fivetran custom function
+* returns this object: `state` is persisted by Fivetran and handed back on the
+* next sync (map it straight to {@link ConnectorSyncPage.nextCursor}), the
+* `insert` / `update` / `delete` maps bucket records per table, `hasMore` drives
+* Fivetran's "call me again immediately" loop, and `schema` declares each table's
+* primary key.
+*
+* See https://fivetran.com/docs/connectors/functions#responseformat.
+*/
+interface FivetranResponse {
+  delete: Record<string, Record<string, unknown>[]>;
+  hasMore: boolean;
+  insert: Record<string, Record<string, unknown>[]>;
+  schema: Record<string, {
+    primary_key: string[];
+  }>;
+  state: {
+    cursor: string;
+  };
+  update: Record<string, Record<string, unknown>[]>;
+}
+/** One Airbyte protocol message (a `RECORD` row or a `STATE` checkpoint). */
+type AirbyteMessage = {
+  record: {
+    data: Record<string, unknown>;
+    emitted_at: number;
+    stream: string;
+  };
+  type: "RECORD";
+} | {
+  state: {
+    data: {
+      cursor: string;
+    };
+  };
+  type: "STATE";
+};
+/**
+* Format a {@link ConnectorSyncPage} as a Fivetran connector-function response.
+*
+* Inserts and upserts both land in `insert` (Fivetran upserts on primary key, so
+* an insert and an update of an existing row are wire-identical); explicit
+* updates land in `update`; deletes in `delete`. `state.cursor` carries the
+* opaque resume token Fivetran will echo back on the next invocation.
+* @param page the page returned by the connector sync endpoint.
+* @param primaryKey the primary-key column per table (default `"_id"`); pass a
+* map to override per table, used to fill the `schema` block.
+*/
+declare const toFivetranResponse: (page: ConnectorSyncPage, primaryKey?: Record<string, string> | string) => FivetranResponse;
+/**
+* Format a {@link ConnectorSyncPage} as an ordered array of Airbyte protocol
+* messages: one `RECORD` per change (stream = table name), followed by a single
+* trailing `STATE` message carrying the opaque cursor. An Airbyte source serializes
+* these as line-delimited JSON to stdout.
+*
+* Airbyte's protocol has no native delete verb in `RECORD`; a delete is emitted
+* as a `RECORD` with a `_lunora_deleted: true` marker on the row so a downstream
+* normalization / dbt step can tombstone it. Callers needing true CDC deletes
+* should run Airbyte's CDC-deletion handling on that marker.
+* @param page the page returned by the connector sync endpoint.
+* @param emittedAt epoch-ms stamped on each `RECORD` (default `Date.now()`).
+*/
+declare const toAirbyteMessages: (page: ConnectorSyncPage, emittedAt?: number) => AirbyteMessage[];
+/**
+* The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+* the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+* must outlive the response, and `passThroughOnException` for the top-level
+* error posture.
+*
+* It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+* runtime and `@lunora/nuxt` is a framework integration that intentionally does
+* not depend on `@lunora/runtime`'s worker types, yet both need this exact
+* shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+* inbound request to the user's composed worker. Each imports this file by
+* relative path and the bundler (packem/rollup) inlines it: no runtime
+* dependency edge is created, the helper is duplicated only in emitted output,
+* never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+* `shared/` — bundler-inlined source".
+*
+* Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+* supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+* non-Cloudflare preview, a unit test) may hand over a partial context or none
+* at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+* fall back to {@link NOOP_EXECUTION_CONTEXT}.
+*/
+interface ExecutionContextLike {
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* No-op `ExecutionContext` used when the host runtime didn't supply one (a
+* non-Cloudflare preview, or a unit test), so the worker's `fetch` always
+* receives a valid third argument.
+*/
+declare const NOOP_EXECUTION_CONTEXT: ExecutionContextLike;
+/** A timestamp as better-auth stores it: epoch-ms, an ISO string, or absent. */
+type AuthTimestamp = null | number | string;
+/**
+* One authenticated user, as the auth browser surfaces it. Mirrors better-auth's
+* `user` row plus the `admin()` plugin columns (`role`/`banned`/…); the index
+* signature additionally carries any app-defined `user.additionalFields`.
+*/
+interface AuthUser {
+  [key: string]: unknown;
+  banExpires?: AuthTimestamp;
+  banned?: boolean | null;
+  banReason?: null | string;
+  createdAt?: AuthTimestamp;
+  email?: null | string;
+  emailVerified?: boolean | null;
+  id: string;
+  image?: null | string;
+  name?: null | string;
+  role?: null | string;
+}
+/** One auth session, as the auth browser surfaces it. Mirrors better-auth's `session` row. */
+interface AuthSession {
+  [key: string]: unknown;
+  createdAt?: AuthTimestamp;
+  expiresAt?: AuthTimestamp;
+  id: string;
+  impersonatedBy?: null | string;
+  ipAddress?: null | string;
+  userAgent?: null | string;
+  userId: string;
+}
+/** A page of users or sessions plus the total count, for paginated browsing. */
+interface AuthPage<T> {
+  rows: T[];
+  total: number;
+}
+/** The result of {@link AuthAdmin.impersonateUser}: a session token to act as the target user. */
+interface AuthImpersonation {
+  expiresAt?: AuthTimestamp;
+  token: string;
+  user: AuthUser;
+}
+/**
+* Which admin surfaces the configured auth plane supports, derived from the
+* enabled better-auth plugins. The studio renders only the panels whose
+* capability is `true`.
+*/
+interface AuthCapabilities {
+  accounts: boolean;
+  admin: boolean;
+  organization: boolean;
+  passkey: boolean;
+  twoFactor: boolean;
+}
+/** Filtering / paging options forwarded to {@link AuthAdmin.listUsers} from the users endpoint's query string. */
+interface ListAuthUsersOptions {
+  filterField?: string;
+  filterValue?: string;
+  limit?: number;
+  offset?: number;
+  search?: string;
+  searchField?: string;
+  sortBy?: string;
+  sortDirection?: "asc" | "desc";
+}
+/**
+* The auth user-management plane backing the studio's auth dashboard. The host
+* wires this to better-auth (typically via `@lunora/auth`'s `createAuthAdmin`);
+* the runtime stays free of a hard dependency on `@lunora/auth`. The read
+* methods back the GET browse endpoints; the optional mutations back the
+* admin-gated POST endpoints — a host that only needs read-only browsing can
+* omit them (the POST routes then respond `AUTH_OP_NOT_SUPPORTED`). Omit the
+* whole option and every `/auth/*` endpoint responds `AUTH_NOT_CONFIGURED`.
+*
+* Every method here runs behind the worker's `LUNORA_ADMIN_TOKEN` gate — the
+* implementation is a trusted server-side operator, not an end-user API.
+*/
+interface AuthAdmin {
+  banUser?: (input: {
+    expiresInSeconds?: number;
+    reason?: string;
+    userId: string;
+  }) => Promise<AuthUser>;
+  cancelInvitation?: (input: {
+    invitationId: string;
+  }) => Promise<void>;
+  capabilities?: () => Promise<AuthCapabilities>;
+  createUser?: (input: {
+    data?: Record<string, unknown>;
+    email: string;
+    name: string;
+    password?: string;
+    role?: string | string[];
+  }) => Promise<AuthUser>;
+  deletePasskey?: (input: {
+    passkeyId: string;
+  }) => Promise<void>;
+  disableTwoFactor?: (input: {
+    userId: string;
+  }) => Promise<void>;
+  impersonateUser?: (input: {
+    userId: string;
+  }) => Promise<AuthImpersonation>;
+  listAccounts?: (input: {
+    userId: string;
+  }) => Promise<Record<string, unknown>[]>;
+  listInvitations?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
+  listMembers?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
+  listOrganizations?: (options: {
+    limit?: number;
+    offset?: number;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
+  listPasskeys?: (input: {
+    userId: string;
+  }) => Promise<Record<string, unknown>[]>;
+  listSessions: (options: {
+    limit?: number;
+    offset?: number;
+    userId?: string;
+  }) => Promise<AuthPage<AuthSession>>;
+  listUsers: (options: ListAuthUsersOptions) => Promise<AuthPage<AuthUser>>;
+  removeMember?: (input: {
+    memberId: string;
+  }) => Promise<void>;
+  removeUser?: (input: {
+    userId: string;
+  }) => Promise<void>;
+  revokeUserSession?: (input: {
+    sessionId: string;
+  }) => Promise<void>;
+  revokeUserSessions?: (input: {
+    userId: string;
+  }) => Promise<void>;
+  setRole?: (input: {
+    role: string | string[];
+    userId: string;
+  }) => Promise<AuthUser>;
+  setUserPassword?: (input: {
+    newPassword: string;
+    userId: string;
+  }) => Promise<void>;
+  unbanUser?: (input: {
+    userId: string;
+  }) => Promise<AuthUser>;
+  unlinkAccount?: (input: {
+    accountId: string;
+    userId: string;
+  }) => Promise<void>;
+  updateUser?: (input: {
+    data: Record<string, unknown>;
+    userId: string;
+  }) => Promise<AuthUser>;
+}
+/**
+* Read-only subset of {@link AuthAdmin}, kept as an alias for the former
+* `authIntrospector` option (which the worker still honours as a browse-only
+* fallback). Prefer wiring `authAdmin` with `@lunora/auth`'s `createAuthAdmin`
+* so the mutation endpoints light up too.
+*/
+type AuthIntrospector = Pick<AuthAdmin, "listSessions" | "listUsers">;
+/** Closure-scoped worker helpers the auth routes borrow (so this module stays out of the worker's god-closure). */
+/**
+* A compact, transport-safe description of one function argument — the runtime
+* read of a `v.*` validator's reflection tags (`kind` + `_meta`). The runtime
+* deliberately avoids a hard dependency on `@lunora/values`, so this reads the
+* validator structurally rather than importing its types.
+*/
+interface FunctionArgumentDescriptor {
+  /** Element validator kind for an `array` arg (one level), e.g. `string`. */
+  element?: string;
+  /** The (optional-unwrapped) validator kind, e.g. `string`, `id`, `object`. */
+  kind: string;
+  /** The argument name. */
+  name: string;
+  /** True when the arg is wrapped in `v.optional(...)`. */
+  optional: boolean;
+  /** Target table for an `id` arg (`v.id("table")`). */
+  table?: string;
+}
+/**
+* Describe one named argument from its validator. Unwraps a single `v.optional`
+* layer (marking the arg optional and reporting the inner kind), and surfaces
+* the two most useful per-kind details: an `id` arg's target table and an
+* `array` arg's element kind. Nested object/union shapes report their top-level
+* kind only — enough for a signature view without a deep recursive walk.
+*/
+/**
+* Observability hooks for the Lunora runtime.
+*
+* A user-supplied {@link ObservabilitySink} receives one event per dispatched
+* RPC (single-shard forward or fan-out). The runtime is otherwise oblivious
+* to where the telemetry goes — adapters that forward to Cloudflare Analytics
+* Engine, OTLP-over-HTTP, Sentry, or stdout all implement the same shape.
+*
+* Failure model: the sink callback is wrapped in a try/catch so a faulty
+* adapter never breaks user-facing RPC dispatch. Errors thrown from inside
+* the sink are swallowed (they would otherwise replace a useful user-visible
+* error with a telemetry-pipeline failure).
+*/
+/**
+* Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
+* fan-outs set `fanOut` with the table being aggregated, shard count, and
+* per-shard failure count.
+*/
+interface ObservabilityEvent {
+  /** Wall-clock duration of the dispatch, in milliseconds. */
+  durationMs: number;
+  /**
+  * 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;
+  };
+  /**
+  * 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;
+  };
+  /** 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;
+}
+/** Severity of a {@link LogEvent}, mirroring the usual console levels. */
+type LogLevel = "debug" | "error" | "info" | "log" | "warn";
+/**
+* One application log line emitted from a function handler via `ctx.log`.
+*
+* Unlike {@link ObservabilityEvent} (one summary per dispatch), a `LogEvent`
+* is produced for each `ctx.log.*` call, carrying the human-readable `message`
+* (the args joined for display) plus the structured `args` array for sinks that
+* want the raw values. `functionPath` attributes the line to the handler that
+* emitted it; `shardKey`/`userId` mirror the dispatch context.
+*
+* This is how `ctx.log` reaches a destination in production: wire a sink's
+* {@link ObservabilitySink.onLog} and route it wherever you ship logs. In dev
+* the runtime also emits these to `console` so the CLI / Vite plugin can format
+* them in the terminal.
+*/
+interface LogEvent {
+  /** Raw arguments passed to the `ctx.log.*` call, in order. */
+  args: unknown[];
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: LogLevel;
+  /** Display string — the 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 line was emitted. */
+  ts: number;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+* Per-event context handed to a sink alongside the event. Lets a sink register
+* background work (e.g. a telemetry POST) with the request's `ctx.waitUntil` so
+* it survives isolate teardown after the response returns. Absent (`undefined`
+* `waitUntil`) on paths with no request context (e.g. the in-process
+* `serverQuery` fast-path), where the sink falls back to fire-and-forget.
+*/
+interface ObservabilitySinkContext {
+  /** Keep a background promise alive past the response (the request's `ctx.waitUntil`). */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* 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 dispatched RPC (single-shard or fan-out). */
+  onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
+}
+/**
+* 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>;
+  };
+  /**
+  * `getByName` is the friendlier API but isn't on every workers-types
+  * release yet. We prefer it when available and fall back to
+  * `idFromName` + `get` for compatibility.
+  */
+  getByName?: (name: string) => {
+    fetch: (request: Request) => Promise<Response>;
+  };
+  idFromName: (name: string) => unknown;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Every ID and stub created
+  * from the returned namespace is pinned to `jurisdiction`. Optional because
+  * older workers-types releases (and unit-test doubles) may not expose it;
+  * {@link applyJurisdiction} fails closed when a jurisdiction is requested
+  * but this method is absent.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ShardNamespaceLike;
+}
+interface ResolvedShard {
+  fetch: (request: Request) => Promise<Response>;
+}
+/**
+* Return a jurisdiction-restricted view of `namespace`, or `namespace`
+* unchanged when no jurisdiction is configured.
+*
+* Fail-closed: if a jurisdiction is requested but the binding does not expose
+* `.jurisdiction()` (an older workers-types, or a misconfigured test double),
+* this throws rather than silently routing to the un-pinned global namespace —
+* silently dropping a residency constraint would let data land outside the
+* compliance boundary the caller asked for.
+*/
+declare const applyJurisdiction: (namespace: ShardNamespaceLike, jurisdiction?: DurableObjectJurisdiction) => ShardNamespaceLike;
+/** Look up a shard stub by name, preferring `getByName` when present. */
+declare const resolveShard: (namespace: ShardNamespaceLike, shardKey: string) => ResolvedShard;
+/**
+* Source of "which shard keys exist for a given table right now". Returning
+* an empty array is valid — the coordinator will respond with the merge
+* strategy's identity (empty array for `concat`, `0` for `sum`, etc.).
+*/
+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).
+*/
+declare const createStaticShardRegistry: (table_to_keys: Readonly<Record<string, ReadonlyArray<string>>>) => ShardRegistry;
+/**
+* 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.
+*/
+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";
+};
+/**
+* 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}.
+*/
+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;
+}
+/**
+* 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 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;
+/**
+* Secure-by-default HTTP edge for the Lunora worker.
+*
+* The worker's top-level `fetch` (see `./create-worker`) is the single choke
+* point every response passes through — RPC, auth, admin, `httpRoute` handlers,
+* and the SSR fallback alike. This module supplies what is applied there:
+* `decorateResponse` adds baseline security headers plus, for allowed
+* cross-origin requests, the matching `Access-Control-Allow-*` headers (never
+* overwriting a header the inner handler set); `handleCorsPreflight` answers
+* `OPTIONS` preflights for allowlisted origins; `enforceOrigin` is a CSRF guard
+* that rejects state-changing, cookie-authenticated requests from untrusted
+* origins.
+*
+* Every layer is on by default and individually disable-able through the
+* `SecurityOptions` passed to `createWorker`. Resolution (`resolveSecurity`) is
+* pure and platform-agnostic — it touches only the global `Request`/`Response`/
+* `Headers`/`URL`, so it unit-tests under plain Node without workerd.
+*/
+/** Per-header overrides for {@link SecurityHeadersOptions}. `false` omits the header. */
+interface SecurityHeadersOptions {
+  /**
+  * `Content-Security-Policy`. Omitted (`undefined`) applies a restrictive
+  * default to **non-HTML** responses only, so an SSR page is never broken by
+  * a policy it didn't opt into. Pass a string to apply that policy to every
+  * response (HTML included); `false` to never send one.
+  */
+  csp?: string | false;
+  /** `X-Frame-Options` (clickjacking). Defaults to `SAMEORIGIN`. `false` omits it. */
+  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  /** `Strict-Transport-Security`. Only ever sent over HTTPS. `false` omits it. */
+  hsts?: boolean | {
+    includeSubDomains?: boolean;
+    maxAge?: number;
+    preload?: boolean;
+  };
+  /** `Permissions-Policy`. Defaults to a minimal deny list. `false` omits it. */
+  permissionsPolicy?: string | false;
+  /** `Referrer-Policy`. Defaults to `strict-origin-when-cross-origin`. `false` omits it. */
+  referrerPolicy?: string | false;
+}
+/** CORS allowlist. Cross-origin is denied unless an origin matches. */
+interface CorsOptions {
+  /** Echo `Access-Control-Allow-Credentials: true`. Incompatible with a `*` allowlist. */
+  allowCredentials?: boolean;
+  /** Request headers permitted on the actual request (preflight `Allow-Headers`). */
+  allowedHeaders?: string[];
+  /** Methods permitted cross-origin (preflight `Allow-Methods`). */
+  allowedMethods?: string[];
+  /** Allowed origins — an explicit list (`"*"` permitted only without credentials) or a predicate. */
+  allowedOrigins: string[] | ((origin: string) => boolean);
+  /** Preflight cache lifetime in seconds (`Access-Control-Max-Age`). */
+  maxAge?: number;
+}
+/** Origin/CSRF guard configuration. */
+interface CsrfOptions {
+  /** Extra origins (beyond same-origin and the CORS allowlist) accepted on unsafe cookie requests. */
+  trustedOrigins?: string[];
+}
+/**
+* The `security` option on `createWorker`. Every field is optional and defaults
+* to a secure posture; set a field to `false` to opt out of that layer.
+*/
+interface SecurityOptions {
+  /** CORS. Defaults to **deny cross-origin**; supply an allowlist to permit specific origins. `false` disables CORS handling. */
+  cors?: CorsOptions | false;
+  /** CSRF/origin guard for unsafe, cookie-authenticated requests. `true`/object = on (default), `false` = off. */
+  csrf?: boolean | CsrfOptions;
+  /** Baseline security response headers. `true`/object = on (default), `false` = off. */
+  headers?: boolean | SecurityHeadersOptions;
+}
+interface ResolvedHeaders {
+  coop: string | undefined;
+  csp: {
+    htmlToo: boolean;
+    value: string;
+  } | undefined;
+  enabled: boolean;
+  frameOptions: string | undefined;
+  hsts: string | undefined;
+  permissionsPolicy: string | undefined;
+  referrerPolicy: string | undefined;
+}
+interface ResolvedCors {
+  allowCredentials: boolean;
+  allowedHeaders: string[];
+  allowedMethods: string[];
+  enabled: boolean;
+  isAllowed: (origin: string) => boolean;
+  /**
+  * Like {@link ResolvedCors.isAllowed} but NEVER satisfied by a wildcard `*`
+  * allowlist — an origin counts only when matched by an explicit, non-wildcard
+  * rule (a named origin in the list, or a custom predicate the developer
+  * wrote). Used by the CSRF guard: a wildcard CORS allowlist means "any origin
+  * may read my non-credentialed responses", which must NOT be conflated with
+  * "I trust any origin to make authenticated state changes".
+  */
+  isExplicitlyAllowed: (origin: string) => boolean;
+  maxAge: number;
+}
+interface ResolvedCsrf {
+  enabled: boolean;
+  trustedOrigins: string[];
+}
+/** Normalized, ready-to-apply security configuration. */
+interface ResolvedSecurity {
+  cors: ResolvedCors;
+  csrf: ResolvedCsrf;
+  headers: ResolvedHeaders;
+}
+/**
+* Normalize the public {@link SecurityOptions} into the resolved form the
+* request path applies. Pure — throws only on an invalid combination (wildcard
+* CORS + credentials) so the misconfiguration surfaces at worker construction
+* rather than silently shipping an unenforceable policy.
+*
+* `env` supplies the deployment-level security vars: `LUNORA_SECURITY_HEADERS` /
+* `LUNORA_SECURITY_CSRF` opt out of those layers (set either to `off`/`false`/`0`),
+* and `LUNORA_ALLOWED_ORIGINS` / `LUNORA_CORS_ALLOW_CREDENTIALS` configure CORS
+* when it isn't set in code. **Code config wins** — an explicit `security.*` in
+* {@link SecurityOptions} overrides the matching env knob — so the env var only
+* relaxes or fills the secure default, and the DO security audit (which reads the
+* same vars) and the running worker stay in agreement.
+*/
+declare const resolveSecurity: (security: SecurityOptions | undefined, env?: Record<string, unknown>) => ResolvedSecurity;
+/**
+* CSRF defense: reject an unsafe (state-changing), **cookie-authenticated**
+* request whose `Origin`/`Referer` is neither same-origin nor allowlisted.
+*
+* Scoped deliberately to cookie-bearing browser requests — the only vector a
+* cross-site forgery can ride, since a browser auto-attaches cookies but never a
+* bearer token or custom header. Bearer/server-to-server traffic (no `Cookie`)
+* is exempt, as are safe methods. Returns a `403` `Response` to short-circuit,
+* or `undefined` when the request may proceed.
+* @returns a `403` Response when the origin is untrusted, or `undefined` when the request is allowed.
+*/
+declare const enforceOrigin: (request: Request, resolved: ResolvedSecurity) => Response | undefined;
+/**
+* Answer a CORS preflight (`OPTIONS` carrying `Access-Control-Request-Method`)
+* for an allowlisted origin with a `204`. Returns `undefined` for non-preflight
+* requests, a disabled CORS layer, or a disallowed origin — letting the request
+* fall through to normal routing.
+* @returns a `204` Response for valid preflights, or `undefined` to fall through.
+*/
+declare const handleCorsPreflight: (request: Request, resolved: ResolvedSecurity) => Response | undefined;
+/**
+* Apply baseline security headers and (for allowed cross-origin requests) CORS
+* headers to an outgoing response, without overwriting anything the inner
+* handler already set.
+*
+* WebSocket upgrade responses (`status 101` / a `webSocket` field) are returned
+* untouched: re-wrapping them in a new `Response` would drop the socket and the
+* hibernation handshake.
+*/
+declare const decorateResponse: (response: Response, request: Request, resolved: ResolvedSecurity) => Response;
+/**
+* Wire-format RPC envelope. Posted to `POST /_lunora/rpc`.
+*
+* `functionPath` is the `&lt;file>:&lt;function>` identifier emitted by codegen,
+* e.g. `"messages:list"`. `shardKey` is optional — when omitted the runtime
+* routes to {@link WorkerOptions.defaultShardKey} (default `"__root__"`).
+*
+* `fanOut` opts the envelope into cross-shard routing via the
+* {@link WorkerOptions.queryCoordinator}; mutually exclusive with
+* `shardKey` (specifying both is a 400 — fan-out *is* the shard choice).
+*/
+interface RpcEnvelope {
+  args?: Record<string, unknown>;
+  fanOut?: FanOutSpec;
+  functionPath: string;
+  shardKey?: string;
+}
+type Route = (request: Request, env: unknown, context: ExecutionContextLike) => Promise<Response> | Response;
+/**
+* Context handed to HTTP-action handlers. Built per request by the worker; its
+* `run*` methods forward an RPC envelope to the shard, so handlers reach
+* queries/mutations/actions without a direct DB binding.
+*
+* `reference` is typed `unknown` so this structural contract stays free of a
+* `@lunora/server` dependency while remaining assignable from the fully-typed
+* `HttpActionCtx` on the server side (`{ __lunoraRef }` is read at runtime).
+*/
+interface HttpActionContext {
+  auth: {
+    getIdentity: () => Promise<Record<string, unknown> | null>;
+    userId: null | string;
+  };
+  fetch: typeof globalThis.fetch;
+  runAction: <R>(reference: unknown, args?: Record<string, unknown>) => Promise<R>;
+  runMutation: <R>(reference: unknown, args?: Record<string, unknown>) => Promise<R>;
+  runQuery: <R>(reference: unknown, args?: Record<string, unknown>) => Promise<R>;
+}
+interface HttpActionLike {
+  handler: (context: HttpActionContext, request: Request) => Promise<Response> | Response;
+}
+/**
+* Structural view of `@lunora/server`'s `httpRouter()`. The worker dispatches by
+* calling `fetch` — the same shape as a hono app's `app.fetch` — so the runtime
+* stays free of a hard dependency on the server package (and on hono). The
+* per-request {@link HttpActionContext} is injected on the `__lunoraCtx` env
+* binding; the router lifts it into the handler's context.
+*/
+interface HttpRouterLike {
+  fetch(request: Request, env?: unknown, context?: ExecutionContextLike): Promise<Response> | Response;
+}
+/**
+* Identity resolved from the inbound request by {@link 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;
+}
+/**
+* Per-table sharding metadata the admin import endpoint needs to route rows.
+* Structural so this package stays free of `@lunora/server`. The codegen-
+* generated worker entry passes a thin projection of the user's schema.
+*/
+interface ShardingInfo {
+  /** `global` when the table lives in D1; `shardBy` when keyed by a field; `root` (or absent) otherwise. */
+  mode: {
+    field?: string;
+    kind: "global" | "root" | "shardBy";
+  };
+}
+/**
+* Lookup the runtime uses to bucket an import row to its owning shard. Returns
+* `undefined` for unknown tables — the row is reported as a hard error.
+*/
+type AdminTableResolver = (table: string) => ShardingInfo | undefined;
+/**
+* Streamed bulk export of `.global()` tables, materialised as an async iterable
+* of `{table, doc}` rows. The runtime concatenates this stream after the
+* shard-local stream so the receiver sees a single NDJSON body.
+*/
+type GlobalExportFunction = (request: {
+  tables: ReadonlyArray<string>;
+}) => AsyncIterable<{
+  doc: Record<string, unknown>;
+  table: string;
+}>;
+/**
+* Read a page of the `.global()` (D1) change-data-capture log past `sinceSeq`
+* for the admin sync endpoint. Wire it to `@lunora/d1`'s `readD1CdcChanges`.
+* When omitted, the sync endpoint returns only shard-local changes.
+*/
+type GlobalCdcSyncFunction = (request: {
+  limit?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: ReadonlyArray<Record<string, unknown>>;
+  cursor: number;
+}>;
+/**
+* Replay a batch of `.global()` (D1) CDC changes for the admin apply endpoint
+* (point-in-time recovery). Wire it to `applyCdcChanges` on a D1 writer;
+* returns the number applied. When omitted, the apply endpoint replays only
+* shard-local changes.
+*/
+type GlobalCdcApplyFunction = (request: {
+  changes: ReadonlyArray<Record<string, unknown>>;
+}) => Promise<number>;
+/**
+* Bulk import of `.global()` rows. Returns insert counts + errors merged across
+* tables.
+*
+* Each row carries its true physical source `line` so error attribution stays
+* accurate even when global rows are interspersed with shard rows or blank lines
+* in the NDJSON (a single `startLine` can't describe non-contiguous rows). The
+* `startLine` field is the line of the FIRST global row, retained only as a
+* backward-compatible fallback for importers that haven't adopted per-row lines.
+*/
+type GlobalImportFunction = (request: {
+  rows: ReadonlyArray<{
+    doc: Record<string, unknown>;
+    line: number;
+    table: string;
+  }>;
+  startLine?: number;
+}) => Promise<{
+  conflicts: number;
+  errors: ReadonlyArray<{
+    code: string;
+    line: number;
+    message: string;
+    table: string;
+  }>;
+  inserted: Record<string, number>;
+}>;
+/** One R2 object as the storage browser surfaces it. Mirrors `@lunora/storage`'s `R2ObjectLike`. */
+interface StorageObject {
+  customMetadata?: Record<string, string>;
+  etag: string;
+  httpMetadata?: {
+    contentType?: string;
+  };
+  key: string;
+  size: number;
+}
+/**
+* One registered function, as the discovery endpoint surfaces it. Structurally
+* a subset of codegen's `RegisteredLunoraFunction` — only `kind` and
+* `visibility` matter here, so the generated `LUNORA_FUNCTIONS` map satisfies
+* the {@link FunctionRegistryLike} value shape.
+*/
+interface FunctionDescriptor {
+  /** The function's declared argument schema, derived from its `v.*` validators. */
+  args: FunctionArgumentDescriptor[];
+  kind: "action" | "mutation" | "query";
+  /** The `&lt;file>:&lt;function>` identifier, e.g. `messages:list`. */
+  path: string;
+  /** `"internal"` functions are never exposed by the discovery endpoint; absence === public. */
+  visibility?: "internal" | "public";
+}
+/** One value in {@link FunctionRegistryLike} — the bits of a registered function the discovery endpoint reads. */
+interface FunctionRegistryEntry {
+  /** The function's `v.*` args validator map; read structurally for the signature view. */
+  args?: unknown;
+  /**
+  * The generated registry carries `"stream"` alongside query/mutation/action;
+  * the discovery endpoint surfaces the latter three only (a `stream` function
+  * isn't runnable from the function runner), but accepting the kind here lets
+  * callers pass the generated `LUNORA_FUNCTIONS` map without a cast.
+  */
+  kind: "action" | "mutation" | "query" | "stream";
+  visibility?: "internal" | "public";
+}
+/**
+* The generated `LUNORA_FUNCTIONS` dispatch table, narrowed to what the
+* discovery endpoint reads. Pass the map straight from `_generated/functions.ts`.
+*/
+type FunctionRegistryLike = Record<string, FunctionRegistryEntry>;
+/**
+* Lists objects in the storage bucket for the admin file browser. Structurally
+* compatible with `@lunora/storage`'s `Storage["list"]` — the runtime stays free
+* of a hard dependency on the storage package.
+*/
+type StorageListFunction = (prefix?: string, options?: {
+  bucket?: string;
+  cursor?: string;
+  limit?: number;
+}) => Promise<{
+  cursor?: string;
+  objects: StorageObject[];
+}>;
+/**
+* Deletes one object from a storage bucket for the admin file browser.
+* Structurally compatible with `@lunora/storage`'s `Storage["delete"]`, so
+* passing `createStorage(...).delete` satisfies it. The optional `bucket` selects
+* a named bucket for a multi-bucket deployment (ignored by single-bucket hosts).
+*/
+type StorageDeleteFunction = (key: string, options?: {
+  bucket?: string;
+}) => Promise<void> | void;
+/**
+* Uploads one object to a storage bucket for the admin file browser. Mirrors
+* `@lunora/storage`'s `Storage["upload"]` (only the bits the admin endpoint
+* needs): the key, the raw bytes, an optional content-type, and an optional
+* target `bucket` for multi-bucket deployments.
+*/
+type StorageUploadFunction = (key: string, body: ArrayBuffer, options?: {
+  bucket?: string;
+  contentType?: string;
+}) => Promise<{
+  etag?: string;
+  key: string;
+}> | {
+  etag?: string;
+  key: string;
+};
+/**
+* Mints a (signed or public) URL for one object so the admin file browser can
+* offer a "copy URL" action. The optional `expiresInSeconds` lets the caller pick
+* a share-link lifetime (the host clamps it); `bucket` selects a named bucket.
+* Structurally compatible with `@lunora/storage`'s `Storage["getSignedUrl"]`.
+*/
+type StorageSignedUrlFunction = (key: string, options?: {
+  bucket?: string;
+  expiresInSeconds?: number;
+}) => Promise<string> | string;
+/** One `.global()` table plus its row count. Mirrors `@lunora/d1`'s `GlobalTableInfo`. */
+interface GlobalTableInfo {
+  name: string;
+  rowCount: number;
+}
+/** A window of rows from one global table. Mirrors `@lunora/d1`'s `GlobalTablePage`. */
+interface GlobalTablePage {
+  columns: string[];
+  /** FK columns (local column → referenced table) for external tables with real `REFERENCES` constraints. */
+  refs?: Record<string, string>;
+  rows: Record<string, unknown>[];
+  total: number;
+}
+/** One eq constraint a facet-value click adds to the global browser's view. Mirrors `@lunora/d1`'s `GlobalFilterClause`. */
+interface GlobalFilterClause {
+  column: string;
+  value: unknown;
+}
+/** Per-column distinct-value summary for the global browser. Mirrors `@lunora/d1`'s `GlobalFacetResult`. */
+interface GlobalFacetResult {
+  truncated: boolean;
+  values: {
+    count: number;
+    value: unknown;
+  }[];
+}
+/**
+* Introspect `.global()` (D1-backed) tables for the data browser. Structurally
+* compatible with `@lunora/d1`'s `listGlobalTables` / `readGlobalTablePage` /
+* `facetGlobalColumn` (curried with the D1 exec + schema) — the runtime stays
+* free of a hard dependency on the D1 package.
+*/
+interface GlobalIntrospector {
+  facetColumn: (options: {
+    column: string;
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    table: string;
+  }) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: {
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    offset?: number;
+    table: string;
+  }) => Promise<GlobalTablePage>;
+}
+/**
+* One vector index as the studio's vector browser lists it: the static schema
+* metadata (name/table/field/dimensions/metric/metadata) merged with the live
+* Vectorize `describe()` stats (`vectorsCount`, processing watermark) when the
+* binding is reachable. The live fields are optional so a never-bound index
+* still lists with its declared shape.
+*/
+interface VectorIndexSummary {
+  dimensions?: number;
+  field?: string;
+  metadata?: ReadonlyArray<string>;
+  metric?: "cosine" | "dot-product" | "euclidean";
+  name: string;
+  /** Most recent mutation Vectorize has finished indexing, from `describe()`. */
+  processedUpToMutation?: string;
+  table: string;
+  /** Live vector count from `describe()`; absent when the binding is unreachable. */
+  vectorsCount?: number;
+}
+/** One nearest-neighbour hit from a vector-index similarity query. */
+interface VectorQueryMatch {
+  id: string;
+  metadata?: Record<string, unknown>;
+  score: number;
+}
+/**
+* Introspect Vectorize indexes for the studio's vector browser. Built in the
+* worker entry from the generated `LUNORA_VECTOR_INDEXES` registry (Vectorize
+* cannot enumerate indexes at runtime) paired with the env bindings + the
+* schema's per-index embedders. `queryIndex` is optional: an index with no
+* embedder (a `select`-derived Shape B index, or a deployment that withholds the
+* embedder) lists but cannot be similarity-queried from the studio.
+*/
+interface VectorIntrospector {
+  listIndexes: () => Promise<VectorIndexSummary[]>;
+  queryIndex?: (options: {
+    name: string;
+    text: string;
+    topK?: number;
+  }) => Promise<{
+    matches: VectorQueryMatch[];
+  }>;
+}
+/**
+* Cron controller handed to the worker's `scheduled()` entry by the Workers
+* runtime. `cron` is the exact trigger expression that fired (matched against
+* {@link WorkerOptions.crons} keys and {@link WorkerOptions.backupCron});
+* `scheduledTime` is the firing time in epoch-ms, used as the backup id so the
+* snapshot is named after the moment it represents rather than wall-clock skew.
+*/
+interface ScheduledControllerLike {
+  cron: string;
+  noRetry?: () => void;
+  scheduledTime: number;
+}
+/**
+* A cron-trigger handler registered on {@link WorkerOptions.crons}. The worker's
+* `scheduled()` entry invokes the handler whose map key equals the firing
+* trigger's `cron` expression. Runs server-side with no end-user identity.
+*/
+type CronHandler = (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void> | void;
+/**
+* A Cloudflare Queues push-consumer handler — the worker's `queue()` entry
+* forwards each delivered `MessageBatch` (typed `unknown` here to keep the
+* runtime decoupled from `@lunora/queue`'s structural batch type).
+*/
+type QueueConsumerHandler = (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
+/**
+* A single code-defined cron job, shaped like an entry of the generated
+* `LUNORA_CRONS` map. `functionPath` is the `"namespace:fn"` to run, `args` its
+* bound arguments, and `name` the human label from the `cronJobs()` builder.
+* Pass the whole `LUNORA_CRONS` map as {@link WorkerOptions.cronJobs}; the worker
+* dispatches each job on its firing trigger via the same authorized shard path
+* as the scheduler.
+*/
+interface CronJobDispatch {
+  args?: Record<string, unknown>;
+  functionPath?: string;
+  name: string;
+  shardKey?: string;
+  /**
+  * Set when the job targets a durable workflow instead of a function: the
+  * `WORKFLOW_*` binding name on `env`. On a firing trigger the worker starts a
+  * NEW workflow instance (the {@link CronJobDispatch.args} become its
+  * `params`) rather than dispatching {@link CronJobDispatch.functionPath} to a
+  * shard. Mutually exclusive with `functionPath`.
+  */
+  workflow?: string;
+}
+/**
+* One scheduled cron invocation as the discovery endpoint surfaces it: a
+* {@link CronJobDispatch} flattened together with the `cron` expression that
+* fires it. Cloudflare exposes no runtime cron introspection, so the injected
+* `cronJobs` map is the only source of truth; the studio renders these read-only.
+*/
+interface CronJobInfo {
+  args?: Record<string, unknown>;
+  /** The compiled cron expression, e.g. `"0 9 * * *"`. */
+  cron: string;
+  functionPath?: string;
+  name: string;
+  shardKey?: string;
+  /** The `WORKFLOW_*` binding name when the job starts a durable workflow instead of a function. */
+  workflow?: string;
+}
+/**
+* R2-like sink for scheduled backups. Structurally a subset of `@lunora/storage`'s
+* `R2BucketLike` (and of the raw R2 binding), so passing `env.BACKUPS` straight
+* through satisfies it. `put` writes the NDJSON snapshot and its manifest
+* sidecar; `list`/`delete` drive retention pruning when
+* {@link WorkerOptions.backupRetain} is set.
+*/
+interface BackupStore {
+  delete: (key: string) => Promise<unknown>;
+  list: (options?: {
+    cursor?: string;
+    limit?: number;
+    prefix?: string;
+  }) => Promise<{
+    cursor?: string;
+    objects: ReadonlyArray<{
+      key: string;
+    }>;
+    truncated?: boolean;
+  }>;
+  put: (key: string, body: ArrayBuffer | Blob | null | ReadableStream | string, options?: {
+    customMetadata?: Record<string, string>;
+    httpMetadata?: {
+      contentType?: string;
+    };
+  }) => Promise<unknown>;
+}
+/**
+* Manifest sidecar written next to each scheduled backup's NDJSON object (at
+* `&lt;file>.manifest.json`). Mirrors the manifest entry the CLI records for local
+* backups so both backup planes describe a snapshot the same way;
+* `cron`/`scheduledTime` additionally record which trigger produced it.
+*/
+interface BackupManifest {
+  bytes: number;
+  createdAt: string;
+  cron: string;
+  file: string;
+  id: string;
+  rows: number;
+  scheduledTime: number;
+  tables?: string;
+}
+interface WorkerOptions {
+  /**
+  * An additional, async authorization gate for the `/_lunora/admin/*` plane
+  * (the Studio's HTTP + WS endpoints), OR-ed with the static {@link WorkerOptions.adminToken}
+  * bearer. When it resolves `true` for a request, that request is treated as
+  * admin-authorized even without the bearer; when it resolves `false` (or is
+  * unset) the bearer remains the only path. Evaluated once per admin request
+  * and never on the RPC/WebSocket data hot path.
+  *
+  * The intended producer is `@lunora/cloudflare-access`'s `accessAdminGate(...)`,
+  * which verifies the request's `Cf-Access-Jwt-Assertion` JWT and applies an
+  * `isAdmin(claims)` predicate — so the Studio can sit behind Cloudflare Access
+  * instead of (or alongside) a shared admin token. It takes only the request
+  * (verification needs static team-domain/aud config + the remote JWKS, no env
+  * binding), so it composes without threading async through every admin route.
+  */
+  adminGate?: (request: Request) => boolean | Promise<boolean>;
+  /**
+  * Admin bearer token expected by the export/import endpoints. When unset,
+  * the endpoints respond with `ADMIN_FORBIDDEN` — the same posture the
+  * per-shard admin gate uses.
+  */
+  adminToken?: string;
+  /**
+  * Acknowledge — explicitly — that sharded and fan-out access may be
+  * exercised by any caller (including unauthenticated ones) because no
+  * authorization callback is configured. When neither {@link WorkerOptions.authorizeShard}
+  * nor {@link WorkerOptions.authorizeFanOut} is set, naming a non-default shard or sending
+  * a fan-out envelope is authorization-open: this is the historical posture,
+  * preserved for backward compatibility. The runtime emits a single loud
+  * `console.warn` the first time such a request is seen so the gap is
+  * visible in logs. Set this to `true` to assert the posture is intentional
+  * and silence that warning. It does NOT change behaviour — it is purely an
+  * acknowledgement flag — and has no effect once an `authorize*` callback is
+  * configured.
+  */
+  allowUnauthenticatedShardAccess?: boolean;
+  /**
+  * Replay `.global()` (D1) CDC changes for the admin apply endpoint
+  * (point-in-time recovery). When omitted, apply covers only shard-local tables.
+  */
+  applyGlobals?: GlobalCdcApplyFunction;
+  /**
+  * The auth user-management plane backing the studio's users dashboard:
+  * browse via `GET /_lunora/admin/auth/users` + `/sessions`, and (when the
+  * implementation provides the optional mutations) create/ban/role/revoke/
+  * delete/impersonate via the matching admin-gated `POST /_lunora/admin/auth/*`
+  * routes. Wire it with `@lunora/auth`'s `createAuthAdmin(auth)`. Omit it and
+  * every `/auth/*` endpoint responds `AUTH_NOT_CONFIGURED`.
+  */
+  authAdmin?: AuthAdmin;
+  /**
+  * Base path the auth routes are mounted under (default `/api/auth`). Used
+  * to classify which inbound paths are auth ATTEMPTS for the app-level
+  * auth-failure SLO signal (PLAN3 §2.3) — see {@link WorkerOptions.authHandler}.
+  * Only meaningful alongside `authHandler`.
+  */
+  authBasePath?: string;
+  /**
+  * Optional prebound `@lunora/auth` handler (`handleAuthRequest(auth, …)`
+  * with its `auth` argument already bound) the worker dispatches BEFORE its
+  * own routing — auth runs as a top-level `/api/auth/*` route, not through
+  * lunora functions. It returns a `Response` for an auth route and
+  * `undefined` to let the request fall through to the worker.
+  *
+  * Wiring it here (rather than in the host entry) lets the runtime instrument
+  * it for the app-level auth-failure SLO (PLAN3 §2.3): after the handler
+  * answers a genuine auth ATTEMPT route (sign-in / sign-up / callback under
+  * {@link WorkerOptions.authBasePath}), the worker fires a fire-and-forget
+  * `recordAuthEvent` against the root shard via `ctx.waitUntil` — classifying
+  * the outcome by status (`≥ 400` ⇒ `fail`). The recording never blocks or
+  * fails the auth response, and is skipped silently when no admin token or
+  * shard namespace is configured (the SLO signal is simply absent).
+  *
+  * Omit it and the host keeps calling `handleAuthRequest` itself; the SLO
+  * signal is then absent but auth behaves identically.
+  */
+  authHandler?: (request: Request) => Promise<Response | undefined>;
+  /**
+  * @deprecated Use {@link WorkerOptions.authAdmin} (an {@link AuthAdmin}),
+  * which also lights up the user-management mutation endpoints. Still honored
+  * as a read-only fallback for the browse endpoints.
+  */
+  authIntrospector?: AuthIntrospector;
+  /**
+  * Optional table-level authorization callback for fan-out RPC envelopes.
+  * Called after `resolveIdentity` and before `coordinator.fanOut` walks
+  * the registry. Returning `false` rejects the request with 403
+  * `FORBIDDEN_FANOUT`. When unset, fan-out is denied by default
+  * whenever {@link WorkerOptions.authorizeShard} is configured — fan-out is a
+  * privileged operation (it dispatches the caller's function across
+  * every live shard for the table) and a per-shard gate is not
+  * sufficient to authorize it. Apps that need client-driven fan-out
+  * must opt in explicitly via this callback.
+  */
+  authorizeFanOut?: (identity: ResolvedIdentity | null, table: string, functionPath: string) => boolean | Promise<boolean>;
+  /**
+  * Optional per-shard authorization callback. Called from both the RPC
+  * dispatch path and the WebSocket upgrade path after `resolveIdentity`
+  * has produced an identity but before the request is forwarded to the
+  * named shard. Returning `false` (or a promise resolving to `false`)
+  * causes the runtime to reject the request with a 403
+  * `FORBIDDEN_SHARD` error. When unset, the runtime allows the
+  * request — preserving the historical "any client may name any
+  * shard" posture.
+  *
+  * Note: this callback does NOT gate fan-out envelopes — fan-out
+  * targets every live shard for a table and must be authorized at the
+  * table level via {@link WorkerOptions.authorizeFanOut}. Configuring this callback
+  * without `authorizeFanOut` causes fan-out envelopes to be denied by
+  * default.
+  */
+  authorizeShard?: (identity: ResolvedIdentity | null, shardKey: string) => boolean | Promise<boolean>;
+  /**
+  * Cron expression that triggers the built-in backup. When set alongside
+  * {@link WorkerOptions.backupStore} and {@link WorkerOptions.adminToken}, the
+  * worker's `scheduled()` entry runs a full export and writes an NDJSON
+  * snapshot + manifest sidecar to the backup store whenever a cron trigger
+  * with this exact expression fires. Must match an entry in the worker's
+  * wrangler `triggers.crons` (and the string is compared verbatim). Omit it
+  * and no automatic backup runs.
+  */
+  backupCron?: string;
+  /**
+  * Key prefix the scheduled backup writes under (default `"backups/"`). The
+  * NDJSON object lands at `&lt;prefix>lunora-backup-&lt;id>.ndjson` and its manifest
+  * at the same key plus `.manifest.json`.
+  */
+  backupPrefix?: string;
+  /**
+  * Retention bound for scheduled backups: keep only the newest N snapshots
+  * under {@link WorkerOptions.backupPrefix}, pruning older NDJSON objects and
+  * their manifests after each run. Omit (or `0`) to keep every backup.
+  */
+  backupRetain?: number;
+  /**
+  * R2-like store the scheduled backup writes snapshots to. Pass the bound R2
+  * bucket (`env.BACKUPS`) directly — its shape satisfies {@link BackupStore}.
+  * Without it (or without {@link WorkerOptions.backupCron}) no automatic
+  * backup runs.
+  */
+  backupStore?: BackupStore;
+  /**
+  * Table allowlist for the scheduled backup. Omit to back up every table
+  * (shard-local + `.global()`). Mirrors the export endpoint's `tables`.
+  */
+  backupTables?: ReadonlyArray<string>;
+  /**
+  * Code-defined cron jobs keyed by cron expression — pass the generated
+  * `LUNORA_CRONS` map directly. On a firing trigger the worker runs every job
+  * listed under the matching expression by dispatching its `functionPath`/`args`
+  * to the shard, server-side, through the same authorization as the scheduler.
+  * Runs alongside any {@link WorkerOptions.crons} handler and the backup.
+  */
+  cronJobs?: Record<string, ReadonlyArray<CronJobDispatch>>;
+  /**
+  * Cron-trigger handlers keyed by their exact cron expression. The worker's
+  * `scheduled()` entry dispatches the handler whose key equals the firing
+  * trigger's `cron`. Independent of the built-in backup — a handler keyed on
+  * the same expression as {@link WorkerOptions.backupCron} runs alongside it.
+  */
+  crons?: Record<string, CronHandler>;
+  /**
+  * D1 binding for `.global()` tables. Currently unused by the routing
+  * layer; downstream packages will read it from `env.DB` directly.
+  */
+  d1?: unknown;
+  /** Default shard key used when an envelope omits one. */
+  defaultShardKey?: string;
+  /**
+  * Stream `.global()` rows for the admin export endpoint. When omitted,
+  * the export endpoint covers only shard-local tables.
+  */
+  exportGlobals?: GlobalExportFunction;
+  /**
+  * The generated `LUNORA_FUNCTIONS` map (from `_generated/functions.ts`). When
+  * set, the worker exposes the admin-gated `GET /_lunora/admin/functions`
+  * endpoint the studio uses to auto-discover queries/mutations/actions
+  * (internal functions are filtered out). Omit it and the endpoint responds
+  * `FUNCTIONS_NOT_CONFIGURED`.
+  */
+  functions?: FunctionRegistryLike;
+  /**
+  * Read-only introspector for `.global()` (D1) tables, backing the data
+  * browser's global mode via `GET /_lunora/admin/global/tables` and
+  * `/_lunora/admin/global/table`. Build it from `@lunora/d1`'s
+  * `listGlobalTables` / `readGlobalTablePage`. Omit it and those endpoints
+  * respond `GLOBALS_NOT_CONFIGURED`.
+  */
+  globalIntrospector?: GlobalIntrospector;
+  /**
+  * Router for HTTP actions (`httpRouter()` from `@lunora/server`, a hono app).
+  * Consulted for requests that miss the explicit {@link WorkerOptions.routes}
+  * map and the internal `/_lunora/*` endpoints. The runtime builds the action
+  * context, injects it on the `__lunoraCtx` env binding, and dispatches via
+  * `httpRouter.fetch`; matched handlers reach the data layer through
+  * `ctx.run*`, which forward to the shard. An unmatched request returns hono's
+  * own 404 (a path-match with the wrong verb is a 404, not a 405).
+  */
+  httpRouter?: HttpRouterLike;
+  /**
+  * Insert `.global()` rows for the admin import endpoint. When omitted,
+  * rows targeting global tables are reported as hard errors.
+  */
+  importGlobals?: GlobalImportFunction;
+  /**
+  * Restrict every Durable Object this worker reaches — shard DOs, the
+  * scheduler DO, the fan-out coordinator, subscriptions — to a Cloudflare
+  * data-residency jurisdiction (`"eu"`, `"us"`, `"fedramp"`). The runtime
+  * derives a jurisdiction-pinned subnamespace from {@link WorkerOptions.shardDO}
+  * and {@link WorkerOptions.schedulerDO} once, so all routing inherits it.
+  *
+  * Fail-closed: if the bound namespace does not expose `.jurisdiction()`
+  * (an older `@cloudflare/workers-types`), the worker throws rather than
+  * silently routing to the un-pinned global namespace. Omit it for the
+  * default, un-pinned behaviour.
+  *
+  * ⚠️ Set once, before the first deploy — changing it strands data. A DO name
+  * maps to a *different* ID per jurisdiction, so toggling this on an existing
+  * deployment makes every shard/scheduler call resolve to a new, empty DO; the
+  * prior data stays in the old jurisdiction and is unreachable (no in-place
+  * migration). Usually set via the schema's `.jurisdiction(...)`, which codegen
+  * threads here.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /**
+  * Optional telemetry sink. When supplied, the worker emits one
+  * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
+  * with duration / ok / error / shardKey or fanOut metadata. Sink
+  * throws are swallowed so a faulty adapter cannot break user-facing
+  * dispatch. See {@link ObservabilitySink}.
+  */
+  observability?: ObservabilitySink;
+  /**
+  * The generated OpenAPI 3.1 document. Import it from the codegen-emitted
+  * module and pass it through:
+  * `import { openApiSpec } from "./lunora/_generated/openapi"`. A Worker can't
+  * read the `_generated/openapi.json` file at runtime, so codegen also emits
+  * `openapi.ts` (the same document inlined as `export const openApiSpec`) for
+  * exactly this wiring — it regenerates on every `lunora/` change so the spec
+  * stays live.
+  *
+  * When set, the worker exposes the admin-gated `GET /_lunora/admin/openapi`
+  * endpoint the studio's API-reference view renders. The runtime does
+  * NOT assemble or validate the spec — it serves what the host injects verbatim.
+  * Omit it and the endpoint returns an empty-but-valid OpenAPI 3.1 document
+  * (no paths), so the studio shows a "not configured" state rather than erroring.
+  */
+  openApiSpec?: unknown;
+  /**
+  * The generated OpenRPC 1.x document. Import it from the codegen-emitted
+  * module and pass it through:
+  * `import { openRpcSpec } from "./lunora/_generated/openrpc"` (only emitted
+  * when the project opts into `apiSpec: "openrpc"` or `"both"`). Like
+  * `openApiSpec`, codegen inlines the document into `openrpc.ts` because a
+  * Worker can't read the `.json` at runtime; both regenerate together.
+  *
+  * When set, the worker exposes the admin-gated `GET /_lunora/admin/openrpc`
+  * endpoint the studio's API-reference view can render. OpenRPC is the
+  * RPC-native spec (a `methods` array over the JSON-RPC-shaped
+  * `POST /_lunora/rpc` transport); it covers only the RPC functions, not
+  * `httpRouter()` REST routes. The runtime does NOT assemble or validate the
+  * spec — it serves what the host injects verbatim. Omit it and the endpoint
+  * returns an empty-but-valid OpenRPC 1.x document (no methods), so the studio
+  * shows a "not configured" state rather than erroring.
+  */
+  openRpcSpec?: unknown;
+  /**
+  * When true, the runtime calls `ctx.passThroughOnException()` at the top
+  * of the fetch handler. Forwards uncaught exceptions to the origin
+  * instead of returning a synthetic 500.
+  */
+  passThroughOnException?: boolean;
+  /**
+  * Coordinator for cross-shard RPCs. When absent, envelopes with
+  * `fanOut` set are rejected with a 400. Construct via
+  * `createQueryCoordinator({ registry })`.
+  */
+  queryCoordinator?: QueryCoordinator;
+  /**
+  * Cloudflare Queues push-consumer handler — the worker's `queue(batch, …)`
+  * entry forwards every delivered `MessageBatch` here. Built by codegen from
+  * `lunora/queues.ts` (via `@lunora/queue`'s `dispatchQueueBatch`, which routes
+  * by `batch.queue` to the matching `defineQueue` handler), so the runtime
+  * stays decoupled from the queue package. Omitted when no push queues exist.
+  */
+  queue?: QueueConsumerHandler;
+  /**
+  * Resolve the calling identity from the inbound RPC request. Called once
+  * per RPC (and per fan-out) before the request is forwarded to the
+  * shard. The returned `userId` becomes `ctx.auth.userId` on the shard
+  * side; remaining keys (`email`, role flags, etc.) are JSON-encoded and
+  * forwarded as `x-lunora-identity` so `ctx.auth.getIdentity()` can
+  * return them. Returning `null` (or omitting this option) means
+  * anonymous — no identity headers are injected.
+  */
+  resolveIdentity?: (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
+  /**
+  * Resolve a table's sharding metadata. Required by the import endpoint to
+  * bucket rows; when omitted, every row routes to the default shard.
+  */
+  resolveTableSharding?: AdminTableResolver;
+  /**
+  * Map of routes for custom HTTP handlers (auth callbacks etc.). Keys can
+  * be either `"METHOD path"` (e.g. `"GET /healthz"`) or just `"path"`
+  * (e.g. `"/healthz"`) — the runtime will match the more specific form
+  * first.
+  */
+  routes?: Record<string, Route>;
+  /**
+  * Namespace binding for the `SchedulerDO` (typically `env.SCHEDULER`). When
+  * set, the worker exposes the admin-gated `/_lunora/admin/scheduled`
+  * endpoints used by the studio to list and cancel `runAfter` / `runAt`
+  * jobs. Omit it and those endpoints respond `SCHEDULER_NOT_CONFIGURED`.
+  */
+  schedulerDO?: ShardNamespaceLike;
+  /**
+  * Named `SchedulerDO` instance the admin endpoints target. Must match the
+  * `instanceName` passed to `createScheduler` (both default to `default`).
+  */
+  schedulerInstanceName?: string;
+  /**
+  * Secure-by-default HTTP edge applied to every response the worker emits
+  * (RPC, auth, admin, `httpRoute` handlers, SSR fallback): baseline security
+  * headers, deny-by-default CORS, and a CSRF/origin guard. Every layer is on
+  * by default and individually opt-out — see {@link SecurityOptions}. Omit it
+  * to take the hardened defaults; set a field to `false` to relax that layer
+  * (e.g. `security: { cors: { allowedOrigins: ["https://app.example.com"] } }`).
+  */
+  security?: SecurityOptions;
+  /** Namespace binding for the shard Durable Object (typically `env.SHARD`). */
+  shardDO: ShardNamespaceLike;
+  /**
+  * Names of the storage buckets the studio's file browser offers in its bucket
+  * picker, backing `GET /_lunora/admin/storage/buckets`. Supply the keys of a
+  * multi-bucket `createBucketStorage({...})` so the operator can switch buckets;
+  * the selected name is forwarded to the storage ops as `options.bucket`. Omit
+  * it (single-bucket deployments) and the picker is hidden — the ops target the
+  * default bucket.
+  */
+  storageBuckets?: string[];
+  /**
+  * Deletes one object, backing the admin-gated `DELETE /_lunora/admin/storage`
+  * endpoint the studio's file browser calls. Passing
+  * `createStorage(...).delete` satisfies it. Omit it and the endpoint responds
+  * `STORAGE_DELETE_NOT_CONFIGURED` — the studio surfaces a clear inline error.
+  */
+  storageDelete?: StorageDeleteFunction;
+  /**
+  * Storage lister backing the admin-gated `GET /_lunora/admin/storage`
+  * endpoint the studio's file browser calls. The structural shape matches
+  * `@lunora/storage`'s `Storage["list"]`, so passing `createStorage(...).list`
+  * (or the raw R2 bucket's `list`) satisfies it. Omit it and the endpoint
+  * responds `STORAGE_NOT_CONFIGURED`.
+  */
+  storageList?: StorageListFunction;
+  /**
+  * Mints a (signed or public) URL for one object, backing the admin-gated
+  * `GET /_lunora/admin/storage/url` endpoint the studio's "copy URL" action
+  * calls. Passing `createStorage(...).getSignedUrl` (or `.getUrl`) satisfies
+  * it. Omit it and the endpoint responds `STORAGE_URL_NOT_CONFIGURED` — the
+  * studio surfaces a clear inline error.
+  */
+  storageSignedUrl?: StorageSignedUrlFunction;
+  /**
+  * Uploads one object, backing the admin-gated `PUT /_lunora/admin/storage`
+  * endpoint the studio's file browser calls. Passing `createStorage(...).upload`
+  * satisfies it. Omit it and the endpoint responds
+  * `STORAGE_UPLOAD_NOT_CONFIGURED` — the studio surfaces a clear inline error.
+  */
+  storageUpload?: StorageUploadFunction;
+  /**
+  * Page the `.global()` (D1) change-data-capture log for the admin sync
+  * endpoint. When omitted, the sync feed covers only shard-local tables.
+  */
+  syncGlobals?: GlobalCdcSyncFunction;
+  /**
+  * Read-only introspector for Vectorize indexes, backing the studio's vector
+  * browser via `GET /_lunora/admin/vector/indexes` and
+  * `POST /_lunora/admin/vector/query`. Build it from the generated
+  * `LUNORA_VECTOR_INDEXES` registry plus the env Vectorize bindings (and the
+  * schema's embedders, to enable similarity queries). Omit it and those
+  * endpoints respond `VECTORS_NOT_CONFIGURED`.
+  */
+  vectorIntrospector?: VectorIntrospector;
+  /**
+  * Resolver for the Cloudflare Workflows REST client, built from the
+  * deployment `env` (its `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN`).
+  * Set by the codegen-emitted worker entry (which depends on
+  * `@lunora/workflow`); when omitted, the `/_lunora/admin/workflows*` proxy
+  * reports "not configured" and the studio shows the credentials empty state.
+  */
+  workflowsClient?: (env: unknown) => undefined | WorkflowsRestClient;
+}
+interface RpcContext {
+  ctx: ExecutionContextLike;
+  env: unknown;
+  request: Request;
+  shardKey: string;
+}
+/**
+* The composed Lunora worker. `fetch` / `scheduled` are the standard Cloudflare
+* module-worker entrypoints (so the object can be re-exported directly as
+* `export default createWorker(...)`). `serverQuery` is the in-process fast-path
+* (PLAN4 §2.2) an SSR loader running inside the same worker calls to reach a
+* Lunora query without a self-`fetch` to `/_lunora/rpc`, with identity / RLS /
+* auth semantics identical to the HTTP path.
+*/
+interface LunoraWorker {
+  fetch: (request: Request, env: unknown, context: ExecutionContextLike) => Promise<Response>;
+  /**
+  * Cloudflare Queues consumer entry — present only when the app declares push
+  * queues. Forwards each delivered `MessageBatch` to the configured
+  * {@link WorkerOptions.queue} handler; a no-op when none is set.
+  */
+  queue?: (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
+  scheduled: (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void>;
+  /**
+  * In-process query/mutation dispatch for SSR loaders co-located in this
+  * worker. Resolves identity off `request` (cookies / bearer / bookmark) and
+  * runs the per-shard authorization gate exactly like `POST /_lunora/rpc`,
+  * then dispatches to the owning shard — no network self-fetch. Returns the
+  * raw shard {@link Response}, byte-identical to the HTTP path's, so callers
+  * can `.json()` it (`{ result }` / `{ error }`) or forward it verbatim. Like
+  * the worker's `fetch`, it never throws on a request fault: a denied auth
+  * gate, a bad reference, or a downstream error comes back as the SAME JSON
+  * error `Response` (`toErrorResponse`) the HTTP path returns.
+  * @param request The inbound SSR request — its `cookie` / `authorization`
+  * / `x-d1-bookmark` headers drive identity, exactly as the
+  * HTTP RPC path reads them.
+  * @param env The worker `env`, forwarded to `resolveIdentity`.
+  * @param reference A generated function reference (`api.foo.bar`); its
+  * `__lunoraRef` is the `"namespace:fn"` dispatched.
+  * @param args The function arguments.
+  * @param options Call options mirroring the RPC envelope.
+  * @param options.shardKey Routes to a specific shard (omitted → the worker's
+  * `defaultShardKey`).
+  */
+  serverQuery: (request: Request, env: unknown, reference: unknown, args?: Record<string, unknown>, options?: {
+    shardKey?: string;
+  }) => Promise<Response>;
+}
+/**
+* Build a Cloudflare Worker entry. Returns an object with `fetch` so it can
+* be re-exported directly as `export default createWorker(...)`.
+*/
+declare const createWorker: (options: WorkerOptions) => LunoraWorker;
+/**
+* Compose a meta-framework SSR handler and Lunora into a single Cloudflare
+* Worker (PLAN4 §1, §2.2). Thin sugar over {@link createWorker} — a
+* near-pass-through whose value is naming and a documented, framework-neutral
+* entrypoint, so a template reads cleanly:
+*
+* ```ts
+* import { composeWorker } from "@lunora/runtime";
+*
+* export default composeWorker({
+*   httpRouter: ssrHandler, // TanStack Start / React Router / SolidStart / …
+*   shardDO: env.SHARD,
+*   auth,
+* });
+* ```
+*
+* `httpRouter` is *any* meta-framework SSR handler — structurally an
+* {@link HttpRouterLike} (`{ fetch(request, env?, ctx?) }`). It is the
+* lowest-priority matcher: the worker dispatches auth (`/api/auth/*`), explicit
+* {@link WorkerOptions.routes}, and the reserved realtime endpoints
+* (`/_lunora/rpc`, `/_lunora/ws`, `/_lunora/admin/*`) first, then falls through
+* to `httpRouter.fetch` for everything else. An SSR render that throws is
+* contained at that seam and surfaced as a plain 500 — it can never take down
+* the realtime plane (see `dispatchHttpRoute`). The two flows share one worker
+* but never collide.
+*
+* The signature is identical to {@link createWorker}; pass exactly the same
+* options. Prefer this name in framework templates to make the composition
+* intent explicit.
+*/
+declare const composeWorker: (options: WorkerOptions) => LunoraWorker;
+/**
+* A meta-framework's emitted Cloudflare handler: either a bare `fetch` function
+* or a `{ fetch }` module object (optionally carrying its own `scheduled`). Every
+* class-B adapter output (`@sveltejs/adapter-cloudflare`, Nitro's
+* `cloudflare-module`, `@astrojs/cloudflare`) is structurally one of these.
+*/
+type FrameworkHostHandler = ((request: Request, env?: unknown, context?: ExecutionContextLike) => Promise<Response> | Response) | (HttpRouterLike & {
+  scheduled?: (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void> | void;
+});
+/** Lunora worker options for {@link withFrameworkWorker} — everything except `httpRouter` (supplied from the framework host). */
+type FrameworkWorkerOptions = Omit<WorkerOptions, "httpRouter">;
+/**
+* Either fixed {@link FrameworkWorkerOptions}, or a factory deriving them from the
+* per-request `env` — for bindings (like `env.SHARD` → `shardDO`) that only exist
+* at request time.
+*/
+type FrameworkWorkerOptionsInput = ((env: unknown) => FrameworkWorkerOptions) | FrameworkWorkerOptions;
+/**
+* Compose a meta-framework's Cloudflare Worker handler with Lunora's realtime
+* plane into one `{ fetch, scheduled }` Worker — the **single, shared** class-B
+* (own-CF-adapter, hook-injection) composer behind `@lunora/svelte/worker`,
+* `@lunora/vue/worker`, and `@lunora/astro`'s `withLunora` (PLAN4 §3). It wraps
+* the framework handler as {@link composeWorker}'s `httpRouter`, so the reserved
+* realtime endpoints (`/_lunora/rpc`, `/_lunora/ws`, `/_lunora/admin/*`) plus
+* auth/explicit `routes` go to Lunora and **everything else** delegates to the
+* framework. A framework render that throws is contained at the seam and
+* surfaced as a plain 500 — it can never take down the realtime plane.
+*
+* Owns the three behaviors the adapters otherwise each re-implemented (and
+* diverged on): (1) the host may be a bare `fetch` fn or a `{ fetch }` object;
+* (2) options may be a fixed object or an `(env) => options` factory, rebuilt per
+* request so per-request bindings wire in; (3) **`scheduled` preservation** — when
+* Lunora configures no cron surface, the framework host's own `scheduled` (if any)
+* is preserved rather than silently dropped; otherwise Lunora owns it (crons /
+* backup).
+* @param host The framework's emitted Cloudflare handler.
+* @param optionsInput Lunora options minus `httpRouter`, or an `(env) => options` factory.
+*/
+declare const withFrameworkWorker: (host: FrameworkHostHandler, optionsInput: FrameworkWorkerOptionsInput) => LunoraWorker;
+/**
+* Options for {@link createLunoraHandler}. Either an `(env) => options` factory
+* (full control — for bindings that only exist at request time), or a partial
+* {@link FrameworkWorkerOptions} object whose `shardDO` defaults to the
+* conventional `env.SHARD` binding. Pass nothing for the common case.
+*/
+type LunoraHandlerOptions = ((env: unknown) => FrameworkWorkerOptions) | Partial<FrameworkWorkerOptions>;
+/**
+* Resolve per-request Lunora worker options. A factory is called with the
+* request `env`; a partial object has its `shardDO` defaulted to `env.SHARD` so
+* the common case needs no configuration. Throws a clear error when no shard
+* namespace can be found — a wiring mistake, not a runtime condition to swallow.
+*/
+declare const resolveLunoraOptions: (options: LunoraHandlerOptions, env: unknown) => FrameworkWorkerOptions;
+/**
+* Build a framework-neutral request handler for Lunora's realtime plane
+* (`/_lunora/rpc`, `/_lunora/ws`, `/_lunora/admin/*`). This is the **one shared
+* seam** every web-standard framework integration mounts — Hono, Nitro/h3,
+* Elysia, or any WinterCG host running on Cloudflare Workers — so each is a
+* 1–2 line bridge (`(request, env, ctx) => Response`) rather than a bespoke
+* adapter package.
+*
+* Mount it under `/_lunora/*` (or whatever path you reserve) inside your app's
+* router; everything else stays your framework's. The host supplies, per
+* request: a Web `Request`, the Cloudflare `env` (carrying the `SHARD` Durable
+* Object namespace), and — when available — the `ExecutionContext`. The
+* `101 Switching Protocols` WebSocket-upgrade `Response` (with its `webSocket`)
+* is returned verbatim, so the framework streams the socket through unchanged.
+*
+* ```ts
+* // Hono
+* const lunora = createLunoraHandler();
+* app.use("/_lunora/*", (c) => lunora(c.req.raw, c.env, c.executionCtx));
+*
+* // Nitro / h3
+* const lunora = createLunoraHandler();
+* export default defineEventHandler((event) => {
+*   const { ctx, env } = event.context.cloudflare;
+*   return lunora(toWebRequest(event), env, ctx);
+* });
+* ```
+*
+* `shardDO` defaults to `env.SHARD`; pass `options` (or an `(env) => options`
+* factory) to add `auth`, `crons`, a `security` posture, or a custom namespace.
+* A new worker is composed per request because the options (and the `SHARD`
+* binding they default from) are only known once `env` arrives.
+* @param options Partial worker options (default `shardDO: env.SHARD`), or an `(env) => options` factory.
+*/
+declare const createLunoraHandler: (options?: LunoraHandlerOptions) => ((request: Request, env: unknown, context?: ExecutionContextLike) => Promise<Response>);
+/** Re-exported helper so callers can roundtrip envelopes in tests. */
+declare const defineRpcEnvelope: (envelope: RpcEnvelope) => RpcEnvelope;
+/**
+* Reader / counter capabilities, typed against the SAME canonical
+* `DatabaseWriterLike` the `@lunora/d1` ctx-db derives its `crossShardReader` /
+* `crossShardCounter` options from (`DatabaseWriterLike["findMany"]` /
+* `["count"]`) — so the pair drops straight into `createD1CtxDb` with no cast and
+* no structural drift. The import is type-only: `@lunora/runtime` keeps no hard
+* (value) dependency on `@lunora/do`.
+*/
+type CrossShardCounter = DatabaseWriterLike["count"];
+type CrossShardReader = DatabaseWriterLike["findMany"];
+interface CrossShardRelationOptions {
+  /**
+  * `fetch` used for the worker subrequest. Defaults to `globalThis.fetch`.
+  * Injectable so the in-DO loopback (or a test) can supply its own.
+  */
+  fetch?: typeof globalThis.fetch;
+  /** Forwarded identity claims (the `x-lunora-identity` envelope), when present. */
+  identity?: Record<string, unknown>;
+  /**
+  * Origin the worker is reachable at (`LUNORA_WORKER_ORIGIN`). The DO issues a
+  * loopback subrequest to `${origin}/_lunora/rpc`.
+  */
+  origin: string;
+  /** Forwarded user id (the `x-lunora-userid` header), when authenticated. */
+  userId?: string;
+}
+interface CrossShardRelationCapabilities {
+  crossShardCounter: CrossShardCounter;
+  crossShardReader: CrossShardReader;
+}
+/**
+* Build the `crossShardReader` / `crossShardCounter` pair for a single request,
+* wired to fan reverse-relation reads out across every shard via the worker's
+* coordinator. Pass the result straight into `createD1CtxDb`.
+*/
+declare const createCrossShardRelationCapabilities: (options: CrossShardRelationOptions) => CrossShardRelationCapabilities;
+/**
+* Conventional DO instance name. Kept in sync with `SHARD_REGISTRY_DO_NAME`
+* in `@lunora/do` (not imported to avoid the runtime → do dependency edge —
+* `@lunora/runtime` MUST stay free of a hard `@lunora/do` dep).
+*/
+declare const SHARD_REGISTRY_DO_NAME: string;
+/**
+* Default per-table cache TTL in milliseconds. 30s is a balance between
+* read amplification (a wide fan-out costs N registry round-trips at
+* minimum every 30s) and registration latency (newly registered shards
+* take up to 30s to participate in fan-outs).
+*/
+declare const DEFAULT_REGISTRY_CACHE_TTL_MS: number;
+interface DynamicShardRegistryOptions {
+  /**
+  * Override the in-process per-table cache TTL. Set to `0` to disable
+  * caching (every `listShardKeys` call hits the DO — useful only for
+  * tests).
+  */
+  cacheTtlMs?: number;
+  /**
+  * DO instance name. Defaults to {@link SHARD_REGISTRY_DO_NAME}. Override
+  * only if you run multiple isolated registries in one environment.
+  */
+  instanceName?: string;
+  /**
+  * Pin the registry DO to a Cloudflare data-residency jurisdiction. Pass the
+  * same value as the worker's `jurisdiction` so the registry co-locates with
+  * the shards it tracks. Omit for the un-pinned global namespace.
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /** DO namespace binding (`env.SHARD_REGISTRY`). */
+  namespace: ShardNamespaceLike;
+}
+/**
+* Extension of {@link ShardRegistry} with the mutator surface a worker
+* needs to register / unregister shard keys.
+*/
+interface DynamicShardRegistry extends ShardRegistry {
+  /** Drop the local cache. Pass a table to invalidate one entry; omit for everything. */
+  invalidate: (table?: string) => void;
+  /** Register a shard key as live for `table`. Idempotent. */
+  register: (table: string, shardKey: string) => Promise<void>;
+  /**
+  * Read the full `table → shardKeys` map. Useful for admin / debug UIs;
+  * not on the fan-out hot path.
+  */
+  snapshot: () => Promise<Record<string, ReadonlyArray<string>>>;
+  /** Remove a shard key from `table`'s live set. Idempotent. */
+  unregister: (table: string, shardKey: string) => Promise<void>;
+}
+declare const createDynamicShardRegistry: (options: DynamicShardRegistryOptions) => DynamicShardRegistry;
+interface LunoraErrorBody {
+  error: {
+    code: string;
+    message: string;
+  };
+}
+/**
+* Error type recognised by the runtime's error middleware. Anything thrown
+* that isn't a `LunoraError` is mapped to a generic 500 with code `INTERNAL`.
+*/
+declare class LunoraError extends Error {
+  readonly code: string;
+  readonly status: number;
+  constructor(message: string, options?: {
+    cause?: unknown;
+    code?: string;
+    status?: number;
+  });
+  toResponse(): Response;
+}
+/** Shape recognised by the runtime's structural error checks. */
+
+/** Convert any thrown value into a JSON error response. */
+declare const toErrorResponse: (error: unknown) => Response;
+/** Shared shape for sinks that can be limited to error events only. */
+interface OnlyErrorsOption {
+  /** When true, only events with `ok === false` are forwarded. */
+  onlyErrors?: boolean;
+}
+/**
+* A sink that logs each event via `console`.
+*
+* Useful as a zero-config default during development, or wired behind
+* {@link combineSinks} alongside a network sink. Successful events are logged
+* with `console.log`; error events (`ok === false`) with `console.error`.
+* @param options Sink options; set `onlyErrors` to log error events only.
+*/
+declare const consoleSink: (options?: OnlyErrorsOption) => ObservabilitySink;
+/** Options for {@link webhookSink}. */
+interface WebhookSinkOptions extends OnlyErrorsOption {
+  /**
+  * Extra headers merged onto the POST. `Content-Type: application/json` is
+  * set by default and may be overridden here (e.g. to add an
+  * `Authorization` / API-key header for Axiom, Datadog, etc.).
+  */
+  headers?: Record<string, string>;
+  /**
+  * Optional redaction hook applied to each event immediately before it is
+  * serialized and shipped. Use it to scrub or drop PII (e.g. strip
+  * `error.message`) before it leaves the worker. Return the (possibly
+  * modified) event to send, or `null`/`undefined` to drop the event
+  * entirely. A throwing `transform` drops the event (fail-closed) so a buggy
+  * redactor can never leak the un-scrubbed payload.
+  */
+  transform?: (event: ObservabilityEvent) => null | ObservabilityEvent | undefined;
+  /** The ingestion endpoint to POST each event to. */
+  url: string;
+}
+/**
+* A fire-and-forget sink that POSTs each event as JSON to an HTTP endpoint.
+*
+* This covers Axiom, Datadog, and any generic webhook/log-ingestion service —
+* point `url` at the ingestion endpoint and supply auth via `headers`. Each
+* event is sent as its own `fetch`. When the runtime supplies a per-event
+* `context.waitUntil` (the request's `ctx.waitUntil`), the send is registered
+* with it so it survives isolate teardown after the response returns; otherwise
+* it degrades to fire-and-forget. Either way its rejection is swallowed so a
+* flaky endpoint never surfaces to the caller.
+*
+* Privacy: the full event is serialized, including `error.message`, which may
+* contain user input. See the module-level note. Pass a `transform` callback to
+* scrub or drop fields before they leave the worker.
+* @param options Sink options: `url` is the POST target, `headers` are merged
+* request headers (e.g. an API key), `onlyErrors` ships error events only, and
+* `transform` redacts/drops each event before send.
+*/
+declare const webhookSink: (options: WebhookSinkOptions) => ObservabilitySink;
+/** Options for {@link sentrySink}. */
+interface SentrySinkOptions extends OnlyErrorsOption {
+  /**
+  * User-supplied capture callback. Wire this to your Sentry client, e.g.
+  * `(event) => Sentry.captureMessage(...)` or `captureException`. Kept as an
+  * injected callback so the runtime takes no dependency on `@sentry/*`.
+  */
+  capture: (event: ObservabilityEvent) => void;
+}
+/**
+* A thin adapter that forwards events to an injected `capture` callback.
+*
+* Intentionally does NOT bundle `@sentry/*`: the user wires their own Sentry
+* client (`captureException` / `captureMessage`) into `capture`, giving Sentry
+* parity without a hard dependency. The callback is invoked inside a try/catch
+* so a throwing client can't break dispatch.
+* @param options Sink options: `capture` is invoked per forwarded event;
+* `onlyErrors` defaults to true (error events only) — pass `false` for all.
+*/
+declare const sentrySink: (options: SentrySinkOptions) => ObservabilitySink;
+/** One Analytics Engine data point — the structural subset {@link analyticsEngineSink} writes. */
+interface AnalyticsEngineDataPointLike {
+  /** Free-form string dimensions (≤20, ≤5120 bytes total). */
+  blobs?: (null | string)[];
+  /** Numeric metrics (≤20). */
+  doubles?: number[];
+  /** Sampling key(s) — Analytics Engine accepts a single index (≤96 bytes). */
+  indexes?: (null | string)[];
+}
+/**
+* The Cloudflare Analytics Engine dataset binding surface this sink needs — the
+* `env` binding declared in `wrangler.jsonc` under `analytics_engine_datasets`.
+* Typed structurally so the runtime takes no dependency on
+* `@cloudflare/workers-types`.
+*/
+interface AnalyticsEngineDatasetLike {
+  writeDataPoint: (point: AnalyticsEngineDataPointLike) => void;
+}
+/** Options for {@link analyticsEngineSink}. */
+interface AnalyticsEngineSinkOptions extends OnlyErrorsOption {
+  /** The Analytics Engine dataset binding to write each event to. */
+  dataset: AnalyticsEngineDatasetLike;
+}
+/**
+* A sink that writes each event to a Cloudflare Analytics Engine dataset.
+*
+* Analytics Engine is the platform's unbounded-cardinality, sampled time-series
+* store — the natural backing for high-volume RPC observability metrics, queried
+* later over SQL. Prefer it over rolling your own counters table for anything
+* that doesn't need to be exact. Each event maps to one data point.
+*
+* indexes: `[functionPath]` — the sampling key, so Analytics Engine samples per
+* function rather than globally.
+*
+* blobs (string dimensions): `[functionPath, ok-or-error, shardKey, error.code,
+* fanOut.table]` — group/filter dimensions; absent fields are the empty string.
+*
+* doubles (numeric metrics): `[durationMs, errorCount, fanOut.shards,
+* fanOut.failed]` where errorCount is 0 or 1 — so `SUM(double2)` is the error
+* count and `AVG(double1)` the latency.
+*
+* `writeDataPoint` is fire-and-forget on the platform; the call is still wrapped
+* in a try/catch so a missing/throwing binding can never break dispatch.
+* @param options Sink options: `dataset` is the AE binding; `onlyErrors` writes
+* only error events (defaults to all events).
+*/
+declare const analyticsEngineSink: (options: AnalyticsEngineSinkOptions) => ObservabilitySink;
+/**
+* Combine several sinks into one that fans each event out to all of them.
+*
+* Each child sink is invoked in order; a throw from one does not prevent the
+* others from running (each call is individually guarded).
+* @param sinks The sinks to fan out to.
+*/
+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 AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, 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 ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, 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 StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };