@lunora/runtime 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -110,6 +110,38 @@ declare const toFivetranResponse: (page: ConnectorSyncPage, primaryKey?: Record<
 * @param emittedAt epoch-ms stamped on each `RECORD` (default `Date.now()`).
 */
 declare const toAirbyteMessages: (page: ConnectorSyncPage, emittedAt?: number) => AirbyteMessage[];
+/**
+* The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+* the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+* must outlive the response, and `passThroughOnException` for the top-level
+* error posture.
+*
+* It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+* runtime and `@lunora/nuxt` is a framework integration that intentionally does
+* not depend on `@lunora/runtime`'s worker types, yet both need this exact
+* shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+* inbound request to the user's composed worker. Each imports this file by
+* relative path and the bundler (packem/rollup) inlines it: no runtime
+* dependency edge is created, the helper is duplicated only in emitted output,
+* never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+* `shared/` — bundler-inlined source".
+*
+* Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+* supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+* non-Cloudflare preview, a unit test) may hand over a partial context or none
+* at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+* fall back to {@link NOOP_EXECUTION_CONTEXT}.
+*/
+interface ExecutionContextLike {
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* No-op `ExecutionContext` used when the host runtime didn't supply one (a
+* non-Cloudflare preview, or a unit test), so the worker's `fetch` always
+* receives a valid third argument.
+*/
+declare const NOOP_EXECUTION_CONTEXT: ExecutionContextLike;
 /** A timestamp as better-auth stores it: epoch-ms, an ISO string, or absent. */
 type AuthTimestamp = null | number | string;
 /**
@@ -420,6 +452,14 @@ declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: Observa
 */
 declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
 /**
+* Cloudflare Durable Object jurisdictions restrict where a DO runs and persists
+* data, for data-residency / compliance regimes (GDPR, FedRAMP, US data
+* residency). The set is open — Cloudflare adds values over time — so this is a
+* widening union rather than a closed enum.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
 * Structural projection of the bits of `DurableObjectNamespace` the runtime
 * needs. Real workers-types defines a much wider surface; this lets us pass
 * unit-test doubles without coupling to `@cloudflare/workers-types`.
@@ -437,10 +477,29 @@ interface ShardNamespaceLike {
     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;
 /**
@@ -1130,10 +1189,6 @@ interface RpcEnvelope {
   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
@@ -1472,6 +1527,12 @@ interface ScheduledControllerLike {
 */
 type CronHandler = (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void> | void;
 /**
+* A Cloudflare Queues push-consumer handler — the worker's `queue()` entry
+* forwards each delivered `MessageBatch` (typed `unknown` here to keep the
+* runtime decoupled from `@lunora/queue`'s structural batch type).
+*/
+type QueueConsumerHandler = (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
+/**
 * A single code-defined cron job, shaped like an entry of the generated
 * `LUNORA_CRONS` map. `functionPath` is the `"namespace:fn"` to run, `args` its
 * bound arguments, and `name` the human label from the `cronJobs()` builder.
@@ -1553,6 +1614,22 @@ interface BackupManifest {
   tables?: string;
 }
 interface WorkerOptions {
+  /**
+  * An additional, async authorization gate for the `/_lunora/admin/*` plane
+  * (the Studio's HTTP + WS endpoints), OR-ed with the static {@link WorkerOptions.adminToken}
+  * bearer. When it resolves `true` for a request, that request is treated as
+  * admin-authorized even without the bearer; when it resolves `false` (or is
+  * unset) the bearer remains the only path. Evaluated once per admin request
+  * and never on the RPC/WebSocket data hot path.
+  *
+  * The intended producer is `@lunora/cloudflare-access`'s `accessAdminGate(...)`,
+  * which verifies the request's `Cf-Access-Jwt-Assertion` JWT and applies an
+  * `isAdmin(claims)` predicate — so the Studio can sit behind Cloudflare Access
+  * instead of (or alongside) a shared admin token. It takes only the request
+  * (verification needs static team-domain/aud config + the remote JWKS, no env
+  * binding), so it composes without threading async through every admin route.
+  */
+  adminGate?: (request: Request) => boolean | Promise<boolean>;
   /**
   * Admin bearer token expected by the export/import endpoints. When unset,
   * the endpoints respond with `ADMIN_FORBIDDEN` — the same posture the
@@ -1742,6 +1819,27 @@ interface WorkerOptions {
   */
   importGlobals?: GlobalImportFunction;
   /**
+  * Restrict every Durable Object this worker reaches — shard DOs, the
+  * scheduler DO, the fan-out coordinator, subscriptions — to a Cloudflare
+  * data-residency jurisdiction (`"eu"`, `"us"`, `"fedramp"`). The runtime
+  * derives a jurisdiction-pinned subnamespace from {@link WorkerOptions.shardDO}
+  * and {@link WorkerOptions.schedulerDO} once, so all routing inherits it.
+  *
+  * Fail-closed: if the bound namespace does not expose `.jurisdiction()`
+  * (an older `@cloudflare/workers-types`), the worker throws rather than
+  * silently routing to the un-pinned global namespace. Omit it for the
+  * default, un-pinned behaviour.
+  *
+  * ⚠️ Set once, before the first deploy — changing it strands data. A DO name
+  * maps to a *different* ID per jurisdiction, so toggling this on an existing
+  * deployment makes every shard/scheduler call resolve to a new, empty DO; the
+  * prior data stays in the old jurisdiction and is unreachable (no in-place
+  * migration). Usually set via the schema's `.jurisdiction(...)`, which codegen
+  * threads here.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /**
   * Optional telemetry sink. When supplied, the worker emits one
   * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
   * with duration / ok / error / shardKey or fanOut metadata. Sink
@@ -1796,6 +1894,14 @@ interface WorkerOptions {
   */
   queryCoordinator?: QueryCoordinator;
   /**
+  * Cloudflare Queues push-consumer handler — the worker's `queue(batch, …)`
+  * entry forwards every delivered `MessageBatch` here. Built by codegen from
+  * `lunora/queues.ts` (via `@lunora/queue`'s `dispatchQueueBatch`, which routes
+  * by `batch.queue` to the matching `defineQueue` handler), so the runtime
+  * stays decoupled from the queue package. Omitted when no push queues exist.
+  */
+  queue?: QueueConsumerHandler;
+  /**
   * Resolve the calling identity from the inbound RPC request. Called once
   * per RPC (and per fan-out) before the request is forwarded to the
   * shard. The returned `userId` becomes `ctx.auth.userId` on the shard
@@ -1918,6 +2024,12 @@ interface RpcContext {
 */
 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
@@ -2019,6 +2131,55 @@ type FrameworkWorkerOptionsInput = ((env: unknown) => FrameworkWorkerOptions) |
 * @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;
 /**
@@ -2082,6 +2243,12 @@ interface DynamicShardRegistryOptions {
   * 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;
 }
@@ -2256,4 +2423,4 @@ declare const analyticsEngineSink: (options: AnalyticsEngineSinkOptions) => Obse
 */
 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 AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.d.ts

@@ -110,6 +110,38 @@ declare const toFivetranResponse: (page: ConnectorSyncPage, primaryKey?: Record<
 * @param emittedAt epoch-ms stamped on each `RECORD` (default `Date.now()`).
 */
 declare const toAirbyteMessages: (page: ConnectorSyncPage, emittedAt?: number) => AirbyteMessage[];
+/**
+* The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+* the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+* must outlive the response, and `passThroughOnException` for the top-level
+* error posture.
+*
+* It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+* runtime and `@lunora/nuxt` is a framework integration that intentionally does
+* not depend on `@lunora/runtime`'s worker types, yet both need this exact
+* shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+* inbound request to the user's composed worker. Each imports this file by
+* relative path and the bundler (packem/rollup) inlines it: no runtime
+* dependency edge is created, the helper is duplicated only in emitted output,
+* never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+* `shared/` — bundler-inlined source".
+*
+* Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+* supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+* non-Cloudflare preview, a unit test) may hand over a partial context or none
+* at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+* fall back to {@link NOOP_EXECUTION_CONTEXT}.
+*/
+interface ExecutionContextLike {
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* No-op `ExecutionContext` used when the host runtime didn't supply one (a
+* non-Cloudflare preview, or a unit test), so the worker's `fetch` always
+* receives a valid third argument.
+*/
+declare const NOOP_EXECUTION_CONTEXT: ExecutionContextLike;
 /** A timestamp as better-auth stores it: epoch-ms, an ISO string, or absent. */
 type AuthTimestamp = null | number | string;
 /**
@@ -420,6 +452,14 @@ declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: Observa
 */
 declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
 /**
+* Cloudflare Durable Object jurisdictions restrict where a DO runs and persists
+* data, for data-residency / compliance regimes (GDPR, FedRAMP, US data
+* residency). The set is open — Cloudflare adds values over time — so this is a
+* widening union rather than a closed enum.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
 * Structural projection of the bits of `DurableObjectNamespace` the runtime
 * needs. Real workers-types defines a much wider surface; this lets us pass
 * unit-test doubles without coupling to `@cloudflare/workers-types`.
@@ -437,10 +477,29 @@ interface ShardNamespaceLike {
     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;
 /**
@@ -1130,10 +1189,6 @@ interface RpcEnvelope {
   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
@@ -1472,6 +1527,12 @@ interface ScheduledControllerLike {
 */
 type CronHandler = (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void> | void;
 /**
+* A Cloudflare Queues push-consumer handler — the worker's `queue()` entry
+* forwards each delivered `MessageBatch` (typed `unknown` here to keep the
+* runtime decoupled from `@lunora/queue`'s structural batch type).
+*/
+type QueueConsumerHandler = (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
+/**
 * A single code-defined cron job, shaped like an entry of the generated
 * `LUNORA_CRONS` map. `functionPath` is the `"namespace:fn"` to run, `args` its
 * bound arguments, and `name` the human label from the `cronJobs()` builder.
@@ -1553,6 +1614,22 @@ interface BackupManifest {
   tables?: string;
 }
 interface WorkerOptions {
+  /**
+  * An additional, async authorization gate for the `/_lunora/admin/*` plane
+  * (the Studio's HTTP + WS endpoints), OR-ed with the static {@link WorkerOptions.adminToken}
+  * bearer. When it resolves `true` for a request, that request is treated as
+  * admin-authorized even without the bearer; when it resolves `false` (or is
+  * unset) the bearer remains the only path. Evaluated once per admin request
+  * and never on the RPC/WebSocket data hot path.
+  *
+  * The intended producer is `@lunora/cloudflare-access`'s `accessAdminGate(...)`,
+  * which verifies the request's `Cf-Access-Jwt-Assertion` JWT and applies an
+  * `isAdmin(claims)` predicate — so the Studio can sit behind Cloudflare Access
+  * instead of (or alongside) a shared admin token. It takes only the request
+  * (verification needs static team-domain/aud config + the remote JWKS, no env
+  * binding), so it composes without threading async through every admin route.
+  */
+  adminGate?: (request: Request) => boolean | Promise<boolean>;
   /**
   * Admin bearer token expected by the export/import endpoints. When unset,
   * the endpoints respond with `ADMIN_FORBIDDEN` — the same posture the
@@ -1742,6 +1819,27 @@ interface WorkerOptions {
   */
   importGlobals?: GlobalImportFunction;
   /**
+  * Restrict every Durable Object this worker reaches — shard DOs, the
+  * scheduler DO, the fan-out coordinator, subscriptions — to a Cloudflare
+  * data-residency jurisdiction (`"eu"`, `"us"`, `"fedramp"`). The runtime
+  * derives a jurisdiction-pinned subnamespace from {@link WorkerOptions.shardDO}
+  * and {@link WorkerOptions.schedulerDO} once, so all routing inherits it.
+  *
+  * Fail-closed: if the bound namespace does not expose `.jurisdiction()`
+  * (an older `@cloudflare/workers-types`), the worker throws rather than
+  * silently routing to the un-pinned global namespace. Omit it for the
+  * default, un-pinned behaviour.
+  *
+  * ⚠️ Set once, before the first deploy — changing it strands data. A DO name
+  * maps to a *different* ID per jurisdiction, so toggling this on an existing
+  * deployment makes every shard/scheduler call resolve to a new, empty DO; the
+  * prior data stays in the old jurisdiction and is unreachable (no in-place
+  * migration). Usually set via the schema's `.jurisdiction(...)`, which codegen
+  * threads here.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /**
   * Optional telemetry sink. When supplied, the worker emits one
   * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
   * with duration / ok / error / shardKey or fanOut metadata. Sink
@@ -1796,6 +1894,14 @@ interface WorkerOptions {
   */
   queryCoordinator?: QueryCoordinator;
   /**
+  * Cloudflare Queues push-consumer handler — the worker's `queue(batch, …)`
+  * entry forwards every delivered `MessageBatch` here. Built by codegen from
+  * `lunora/queues.ts` (via `@lunora/queue`'s `dispatchQueueBatch`, which routes
+  * by `batch.queue` to the matching `defineQueue` handler), so the runtime
+  * stays decoupled from the queue package. Omitted when no push queues exist.
+  */
+  queue?: QueueConsumerHandler;
+  /**
   * Resolve the calling identity from the inbound RPC request. Called once
   * per RPC (and per fan-out) before the request is forwarded to the
   * shard. The returned `userId` becomes `ctx.auth.userId` on the shard
@@ -1918,6 +2024,12 @@ interface RpcContext {
 */
 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
@@ -2019,6 +2131,55 @@ type FrameworkWorkerOptionsInput = ((env: unknown) => FrameworkWorkerOptions) |
 * @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;
 /**
@@ -2082,6 +2243,12 @@ interface DynamicShardRegistryOptions {
   * 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;
 }
@@ -2256,4 +2423,4 @@ declare const analyticsEngineSink: (options: AnalyticsEngineSinkOptions) => Obse
 */
 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 AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.mjs

@@ -1,13 +1,14 @@
 export { toAirbyteMessages, toFivetranResponse } from './packem_shared/toAirbyteMessages-DrHdplb4.mjs';
-export { composeWorker, createWorker, defineRpcEnvelope, withFrameworkWorker } from './packem_shared/composeWorker-BYHiNH_V.mjs';
+export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-BEv9IBWS.mjs';
 export { createCrossShardRelationCapabilities } from './packem_shared/createCrossShardRelationCapabilities-C0KOf7er.mjs';
-export { DEFAULT_REGISTRY_CACHE_TTL_MS, SHARD_REGISTRY_DO_NAME, createDynamicShardRegistry } from './packem_shared/createDynamicShardRegistry-BpCwo_mo.mjs';
+export { DEFAULT_REGISTRY_CACHE_TTL_MS, SHARD_REGISTRY_DO_NAME, createDynamicShardRegistry } from './packem_shared/DEFAULT_REGISTRY_CACHE_TTL_MS-ocax8v0n.mjs';
 export { LunoraError, toErrorResponse } from './packem_shared/LunoraError-CL0aOtpo.mjs';
-export { emitLogEvent, emitRpcEvent } from './packem_shared/emitRpcEvent-pEdtqAK8.mjs';
-export { analyticsEngineSink, combineSinks, consoleSink, sentrySink, webhookSink } from './packem_shared/consoleSink-DqEvrQs0.mjs';
-export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate } from './packem_shared/createQueryCoordinator-DbxC7iUz.mjs';
-export { resolveShard } from './packem_shared/resolveShard-DDkzWtrU.mjs';
+export { emitLogEvent, emitRpcEvent } from './packem_shared/emitLogEvent-pEdtqAK8.mjs';
+export { analyticsEngineSink, combineSinks, consoleSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-DqEvrQs0.mjs';
+export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate } from './packem_shared/createQueryCoordinator-Cbds9cUI.mjs';
+export { applyJurisdiction, resolveShard } from './packem_shared/applyJurisdiction-BkZtTkct.mjs';
 export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-DbISh_Wi.mjs';
+export { NOOP_EXECUTION_CONTEXT } from './packem_shared/NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
 
 const VERSION = "0.0.0";
 

package/dist/packem_shared/{createDynamicShardRegistry-BpCwo_mo.mjs → DEFAULT_REGISTRY_CACHE_TTL_MS-ocax8v0n.mjs}

@@ -1,3 +1,5 @@
+import { applyJurisdiction } from './applyJurisdiction-BkZtTkct.mjs';
+
 const SHARD_REGISTRY_DO_NAME = "__lunora_shard_registry__";
 const DEFAULT_REGISTRY_CACHE_TTL_MS = 3e4;
 const REGISTRY_BASE_URL = "https://shard-registry.internal";
@@ -10,9 +12,10 @@ const createDynamicShardRegistry = (options) => {
   const instanceName = options.instanceName ?? SHARD_REGISTRY_DO_NAME;
   const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_REGISTRY_CACHE_TTL_MS;
   const cache = /* @__PURE__ */ new Map();
+  const namespace = applyJurisdiction(options.namespace, options.jurisdiction);
   let cachedStub;
   const stub = () => {
-    cachedStub ??= options.namespace.get(options.namespace.idFromName(instanceName));
+    cachedStub ??= namespace.get(namespace.idFromName(instanceName));
     return cachedStub;
   };
   const post = async (path, body) => stub().fetch(

package/dist/packem_shared/NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs

@@ -0,0 +1,8 @@
+const NOOP_EXECUTION_CONTEXT = {
+  passThroughOnException: () => {
+  },
+  waitUntil: () => {
+  }
+};
+
+export { NOOP_EXECUTION_CONTEXT };

package/dist/packem_shared/applyJurisdiction-BkZtTkct.mjs

@@ -0,0 +1,20 @@
+const applyJurisdiction = (namespace, jurisdiction) => {
+  if (jurisdiction === void 0) {
+    return namespace;
+  }
+  if (typeof namespace.jurisdiction !== "function") {
+    throw new TypeError(
+      `@lunora/runtime: Durable Object namespace does not support jurisdiction("${jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
+    );
+  }
+  return namespace.jurisdiction(jurisdiction);
+};
+const resolveShard = (namespace, shardKey) => {
+  if (typeof namespace.getByName === "function") {
+    return namespace.getByName(shardKey);
+  }
+  const id = namespace.idFromName(shardKey);
+  return namespace.get(id);
+};
+
+export { applyJurisdiction, resolveShard };