@lunora/runtime 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/index.d.mts

@@ -1,31 +1,32 @@
 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.
-*/
+import { LunoraError as LunoraError$1, ErrorBody } from '@lunora/errors';
+/**
+ * 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>;
@@ -35,11 +36,11 @@ interface ConnectorChange {
   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).
-*/
+ * 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;
@@ -47,15 +48,15 @@ interface ConnectorSyncPage {
   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.
-*/
+ * 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;
@@ -85,38 +86,76 @@ type AirbyteMessage = {
   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.
-*/
+ * 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()`).
-*/
+ * 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 {
+  cache?: {
+    purge: (options: {
+      purgeEverything?: boolean;
+      tags?: string[];
+    }) => Promise<unknown>;
+  };
+  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`.
-*/
+ * 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;
@@ -153,10 +192,10 @@ interface AuthImpersonation {
   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`.
-*/
+ * 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;
@@ -164,6 +203,43 @@ interface AuthCapabilities {
   passkey: boolean;
   twoFactor: boolean;
 }
+/** One user-settable extra field for the create-user form, derived from the merged `user` table. */
+interface AuthUserFieldSpec {
+  name: string;
+  plugin?: string;
+  required: boolean;
+  type: "boolean" | "date" | "number" | "string";
+  unique: boolean;
+}
+/**
+ * Rich, read-only description of the deployment's auth configuration — enabled
+ * plugins, sign-in methods, user-settable fields, organization sub-features, and
+ * session / rate-limit policy — for the studio's config panel and dynamic
+ * create-user form. Never carries a secret.
+ */
+interface AuthConfigInfo {
+  capabilities: AuthCapabilities;
+  emailAndPassword: boolean;
+  organization: {
+    enabled: boolean;
+    roles: boolean;
+    teams: boolean;
+  };
+  plugins: string[];
+  rateLimit: {
+    enabled: boolean;
+    max?: number;
+    window?: number;
+  };
+  session: {
+    cookieCache?: boolean;
+    expiresIn?: number;
+    freshAge?: number;
+    updateAge?: number;
+  };
+  socialProviders: string[];
+  userFields: AuthUserFieldSpec[];
+}
 /** Filtering / paging options forwarded to {@link AuthAdmin.listUsers} from the users endpoint's query string. */
 interface ListAuthUsersOptions {
   filterField?: string;
@@ -176,18 +252,27 @@ interface ListAuthUsersOptions {
   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.
-*/
+ * 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 {
+  addMember?: (input: {
+    organizationId: string;
+    role?: string;
+    userId: string;
+  }) => Promise<Record<string, unknown>>;
+  addTeamMember?: (input: {
+    teamId: string;
+    userId: string;
+  }) => Promise<Record<string, unknown>>;
   banUser?: (input: {
     expiresInSeconds?: number;
     reason?: string;
@@ -197,6 +282,23 @@ interface AuthAdmin {
     invitationId: string;
   }) => Promise<void>;
   capabilities?: () => Promise<AuthCapabilities>;
+  config?: () => Promise<AuthConfigInfo>;
+  createOrganization?: (input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    ownerId?: string;
+    slug?: string;
+  }) => Promise<Record<string, unknown>>;
+  createOrgRole?: (input: {
+    organizationId: string;
+    permission: Record<string, string[]>;
+    role: string;
+  }) => Promise<Record<string, unknown>>;
+  createTeam?: (input: {
+    name: string;
+    organizationId: string;
+  }) => Promise<Record<string, unknown>>;
   createUser?: (input: {
     data?: Record<string, unknown>;
     email: string;
@@ -204,6 +306,12 @@ interface AuthAdmin {
     password?: string;
     role?: string | string[];
   }) => Promise<AuthUser>;
+  deleteOrganization?: (input: {
+    organizationId: string;
+  }) => Promise<void>;
+  deleteOrgRole?: (input: {
+    roleId: string;
+  }) => Promise<void>;
   deletePasskey?: (input: {
     passkeyId: string;
   }) => Promise<void>;
@@ -213,6 +321,12 @@ interface AuthAdmin {
   impersonateUser?: (input: {
     userId: string;
   }) => Promise<AuthImpersonation>;
+  inviteMember?: (input: {
+    email: string;
+    inviterId?: string;
+    organizationId: string;
+    role?: string;
+  }) => Promise<Record<string, unknown>>;
   listAccounts?: (input: {
     userId: string;
   }) => Promise<Record<string, unknown>[]>;
@@ -230,6 +344,11 @@ interface AuthAdmin {
     limit?: number;
     offset?: number;
   }) => Promise<AuthPage<Record<string, unknown>>>;
+  listOrgRoles?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
   listPasskeys?: (input: {
     userId: string;
   }) => Promise<Record<string, unknown>[]>;
@@ -238,10 +357,26 @@ interface AuthAdmin {
     offset?: number;
     userId?: string;
   }) => Promise<AuthPage<AuthSession>>;
+  listTeamMembers?: (options: {
+    limit?: number;
+    offset?: number;
+    teamId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
+  listTeams?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
   listUsers: (options: ListAuthUsersOptions) => Promise<AuthPage<AuthUser>>;
   removeMember?: (input: {
     memberId: string;
   }) => Promise<void>;
+  removeTeam?: (input: {
+    teamId: string;
+  }) => Promise<void>;
+  removeTeamMember?: (input: {
+    teamMemberId: string;
+  }) => Promise<void>;
   removeUser?: (input: {
     userId: string;
   }) => Promise<void>;
@@ -266,25 +401,36 @@ interface AuthAdmin {
     accountId: string;
     userId: string;
   }) => Promise<void>;
+  updateMemberRole?: (input: {
+    memberId: string;
+    role: string | string[];
+  }) => Promise<Record<string, unknown>>;
+  updateOrganization?: (input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    organizationId: string;
+    slug?: string;
+  }) => Promise<Record<string, unknown>>;
+  updateOrgRole?: (input: {
+    permission: Record<string, string[]>;
+    roleId: string;
+  }) => Promise<Record<string, unknown>>;
+  updateTeam?: (input: {
+    name: string;
+    teamId: string;
+  }) => Promise<Record<string, unknown>>;
   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.
-*/
+ * 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;
@@ -298,49 +444,364 @@ interface FunctionArgumentDescriptor {
   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.
-*/
+ * Identity resolved from the inbound request by `WorkerOptions.resolveIdentity`.
+ *
+ * The `userId` field is special — it becomes `ctx.auth.userId` inside the
+ * Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
+ * forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
+ *
+ * Return `null` to signal that the request is anonymous; the runtime will
+ * skip both `x-lunora-userid` and `x-lunora-identity` headers, and
+ * `ctx.auth.userId` will be `undefined` on the shard side.
+ */
+interface ResolvedIdentity {
+  /** Arbitrary additional claims. Must be JSON-serialisable. */
+  [key: string]: unknown;
+  /**
+   * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
+   * absent), the runtime forwards it as the socket's credential expiry — the
+   * DO drops the socket once it lapses. Used only on the WebSocket path.
+   */
+  exp?: number;
+  /**
+   * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
+   * both are present. Forwarded as the socket's expiry on the WebSocket path
+   * so the DO drops the socket once it lapses; omit for non-expiring sessions.
+   */
+  expiresAtMs?: number;
+  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
+  userId: string;
+}
+/**
+ * A verifier that turns an inbound request into a {@link ResolvedIdentity} (or
+ * `null` for anonymous). Structurally identical to `WorkerOptions.resolveIdentity`,
+ * so `.auth()`'s better-auth session resolver, a signed-preview-link verifier, a
+ * per-tenant bearer check, an upstream-JWT reader, … are all just `IdentityResolver`s
+ * — the identity layer is generic over every scheme, not coupled to any one.
+ */
+type IdentityResolver = (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
+/** Error policy for {@link composeIdentityResolvers} when a participant resolver throws. */
+type ComposeIdentityResolversErrorMode = "fail-closed" | "skip";
+/** Options for {@link composeIdentityResolvers}. */
+interface ComposeIdentityResolversOptions {
+  /**
+   * What to do when a resolver throws. `"fail-closed"` (default, safe)
+   * re-throws so a broken verifier fails the request rather than silently
+   * falling through to a weaker one; `"skip"` swallows the error and tries the
+   * next resolver (use only when a resolver's failure genuinely means "not my
+   * scheme").
+   */
+  readonly onError?: ComposeIdentityResolversErrorMode;
+}
+/**
+ * Compose several {@link IdentityResolver}s into one, first-match-wins: each is
+ * tried in order and the first that returns a non-null identity short-circuits.
+ * Generic over every scheme — the better-auth session resolver (obtained via the
+ * builder's `derived.resolveIdentity` escape hatch) is just one entry in the list,
+ * so composition never means losing it.
+ *
+ * A resolver that throws is handled per {@link ComposeIdentityResolversOptions.onError}
+ * (default `"fail-closed"`: the error propagates).
+ */
+declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
+/**
+ * A thin, generic helper over {@link composeIdentityResolvers} for the per-route case:
+ * pick a resolver by `new URL(request.url).pathname`. Keys are matched by longest
+ * path prefix; `"*"` is the fallback. Still fully generic — a route→resolver map,
+ * with no portal / preview / tenant concepts baked in (those live in the app's
+ * own resolvers).
+ * @example
+ * routeIdentityResolvers({ "/admin": adminResolver, "/partner": partnerResolver, "*": sessionResolver })
+ */
+declare const routeIdentityResolvers: (routes: Record<string, IdentityResolver>) => IdentityResolver;
+/** The result of validating a candidate identity against an {@link IdentityContractLike}. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
+/**
+ * Structural view of `@lunora/server`'s `IdentityContract` (from `defineIdentity`).
+ * Kept structural so `@lunora/runtime` stays free of an `@lunora/server` dependency.
+ * Keep the `onInvalid` union and `validate`/`IdentityValidation` shapes in sync with
+ * `@lunora/server`'s `IdentityContract` — they are projected by hand, not imported.
+ * The generated worker entry passes the app's `defineIdentity(...)` result here;
+ * the worker validates every resolver's returned claims against it at the trust
+ * boundary before they become `ctx.auth`.
+ */
+interface IdentityContractLike {
+  /** Reject policy applied when validation fails: downgrade to anonymous, or reject the request (401). */
+  readonly onInvalid: "anonymous" | "reject";
+  /** Validate resolver-returned claims against the declared contract. */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/** One KV namespace as the studio's KV browser surfaces it. */
+interface KvNamespaceSummary {
+  /** The wrangler/env binding name, e.g. `"MY_KV"`. */
+  binding: string;
+}
+/** One key entry as the KV admin browser surfaces it. */
+interface KvKeyEntry {
+  /** Absolute expiration (Unix seconds), when set. */
+  expiration?: number;
+  /** Per-key metadata set at write time, or absent when none. */
+  metadata?: unknown;
+  /** The key name. */
+  name: string;
+}
+/** A paginated page of KV keys as the admin browser returns it. */
+interface KvKeyListResult {
+  /** Opaque cursor for the next page; absent when the listing is complete. */
+  cursor?: string;
+  /** The keys on this page. */
+  keys: KvKeyEntry[];
+  /** True when this is the final page. */
+  listComplete: boolean;
+}
+/** A KV value together with its stored metadata. */
+interface KvValueResult {
+  /** Per-key metadata, or `null` when none. */
+  metadata: unknown;
+  /** The stored value as a string, or `null` when the key is absent. */
+  value: null | string;
+}
+/**
+ * The introspector the worker wires for the studio's KV browser. Build it from
+ * the env's bound KV namespaces. Omit it and the `/_lunora/admin/kv/*`
+ * endpoints respond `KV_NOT_CONFIGURED`.
+ */
+interface KvIntrospector {
+  /** Delete a key from a namespace. No-op when the key is absent. */
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  /** Read a value (as text) and its metadata from a namespace key. */
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResult>;
+  /** List keys in a namespace, optionally filtered by prefix and paginated. */
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResult>;
+  /** List the registered KV namespaces (binding names). */
+  listNamespaces: () => Promise<KvNamespaceSummary[]>;
+  /** Write a value (as text) with optional absolute expiration / relative TTL and metadata. */
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/**
+ * Shared, bundler-inlined helpers for the structured `fields` a
+ * `ctx.log.<level>(message, fields)` / `ctx.log.with(fields)` call carries.
+ *
+ * Inlined (like {@link file://./otlp.ts}) so `@lunora/do`, `@lunora/runtime`,
+ * `@lunora/config`, and `@lunora/studio` — which sit on different tiers with no
+ * acceptable runtime dependency edge between them — share ONE implementation of
+ * field rendering/normalization instead of the byte-identical copies they would
+ * otherwise hand-mirror. Keep this genuinely zero-dependency (only built-ins) so
+ * inlining into each `dist` stays sound.
+ */
+/** Structured, filterable key/value fields attached to a `ctx.log` line. */
+type LogFields = Record<string, unknown>;
+/**
+ * Severity of a `ctx.log.*` call. The five console method names (`log` is the
+ * default level, distinct from `info`) plus `trace`/`fatal`, so the logger spans
+ * the full OpenTelemetry severity ramp (`trace`→`fatal`).
+ */
+type ContextLogLevel = "debug" | "error" | "fatal" | "info" | "log" | "trace" | "warn";
+/**
+ * Per-event context handed to a sink alongside the event: lets a sink register
+ * background work (a telemetry POST, a durable pipeline send) with the request's
+ * `waitUntil` so it survives isolate teardown after the response returns. Absent
+ * `waitUntil` (no request context) means the sink falls back to fire-and-forget.
+ */
+interface LogSinkContext {
+  /** Keep a background promise alive past the response (the request's `waitUntil`). */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * One application log line emitted from a function handler via `ctx.log`.
+ * Produced per `ctx.log.*` call (unlike a per-dispatch RPC summary).
+ */
+interface LogEvent {
+  /** Raw arguments passed to the `ctx.log.*` call, in order. */
+  args: unknown[];
+  /**
+   * Structured fields the caller attached (`ctx.log.info(message, fields)` or a
+   * bound `ctx.log.with(fields)` child), already normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). Absent for a plain
+   * console-style call.
+   */
+  fields?: LogFields;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Display string — the message, or the console-style args rendered and space-joined. */
+  message: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Span id of the RPC this line was emitted under (trace correlation), or absent. */
+  spanId?: string;
+  /** Trace id this line belongs to (from the inbound `traceparent`), or absent. */
+  traceId?: string;
+  /** Wall-clock millis when the line was emitted. */
+  ts: number;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
+ *
+ * - `counter` — a monotonic delta to add up (requests, retries, bytes sent).
+ * - `gauge` — a point-in-time reading that replaces the last one (queue depth,
+ *   cache size).
+ * - `histogram` — a value whose *distribution* matters (latency, payload size),
+ *   giving percentiles rather than just a mean.
+ */
+type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * One measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
+ */
+interface MetricEvent {
+  /**
+   * Structured attributes the caller attached, normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
+   * dimensions — keep them low-cardinality; an id-valued attribute creates a
+   * distinct time series per id.
+   *
+   * Caller-controlled, so they MAY contain user input and they DO egress to
+   * whatever destination the sink ships to — the same caveat as a log line's
+   * `fields` and a span's `error.message`. Scrub upstream if that matters.
+   */
+  attributes?: LogFields;
+  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
+  functionPath: string;
+  /** Instrument kind; see {@link MetricKind}. */
+  kind: MetricKind;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Wall-clock millis when the measurement was recorded. */
+  ts: number;
+  /**
+   * The measured value: the increment for a `counter`, the current reading for
+   * a `gauge`, the observed sample for a `histogram`.
+   */
+  value: number;
+}
+/**
+ * One span produced by a `ctx.trace(name, fn)` call, or the synthetic root span
+ * the shard records for the dispatch itself so a waterfall has a bar to hang
+ * its children under.
+ *
+ * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
+ * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
+ * no reformatting.
+ */
+interface SpanEvent {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * Populated when the span body threw. `type` is the error's constructor name
+   * (or its `LunoraError` code); `message` is the human-readable string and may
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
+  error?: {
+    message: string;
+    type: string;
+  };
+  /**
+   * Function path the span was created under, e.g. `"messages:list"`. A span
+   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
+   * `runAction` carries the OUTER entrypoint's path, since the composed call
+   * reuses its context — the same attribution rule `ctx.log` follows.
+   */
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
+/**
+ * Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
+ * fan-outs set `fanOut` with the table being aggregated, shard count, and
+ * per-shard failure count.
+ */
 interface ObservabilityEvent {
   /** Wall-clock duration of the dispatch, in milliseconds. */
   durationMs: number;
   /**
-  * 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).
-  */
+   * 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).
-  */
+   * 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;
@@ -352,135 +813,152 @@ interface ObservabilityEvent {
   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.
-*/
+  /**
+   * W3C trace context for this dispatch, generated once at dispatch entry (32-
+   * and 16-hex). A sink (e.g. `otlpSink`) reuses these for the dispatch's span
+   * instead of minting fresh ids, and the runtime propagates them to the shard
+   * as a `traceparent` so a container the handler calls can stitch its spans
+   * under the same trace. Absent on paths that don't originate a trace (a sink
+   * falls back to random ids).
+   */
+  spanId?: string;
+  traceId?: string;
+}
+/**
+ * The `ctx.log` observability contract lives in `shared/` (inlined into each
+ * `dist`) so the DO that builds the events and the runtime sink that consumes
+ * them agree by construction rather than by hand-mirrored duplication. Re-exported
+ * here under the runtime's historical names.
+ *
+ * `LogLevel` is the canonical `ctx.log` severity union (the five console tiers
+ * plus `trace`/`fatal`); `ObservabilitySinkContext` is the shared per-event sink
+ * context (a `waitUntil` to keep a background send alive past the response).
+ */
+type LogLevel = ContextLogLevel;
+type ObservabilitySinkContext = LogSinkContext;
+/**
+ * The hook contract. Methods are optional so a sink can opt into only the
+ * events it cares about; the runtime no-ops the others.
+ */
 interface ObservabilitySink {
   /** Invoked once per `ctx.log.*` call from a function handler. */
   onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
+   * upstream, so counter values are deltas for the destination to sum.
+   */
+  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
   /** Invoked once per dispatched RPC (single-shard or fan-out). */
   onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.trace(name, fn)` span, when the span body settles.
+   * Distinct from `onRpc`: that is the one SERVER span per dispatch, this is the
+   * INTERNAL spans a handler creates beneath it.
+   */
+  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
 }
 /**
-* 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.
-*/
+ * 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.
-*/
+ * 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;
 /**
-* 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`.
-*/
+ * 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` 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.).
-*/
+ * 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).
-*/
+ * 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.
-*/
+ * 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";
 } | {
@@ -503,17 +981,17 @@ type MergeStrategy = {
   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}.
-*/
+ * 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";
@@ -531,11 +1009,11 @@ interface FanOutSpec {
   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.
-*/
+ * 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;
@@ -554,15 +1032,15 @@ interface FanOutResult<T = unknown> {
 }
 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.
-  */
+   * 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.
-  */
+   * 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;
@@ -575,16 +1053,16 @@ interface FanOutRequest {
   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.
-*/
+ * 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;
@@ -614,23 +1092,23 @@ interface MigrationFanOutResult {
   /** 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.
-  */
+   * 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.
-*/
+ * 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`. */
@@ -671,18 +1149,18 @@ interface ShardRankOutcome {
   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.
-*/
+ * 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;
@@ -729,78 +1207,78 @@ interface RankPageFanOutResult {
 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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).
-  */
+   * 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`).
-  */
+   * 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.
-*/
+ * 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 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. */
@@ -822,11 +1300,11 @@ interface ExportFanOutResult {
   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.
-*/
+ * 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>;
@@ -850,16 +1328,16 @@ interface CdcSyncFanOutResult {
   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.
-*/
+ * 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`.
-  */
+   * 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>;
@@ -904,10 +1382,10 @@ interface ImportFanOutResult {
   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.
-*/
+ * 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>>;
@@ -922,17 +1400,17 @@ interface ApplyCdcFanOutResult {
   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.
-*/
+ * 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. */
@@ -951,40 +1429,26 @@ interface ShardTrafficFanOutResult {
   /** 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.
-  */
+   * 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.
-  */
+   * `Content-Security-Policy`. Omitted (`undefined`) applies a restrictive
+   * `default-src 'none'` policy to **non-HTML** responses, and a conservative
+   * hardening policy to **HTML** responses (`base-uri 'none'; frame-ancestors
+   * 'self'; object-src 'none'`) — this does NOT set `default-src`/`script-src`,
+   * so it never blocks an SSR page's own scripts/styles/images/fetches, it only
+   * locks down the `base` element, framing (mirroring the `SAMEORIGIN`
+   * X-Frame-Options default), and legacy plugins. Pass a string to apply that
+   * exact 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;
@@ -1018,9 +1482,9 @@ interface CsrfOptions {
   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.
-*/
+ * 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;
@@ -1032,7 +1496,7 @@ interface SecurityOptions {
 interface ResolvedHeaders {
   coop: string | undefined;
   csp: {
-    htmlToo: boolean;
+    htmlValue: string | undefined;
     value: string;
   } | undefined;
   enabled: boolean;
@@ -1048,13 +1512,13 @@ interface ResolvedCors {
   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".
-  */
+   * 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;
 }
@@ -1069,86 +1533,88 @@ interface ResolvedSecurity {
   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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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).
-*/
+ * 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;
 }
-interface ExecutionContextLike {
-  passThroughOnException: () => void;
-  waitUntil: (promise: Promise<unknown>) => void;
-}
 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).
-*/
+ * 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;
   };
+  cache?: {
+    purge: (options: {
+      purgeEverything?: boolean;
+      tags?: string[];
+    }) => Promise<unknown>;
+  };
   fetch: typeof globalThis.fetch;
   runAction: <R>(reference: unknown, args?: Record<string, unknown>) => Promise<R>;
   runMutation: <R>(reference: unknown, args?: Record<string, unknown>) => Promise<R>;
@@ -1158,49 +1624,20 @@ 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.
-*/
+ * 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.
-*/
+ * 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: {
@@ -1209,15 +1646,15 @@ interface ShardingInfo {
   };
 }
 /**
-* 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.
-*/
+ * 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.
-*/
+ * 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<{
@@ -1225,10 +1662,10 @@ type GlobalExportFunction = (request: {
   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.
-*/
+ * 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;
@@ -1237,24 +1674,24 @@ type GlobalCdcSyncFunction = (request: {
   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.
-*/
+ * 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.
-*/
+ * 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>;
@@ -1283,11 +1720,11 @@ interface StorageObject {
   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.
-*/
+ * 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[];
@@ -1302,24 +1739,56 @@ 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.
-  */
+   * 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";
+  /**
+   * x402 payment tag set by the `.x402({ price })` builder modifier. Present
+   * only on paid public procedures; the origin worker answers an unpaid RPC
+   * for such a function with a real `402` challenge (via the injected
+   * {@link WorkerOptions.x402Charge} gate) before dispatching, then verifies +
+   * settles at the origin boundary so the shard never sees payment state.
+   * Rides along on the registered function object's identity — codegen casts
+   * the real `fn` into `LUNORA_FUNCTIONS`, so reading it needs no change to the
+   * generated shape (same as `fn.rls`).
+   */
+  x402?: {
+    readonly price: number | string;
+  };
 }
 /**
-* The generated `LUNORA_FUNCTIONS` dispatch table, narrowed to what the
-* discovery endpoint reads. Pass the map straight from `_generated/functions.ts`.
-*/
+ * 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.
-*/
+ * Injected x402 charge gate — the seam that paywalls a `.x402({ price })`-tagged
+ * procedure at the origin worker without the runtime importing `@lunora/x402`
+ * (which would pull viem/solana into every worker bundle). Build it with
+ * `createProcedureChargeGate(config)` from `@lunora/x402/charge` and pass it as
+ * {@link WorkerOptions.x402Charge}.
+ *
+ * Given the inbound `request`, the paid procedure's `spec` (its `functionPath` —
+ * used as the x402 challenge `resource` — and USD `price`), and a `dispatch`
+ * that runs the real shard forward, it returns a real `402` + `PAYMENT-REQUIRED`
+ * challenge when the request is unpaid, or the dispatched response (with
+ * `X-PAYMENT-RESPONSE` attached) once the client's `X-PAYMENT` is verified and
+ * settled. `dispatch` runs only after payment is verified — an unpaid or
+ * invalid request never reaches the shard.
+ */
+type X402ChargeGate = (request: Request, spec: {
+  functionPath: string;
+  price: number | string;
+}, dispatch: () => Promise<Response>) => Promise<Response>;
+/**
+ * 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;
@@ -1329,20 +1798,20 @@ type StorageListFunction = (prefix?: string, options?: {
   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).
-*/
+ * 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.
-*/
+ * 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;
@@ -1354,11 +1823,11 @@ type StorageUploadFunction = (key: string, body: ArrayBuffer, options?: {
   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"]`.
-*/
+ * 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;
@@ -1390,11 +1859,11 @@ interface GlobalFacetResult {
   }[];
 }
 /**
-* 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.
-*/
+ * 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;
@@ -1411,12 +1880,12 @@ interface GlobalIntrospector {
   }) => 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.
-*/
+ * 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;
@@ -1436,13 +1905,13 @@ interface VectorQueryMatch {
   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.
-*/
+ * 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: {
@@ -1454,51 +1923,57 @@ interface VectorIntrospector {
   }>;
 }
 /**
-* 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.
-*/
+ * 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.
-*/
+ * 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 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.
-*/
+ * 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`.
-  */
+   * 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.
-*/
+ * 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 * * *"`. */
@@ -1510,12 +1985,12 @@ interface CronJobInfo {
   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.
-*/
+ * 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?: {
@@ -1537,11 +2012,11 @@ interface BackupStore {
   }) => 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.
-*/
+ * 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;
@@ -1554,353 +2029,456 @@ interface BackupManifest {
 }
 interface WorkerOptions {
   /**
-  * 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.
-  */
+   * 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.
-  */
+   * Opt into an authorization-open posture for sharded and fan-out access.
+   *
+   * By default (this flag unset/`false`) the runtime FAILS CLOSED per
+   * operation: naming a non-default shard (a potential cross-tenant hop) is
+   * rejected with a `403` (`FORBIDDEN_SHARD`) unless
+   * {@link WorkerOptions.authorizeShard} is configured, and a fan-out
+   * envelope is rejected (`FORBIDDEN_FANOUT`) unless
+   * {@link WorkerOptions.authorizeFanOut} is. Set this to `true` to allow
+   * such requests from any caller (including unauthenticated ones) —
+   * appropriate only when every table is protected by per-row RLS. The
+   * runtime then emits a single `console.warn` so the open posture stays
+   * visible in logs. The flag is consulted per operation: it has no effect
+   * on an operation whose own `authorize*` callback is configured (that
+   * callback gates directly), but configuring only one of the two callbacks
+   * does NOT cover the other operation.
+   *
+   * NOTE: this is a behaviour change from earlier alphas, where the same
+   * situation was warn-once-then-allow. Apps that relied on client-chosen
+   * shard keys without an `authorize*` callback must set this flag explicitly.
+   */
   allowUnauthenticatedShardAccess?: boolean;
   /**
-  * Replay `.global()` (D1) CDC changes for the admin apply endpoint
-  * (point-in-time recovery). When omitted, apply covers only shard-local tables.
-  */
+   * 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`.
-  */
+   * 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`.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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`.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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`.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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 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.
-  */
+   * 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`.
-  */
+   * 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`.
-  */
+   * 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).
-  */
+   * 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.
-  */
+   * The declared identity claim contract (`defineIdentity(...)` from
+   * `@lunora/server`), passed by the generated worker entry. When present, the
+   * worker validates every `resolveIdentity` result against it at the trust
+   * boundary (on the public data paths — RPC / WebSocket / HTTP-action /
+   * server-query, never the admin path) *before* the claims become `ctx.auth`.
+   * A resolver output that violates the contract is downgraded to anonymous or
+   * rejected with a `401`, per the contract's `onInvalid`. Omitted → no
+   * validation, and the identity stays the historical untyped claim bag.
+   */
+  identity?: IdentityContractLike;
+  /**
+   * Insert `.global()` rows for the admin import endpoint. When omitted,
+   * rows targeting global tables are reported as hard errors.
+   */
   importGlobals?: GlobalImportFunction;
   /**
-  * 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}.
-  */
+   * 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;
+  /**
+   * Introspector for Workers KV namespaces, backing the studio's KV browser
+   * via `GET /_lunora/admin/kv/namespaces`, `GET /_lunora/admin/kv/keys`,
+   * `GET|PUT|DELETE /_lunora/admin/kv/value`. Build it from the env's bound
+   * KV namespaces with `createKvIntrospector` from `@lunora/bindings/kv`.
+   * Omit it and those endpoints respond `KV_NOT_CONFIGURED`.
+   */
+  kvIntrospector?: KvIntrospector;
+  /**
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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 })`.
-  */
+   * Coordinator for cross-shard RPCs. When absent, envelopes with
+   * `fanOut` set are rejected with a 400. Construct via
+   * `createQueryCoordinator({ registry })`.
+   */
   queryCoordinator?: QueryCoordinator;
   /**
-  * 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.
-  */
+   * 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;
+  /**
+   * Enforce the ephemeral WS admin token: when `true`,
+   * the worker's WS admin gate rejects the raw master admin token in the
+   * `?token=` query parameter — only a short-lived sub-token minted by
+   * `POST /_lunora/admin/ws-token` (or the master token in the
+   * `Authorization` HEADER, which never leaks via URLs) authorizes. Off by
+   * default (the master token in `?token=` keeps working); also settable per
+   * deployment via `env.LUNORA_REQUIRE_EPHEMERAL_WS_TOKEN`
+   * (`1`/`true`/`on`/`yes`/`enabled`), which the shard/relay Durable Objects
+   * honor for their own upgrade gate too. Flipping it on is the step that
+   * actually closes the URL/log leak — do so once every studio the
+   * deployment uses mints ephemeral tokens.
+   */
+  requireEphemeralWsToken?: boolean;
+  /**
+   * 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.
-  */
+   * 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.
-  */
+   * 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`.
-  */
+   * 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`).
-  */
+   * 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"] } }`).
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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`.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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`.
-  */
+   * 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.
-  */
+   * Voice-session Durable Object namespaces, keyed by the agent's
+   * `lunora/agents.ts` export name (e.g. `{ support: env.VOICE_SUPPORT }`).
+   * Codegen wires this for every voice-enabled agent. When set, the worker
+   * exposes `/_lunora/voice/&lt;agentExportName>` — a WebSocket upgrade that
+   * resolves the caller's identity, forwards it on the server-minted
+   * `x-lunora-userid` / `x-lunora-identity` headers, and hands the socket to
+   * the agent's `VoiceSessionDO`. Omit it (voice-free apps) and the route does
+   * not exist.
+   */
+  voiceAgents?: Record<string, ShardNamespaceLike>;
+  /**
+   * 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;
+  /**
+   * Injected x402 charge gate for paid (`.x402({ price })`) procedures. Build
+   * it with `createProcedureChargeGate(config)` from `@lunora/x402/charge` and
+   * pass it here; the runtime stays free of a hard `@lunora/x402` dependency
+   * (and its viem/solana deps).
+   *
+   * **Required whenever any registered function is `.x402()`-tagged.** The
+   * origin worker refuses to dispatch a paid procedure with a config error
+   * (`500`) when this is absent, rather than serving it free — the paywall is
+   * fail-closed by construction. See {@link X402ChargeGate}.
+   */
+  x402Charge?: X402ChargeGate;
 }
 interface RpcContext {
   ctx: ExecutionContextLike;
@@ -1909,140 +2487,195 @@ interface RpcContext {
   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.
-*/
+ * 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`).
-  */
+   * 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(...)`.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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`.
-*/
+ * 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` 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 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;
@@ -2052,70 +2685,88 @@ interface CrossShardRelationCapabilities {
   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`.
-*/
+ * 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).
-*/
+ * 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).
-*/
+ * 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).
-  */
+   * 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.
-  */
+   * 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.
-*/
+ * 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.
-  */
+   * 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: ErrorBody;
+}
+/**
+ * Convert any thrown value into a JSON error response.
+ *
+ * Delegates the envelope + redaction to `@lunora/errors`' {@link toErrorBody} —
+ * a non-internal `LunoraError` (from `@lunora/server`, this runtime, or the
+ * `@lunora/do` data layer) is echoed with its `code`/`message`/`hint`/`docsUrl`;
+ * an internal-coded error keeps its status but its message is redacted; anything
+ * else becomes a generic `INTERNAL` 500. All of these share the unified shape
+ * recognized by `isLunoraError`.
+ */
+declare const toErrorResponse: (error: unknown) => Response;
 /**
-* 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;
+ * Transport-level error for the worker entry. A thin ergonomic wrapper over the
+ * shared `@lunora/errors` `LunoraError` that keeps the runtime's historical
+ * `(message, { code, status })` signature — the runtime mints these with
+ * dispatch-specific codes (`METHOD_NOT_ALLOWED`, `*_NOT_CONFIGURED`, …) and an
+ * explicit status, so they don't need a central catalog entry. Because it is a
+ * real `LunoraError`, it carries the unified wire shape and is recognized by
+ * `isLunoraError` everywhere. Anything thrown that isn't a `LunoraError`
+ * is mapped to a generic 500 with code `INTERNAL`.
+ */
+declare class LunoraError extends LunoraError$1 {
   constructor(message: string, options?: {
     cause?: unknown;
     code?: string;
@@ -2123,82 +2774,94 @@ declare class LunoraError extends Error {
   });
   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.
-*/
+ * 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.).
-  */
+   * 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.
-  */
+   * 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;
+  /**
+   * Optional redaction hook for `ctx.log` events (the `transform`
+   * counterpart for log lines). Same fail-closed contract: return the event to
+   * ship it, `null`/`undefined` to drop it, and a throw drops it. When unset,
+   * log events are shipped as-is (message + structured fields — which may carry
+   * user input; see the privacy note).
+   */
+  transformLog?: (event: LogEvent) => LogEvent | null | 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.
-*/
+ * 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/*`.
-  */
+   * 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.
-*/
+  /**
+   * Optional callback for `ctx.log` events. Wire it to Sentry's structured
+   * logging or a breadcrumb, e.g. `(e) => Sentry.logger[e.level]?.(e.message,
+   * e.fields)`. Omit it to leave `ctx.log` lines out of Sentry entirely
+   * (capturing every log line would usually flood the project). Invoked inside
+   * a try/catch so a throwing client can't break the handler.
+   */
+  captureLog?: (event: LogEvent) => 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 {
@@ -2210,11 +2873,11 @@ interface AnalyticsEngineDataPointLike {
   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`.
-*/
+ * 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;
 }
@@ -2224,36 +2887,128 @@ interface AnalyticsEngineSinkOptions extends OnlyErrorsOption {
   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).
-*/
+ * 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.
-*/
+ * The Cloudflare Pipeline binding surface {@link pipelineLogSink} needs — the
+ * `env` binding declared in `wrangler.jsonc` under `pipelines`. Typed
+ * structurally (mirrors `@lunora/bindings/pipelines`' `PipelineBindingLike`) so
+ * the runtime takes no dependency on `@lunora/bindings` or `@cloudflare/workers-types`.
+ */
+interface PipelineLike {
+  /** Durably ingest a batch of records (buffered to R2, read back later with R2 SQL). */
+  send: (records: Record<string, unknown>[]) => Promise<void>;
+}
+/** Options for {@link pipelineLogSink}. */
+interface PipelineLogSinkOptions {
+  /** The Cloudflare Pipeline binding each log record is durably sent to. */
+  pipeline: PipelineLike;
+}
+/**
+ * A sink that durably persists each `ctx.log` line to a Cloudflare Pipeline
+ * (→ R2), so an app has a queryable log store WITHOUT the Cloud — read the
+ * archived records back with R2 SQL. This is the durable counterpart to the
+ * network {@link otlpSink}: where OTLP streams to a collector, this lands the
+ * structured record (message, level, function path, fields, trace ids, shard,
+ * user, timestamp) in object storage under the app's own account.
+ *
+ * Only `onLog` is implemented — RPC-span metrics belong in
+ * {@link analyticsEngineSink}. `Pipeline.send` is durable/fire-and-forget on the
+ * platform; the call is registered with the request's `context.waitUntil` when
+ * present (the DO threads its `state.waitUntil`) so the send survives isolate
+ * teardown, and every rejection is swallowed so a flaky pipeline never surfaces
+ * to the caller.
+ *
+ * Privacy: the persisted record carries `message` + structured `fields` (not the
+ * raw positional args). They may include user input — the R2 bucket is your own,
+ * but treat it as a log store and gate PII upstream if that is a concern.
+ * @param options Sink options: `pipeline` is the Cloudflare Pipeline binding.
+ */
+declare const pipelineLogSink: (options: PipelineLogSinkOptions) => ObservabilitySink;
+/** Options for {@link otlpSink}. */
+interface OtlpSinkOptions extends OnlyErrorsOption {
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g.
+   * `https://collector.example.com`). Following the OTel base-endpoint
+   * convention, the sink POSTs spans to `${endpoint}/v1/traces` and log
+   * records to `${endpoint}/v1/logs`; a trailing slash is tolerated.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every OTLP POST — typically an `Authorization`
+   * bearer plus the `x-lunora-deployment` / `x-lunora-org` correlation headers
+   * the platform injects at deploy. `Content-Type: application/json` is set by
+   * default and may be overridden here.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Value of the `service.name` resource attribute on every exported span and
+   * log — the logical service the telemetry belongs to. Defaults to `lunora`.
+   */
+  serviceName?: string;
+  /**
+   * Convenience bearer token: when set, an `Authorization: Bearer` header
+   * carrying it is added to every POST (overriding any authorization in
+   * `headers`). Mirrors the container exporter so the platform can inject the
+   * same `LUNORA_OTLP_TOKEN` into both. Leave unset for an unauthenticated collector.
+   */
+  token?: string;
+}
+/**
+ * A fire-and-forget sink that exports telemetry over OTLP-over-HTTP (JSON).
+ *
+ * This is the single, standard wire contract both the worker and (via the
+ * container exporter helper) container processes use, so telemetry from either
+ * side lands in the same collector. Each RPC dispatch becomes one OTLP **span**
+ * (`${endpoint}/v1/traces`) named after its `functionPath`, with start/end
+ * derived from `durationMs` and status OK/ERROR; each `ctx.log.*` line becomes
+ * one OTLP **log record** (`${endpoint}/v1/logs`). Spans and log records reuse
+ * the dispatch's `traceId`/`spanId` (minted at dispatch entry and propagated to
+ * the shard and any container as a `traceparent`), so a handler's logs, its RPC
+ * span, and the container spans beneath it all stitch into one trace; ids are
+ * only randomised on paths that carry no trace context.
+ *
+ * Like {@link webhookSink}, each export is its own `fetch`, registered with the
+ * request's `context.waitUntil` when present so it survives isolate teardown,
+ * and every rejection is swallowed so a flaky collector never surfaces to the
+ * caller.
+ *
+ * Privacy: spans carry `error.type`/`error.message` and logs carry the rendered
+ * `message`, which may include user input. Point `endpoint` only at a collector
+ * you trust, and gate PII upstream if that is a concern.
+ * @param options Sink options: `endpoint` is the collector base URL, `headers`
+ * are merged onto every POST (auth + correlation), `serviceName` sets the
+ * resource `service.name`, and `onlyErrors` exports error spans only.
+ */
+declare const otlpSink: (options: OtlpSinkOptions) => 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 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 LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, 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, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, type ListAuthUsersOptions, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MetricEvent, type MetricKind, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type SpanEvent, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };