@lunora/server 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/index.d.mts

@@ -1,37 +1,30 @@
-import { Validator, Infer, v } from '@lunora/values';
-export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
-import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, RelationDefinition, GlobalBackend, OnDeleteAction, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
-export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
+import { Validator, Infer, v, Id, ValidatorMap, InferValidatorMap, ColumnValidator } from '@lunora/values';
+export { type ColumnValidator, type GeoPoint, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
+import { ArgsValidator, InferArgs, RegisteredAction, ExposeConfig, X402ProcedureConfig, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, DurableStreamOptions, RegisteredStream, FunctionKind, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, GlobalBackend, RelationDefinition, OnDeleteAction, SearchLanguage, SearchStrategy, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, DurableObjectJurisdiction, AggregateIndexDefinition, RankIndexDefinition, Secrets, LifecycleEvent, ShardInitEvent, RegisteredLifecycleHook } from "./types.mjs";
+export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type GeoBoundingBox, type GeoFilterBuilder, type GeoIndexDefinition, type GeoPointInput, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type LunoraWideEvent, type MutationStorage, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type RestCacheConfig, type RetryPolicy, type RunQueryOptions, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type SpanEvaluation, type SpanHandle, type SpanKind, type SpanLink, type SpanOptions, type Storage, type StorageMetadata, type StorageObjectBody, type StorageObjectHead, type StorageRange, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type TtlDefinition, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowEventDefinition, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
+import { LunoraError } from '@lunora/errors';
+export { LunoraError, type LunoraErrorCode } from '@lunora/errors';
 import { Context, Hono } from 'hono';
-import { b as Permission, R as Role, T as TypedDefinePolicyInput, a as Policy, D as DefinePolicyInput, W as WhereInput, c as RlsOptions } from "./packem_shared/types.d-DmvyEMD6.mjs";
-export type { d as PolicyContext, e as PolicyDecision, f as PolicyDecisionOf, P as PolicyOperation } from "./packem_shared/types.d-DmvyEMD6.mjs";
+import { WhereOperators, QueryArgs as QueryArgs$2 } from "./data-model.mjs";
+import { W as WhereInput, a as Policy, b as RlsOptions, c as Permission, R as Role, T as TypedDefinePolicyInput, D as DefinePolicyInput } from "./packem_shared/types.d-B7FLdYUD.mjs";
+export type { d as PolicyContext, e as PolicyDecision, f as PolicyDecisionOf, P as PolicyOperation } from "./packem_shared/types.d-B7FLdYUD.mjs";
 export { type CronJob, type CronJobsBuilder, type CronScheduleKind, type DailySchedule, type IntervalSchedule, type MonthlySchedule, type WeeklySchedule, cronJobs } from '@lunora/scheduler';
-import "./data-model.mjs";
-/**
-* Make any `config.storage` result bucket-aware so `ctx.storage.bucket(name)`
-* always resolves. A `createBucketStorage(...)` result already carries
-* `.bucket` / `.bucketName` and is returned as-is; a single `createStorage(...)`
-* (or the no-storage stub) is tagged as the `"default"` bucket, where
-* `.bucket(name)` is the identity — single-bucket apps address one binding under
-* every name.
-*
-* This is the runtime counterpart the generated `_generated/shard.ts` imports to
-* wrap `ctx.storage`; it lives here (the single source) rather than being stamped
-* inline into every generated file, so the bucket-tagging behaviour has one home
-* alongside the storage ctx types. The input is genuinely heterogeneous (a thunk
-* result cast through `unknown`), so the signature is `unknown → unknown`; the
-* generated caller casts the result to its storage type.
-*/
-declare const asBucketStorage: (raw: unknown) => unknown;
+/**
+ * Options for the `.stream()` terminal. `durable: true` is shorthand for
+ * `durable: {}` — the runtime only ever sees the object form.
+ */
+interface StreamOptions {
+  durable?: boolean | DurableStreamOptions;
+}
 /** Builder discriminator. Codegen reads this kind. */
 type TerminalKind = FunctionKind;
 /** Initial (empty) accumulated args for a fresh builder. */
 type EmptyArgs = Record<never, never>;
 /**
-* `next()` advances the middleware chain. Called with no argument it forwards
-* the current context unchanged; called with `{ ctx }` it shallow-merges the
-* extension, and the result type reflects the widened context.
-*/
+ * `next()` advances the middleware chain. Called with no argument it forwards
+ * the current context unchanged; called with `{ ctx }` it shallow-merges the
+ * extension, and the result type reflects the widened context.
+ */
 interface MiddlewareNext<ContextIn> {
   (): Promise<ContextIn>;
   <Extension extends Record<string, unknown>>(options: {
@@ -39,28 +32,69 @@ interface MiddlewareNext<ContextIn> {
   }): Promise<ContextIn & Extension>;
 }
 /**
-* A middleware receives the current context and a `next` continuation. Its
-* return type becomes the builder's new context, so `return next({ ctx })`
-* propagates the extension into every downstream `.use()` and the handler.
-*/
+ * A middleware receives the current context and a `next` continuation. Its
+ * return type becomes the builder's new context, so `return next({ ctx })`
+ * propagates the extension into every downstream `.use()` and the handler.
+ */
 type Middleware<ContextIn, ContextOut> = (options: {
   ctx: ContextIn;
   next: MiddlewareNext<ContextIn>;
 }) => ContextOut | Promise<ContextOut>;
-/** Options accepted by `initLunora.dataModel&lt;DM>().create(...)`. Reserved for transformer/error-formatter wiring. */
+/**
+ * The context a `.use(...)` step actually receives: the procedure context plus
+ * `args`, the call's arguments as declared by `.input(...)` up to this point in
+ * the chain.
+ *
+ * A middleware that gates on the payload — a CAPTCHA token, a signup email —
+ * has nowhere else to read it from: the procedure context carries the resolved
+ * identity, not the request body. `args` is surfaced only AFTER the validators
+ * have run, and as a frozen shallow copy, so a middleware cannot rewrite what
+ * the handler is then handed.
+ *
+ * This is a PROCEDURE-builder surface. `httpAction` / `httpRoute` have no
+ * `.use()` chain at all (`HttpActionCtx` is not a builder context) — an HTTP
+ * handler reads its own `request` / `searchParams` / `body` and calls the
+ * underlying helper (`verifyTurnstile(...)`, `assertEmailAllowed(...)`) inline,
+ * or mounts a hono middleware.
+ */
+type MiddlewareContext<Context, Args extends ArgsValidator> = Context & {
+  readonly args: Readonly<InferArgs<Args>>;
+};
+/** Options accepted by `initLunora.dataModel<DM>().create(...)`. Reserved for transformer/error-formatter wiring. */
 type CreateOptions = Record<never, never>;
 /**
-* `Output` carries the type declared by `.output(validator)`. It defaults to
-* the `undefined` sentinel meaning "not declared": in that state the terminal
-* stays generic over the handler's own return type. Once `.output()` sets it to
-* a concrete type, the terminal requires the handler to return that type and
-* the registration is typed to it (the runtime parses the result through the
-* validator). `[Output] extends [undefined]` is wrapped in a tuple so a union
-* `Output` doesn't distribute and so the test is for the exact sentinel.
-*/
+ * `Output` carries the type declared by `.output(validator)`. It defaults to
+ * the `undefined` sentinel meaning "not declared": in that state the terminal
+ * stays generic over the handler's own return type. Once `.output()` sets it to
+ * a concrete type, the terminal requires the handler to return that type and
+ * the registration is typed to it (the runtime parses the result through the
+ * validator). `[Output] extends [undefined]` is wrapped in a tuple so a union
+ * `Output` doesn't distribute and so the test is for the exact sentinel.
+ */
 interface QueryBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "query";
+  /**
+   * Publish this query on the opt-in public REST surface (plan 167) — the
+   * runtime mints `GET /_lunora/rest/<namespace>/<fn>` (and `POST`), dispatching
+   * THROUGH the procedure so `ctx.auth` / RLS / validators are enforced, and the
+   * generated OpenAPI describes it. Default-closed: omit to keep it RPC-only.
+   */
+  expose: (config: ExposeConfig) => QueryBuilder<Context, Args, Output>;
   input: <A extends ArgsValidator>(validators: A) => QueryBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => QueryBuilder<Context, Args, Output>;
   output: <V extends Validator>(validator: V) => QueryBuilder<Context, Args, Infer<V>>;
   query: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
@@ -70,23 +104,63 @@ interface QueryBuilder<Context, Args extends ArgsValidator, Output = undefined>
     ctx: Context;
   }) => Output | Promise<Output>) => RegisteredQuery<Args, Output>;
   /**
-  * Terminal: declare this procedure as a streaming query. The handler is an
-  * async generator (or any function returning an `AsyncIterable&lt;R>`) that
-  * yields one chunk per server-pushed frame. The third `signal` argument is
-  * tripped when the client cancels — break out of the loop or check
-  * `signal.aborted` between yields. `.output()` does not apply: per-chunk
-  * validation is opt-in via the handler itself.
-  */
-  stream: <R>(handler: (options: {
+   * Terminal: declare this procedure as a streaming query. The handler is an
+   * async generator (or any function returning an `AsyncIterable<R>`) that
+   * yields one chunk per server-pushed frame. The third `signal` argument is
+   * tripped when the client cancels — break out of the loop or check
+   * `signal.aborted` between yields.
+   *
+   * **Unavailable after `.output()`, deliberately.** Chunks are yielded as-is —
+   * there is no per-chunk validation — so `.output(...).stream(...)` used to
+   * compile and quietly enforce nothing, which is worse than not offering the
+   * combination: the author asked for validation and was told yes. Declaring an
+   * output on a stream is now a type error rather than a false promise. Validate
+   * inside the handler, or return the whole payload from `.query()` instead.
+   *
+   * Pass `{ durable: true }` to make the run outlive the socket that opened
+   * it: chunks are persisted as they are produced, so a reload resumes the
+   * same run from where it left off instead of dropping the work, and a
+   * second client with the same arguments attaches to the same transcript.
+   * That is what an LLM response wants; a progress ticker does not need it.
+   */
+  stream: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
     ctx: Context;
     signal: AbortSignal;
-  }) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => RegisteredStream<Args, R>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => QueryBuilder<ContextOut, Args, Output>;
+  }) => AsyncGenerator<R, void, void> | AsyncIterable<R>, options?: StreamOptions) => RegisteredStream<Args, R> : never;
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => QueryBuilder<ContextOut, Args, Output>;
+  /**
+   * Mark this query as paid. The origin worker answers an unpaid client RPC
+   * with HTTP 402, verifies + settles the x402 payment, then dispatches. `price`
+   * is USD (a number of dollars or a `"0.01"`/`"$0.01"` string); the network,
+   * recipient, and facilitator come from the worker-level x402 charge config.
+   */
+  x402: (config: X402ProcedureConfig) => QueryBuilder<Context, Args, Output>;
 }
 interface MutationBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "mutation";
+  /**
+   * Publish this mutation on the opt-in public REST surface (plan 167) — the
+   * runtime mints `POST /_lunora/rest/<namespace>/<fn>`, dispatching THROUGH the
+   * procedure so `ctx.auth` / RLS / validators are enforced, and the generated
+   * OpenAPI describes it. Default-closed: omit to keep it RPC-only.
+   */
+  expose: (config: ExposeConfig) => MutationBuilder<Context, Args, Output>;
   input: <A extends ArgsValidator>(validators: A) => MutationBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => MutationBuilder<Context, Args, Output>;
   mutation: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
     ctx: Context;
@@ -95,7 +169,14 @@ interface MutationBuilder<Context, Args extends ArgsValidator, Output = undefine
     ctx: Context;
   }) => Output | Promise<Output>) => RegisteredMutation<Args, Output>;
   output: <V extends Validator>(validator: V) => MutationBuilder<Context, Args, Infer<V>>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => MutationBuilder<ContextOut, Args, Output>;
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => MutationBuilder<ContextOut, Args, Output>;
+  /**
+   * Mark this mutation as paid. The origin worker answers an unpaid client RPC
+   * with HTTP 402, verifies + settles the x402 payment, then dispatches. `price`
+   * is USD (a number of dollars or a `"0.01"`/`"$0.01"` string); the network,
+   * recipient, and facilitator come from the worker-level x402 charge config.
+   */
+  x402: (config: X402ProcedureConfig) => MutationBuilder<Context, Args, Output>;
 }
 interface ActionBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "action";
@@ -106,20 +187,62 @@ interface ActionBuilder<Context, Args extends ArgsValidator, Output = undefined>
     args: InferArgs<Args>;
     ctx: Context;
   }) => Output | Promise<Output>) => RegisteredAction<Args, Output>;
+  /**
+   * Publish this action on the opt-in public REST surface (plan 167) — the
+   * runtime mints `POST /_lunora/rest/<namespace>/<fn>`, dispatching THROUGH the
+   * procedure so `ctx.auth` / RLS / validators are enforced, and the generated
+   * OpenAPI describes it. Default-closed: omit to keep it RPC-only.
+   */
+  expose: (config: ExposeConfig) => ActionBuilder<Context, Args, Output>;
   input: <A extends ArgsValidator>(validators: A) => ActionBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => ActionBuilder<Context, Args, Output>;
   output: <V extends Validator>(validator: V) => ActionBuilder<Context, Args, Infer<V>>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => ActionBuilder<ContextOut, Args, Output>;
-}
-/**
-* Internal builder variants. Identical to their public counterparts but carry
-* the `__lunoraVisibility: "internal"` brand codegen keys off to route the
-* registration into the `internal` object (and keep it off `api`). `input`/`use`
-* return the internal builder type so the brand survives the whole chain.
-*/
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => ActionBuilder<ContextOut, Args, Output>;
+  /**
+   * Mark this action as paid. The origin worker answers an unpaid client RPC
+   * with HTTP 402, verifies + settles the x402 payment, then dispatches. `price`
+   * is USD (a number of dollars or a `"0.01"`/`"$0.01"` string); the network,
+   * recipient, and facilitator come from the worker-level x402 charge config.
+   */
+  x402: (config: X402ProcedureConfig) => ActionBuilder<Context, Args, Output>;
+}
+/**
+ * Internal builder variants. Identical to their public counterparts but carry
+ * the `__lunoraVisibility: "internal"` brand codegen keys off to route the
+ * registration into the `internal` object (and keep it off `api`). `input`/`use`
+ * return the internal builder type so the brand survives the whole chain.
+ */
 interface InternalQueryBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "query";
   readonly __lunoraVisibility: "internal";
   input: <A extends ArgsValidator>(validators: A) => InternalQueryBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => InternalQueryBuilder<Context, Args, Output>;
   output: <V extends Validator>(validator: V) => InternalQueryBuilder<Context, Args, Infer<V>>;
   query: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
@@ -133,13 +256,27 @@ interface InternalQueryBuilder<Context, Args extends ArgsValidator, Output = und
     args: InferArgs<Args>;
     ctx: Context;
     signal: AbortSignal;
-  }) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => RegisteredStream<Args, R>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => InternalQueryBuilder<ContextOut, Args, Output>;
+  }) => AsyncGenerator<R, void, void> | AsyncIterable<R>, options?: StreamOptions) => RegisteredStream<Args, R>;
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => InternalQueryBuilder<ContextOut, Args, Output>;
 }
 interface InternalMutationBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "mutation";
   readonly __lunoraVisibility: "internal";
   input: <A extends ArgsValidator>(validators: A) => InternalMutationBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => InternalMutationBuilder<Context, Args, Output>;
   mutation: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
     ctx: Context;
@@ -148,7 +285,7 @@ interface InternalMutationBuilder<Context, Args extends ArgsValidator, Output =
     ctx: Context;
   }) => Output | Promise<Output>) => RegisteredMutation<Args, Output>;
   output: <V extends Validator>(validator: V) => InternalMutationBuilder<Context, Args, Infer<V>>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => InternalMutationBuilder<ContextOut, Args, Output>;
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => InternalMutationBuilder<ContextOut, Args, Output>;
 }
 interface InternalActionBuilder<Context, Args extends ArgsValidator, Output = undefined> {
   readonly __lunoraProcedure: "action";
@@ -161,8 +298,22 @@ interface InternalActionBuilder<Context, Args extends ArgsValidator, Output = un
     ctx: Context;
   }) => Output | Promise<Output>) => RegisteredAction<Args, Output>;
   input: <A extends ArgsValidator>(validators: A) => InternalActionBuilder<Context, A & Args, Output>;
+  /**
+   * Attach static, per-procedure metadata. Merges across calls and is readable
+   * from middleware as `ctx.meta`.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` lets ONE generic middleware read the policy it is meant
+   * to enforce off `ctx.meta`, where the same policy expressed only as
+   * `.use(rateLimit("pins/create"))` has to be re-parameterised at every
+   * `.use()` site. Mirrors tRPC's `.meta()`. The value is structured-cloned
+   * and deep-frozen: the same copy reaches every request, so it must not be
+   * mutable, and the object you passed stays yours (unfrozen). It must be
+   * structured-cloneable data — a function or class instance is rejected.
+   */
+  meta: (value: Record<string, unknown>) => InternalActionBuilder<Context, Args, Output>;
   output: <V extends Validator>(validator: V) => InternalActionBuilder<Context, Args, Infer<V>>;
-  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => InternalActionBuilder<ContextOut, Args, Output>;
+  use: <ContextOut>(middleware: Middleware<MiddlewareContext<Context, Args>, ContextOut>) => InternalActionBuilder<ContextOut, Args, Output>;
 }
 /** The public root builders plus their `internal*` counterparts, returned by `.create()`. */
 interface LunoraBuilders {
@@ -179,421 +330,1502 @@ interface DataModelInit<DataModel> {
   create: (options?: CreateOptions) => LunoraBuilders;
 }
 /**
-* Entry point for the procedure builder. `dataModel&lt;DM>()` binds the generated
-* `DataModel` (phantom for now), and `.create()` yields the public root builders
-* plus their `internal*` counterparts.
-*/
-declare const initLunora: {
-  dataModel: <DataModel>() => DataModelInit<DataModel>;
-};
+ * The prefixed tables a single plugin `P` contributes, or an empty map when it
+ * ships no schema extension. Mirrors {@link PrefixedTables} at the plugin level
+ * so {@link InstalledTables} can fold a tuple of plugins.
+ */
+type ExtensionTablesOf<P> = P extends {
+  readonly extension: SchemaExtension<infer X> & {
+    readonly key: infer K;
+  };
+} ? K extends string ? PrefixedTables<X, K> : Record<never, never> : Record<never, never>;
 /**
-* Redact secrets from a free-form message. Masks, in order: any quoted value
-* whose contents look like a credential (so a value surfaced as `received string
-* "sk_live_…"` is masked even though the surrounding text is not a token); a
-* `scheme://user:password@host` URL credential (the password segment); any
-* known-prefix credential token wherever it appears, at any length; any value
-* following a secret-named key in `KEY=value` / `KEY: value` form; and any
-* remaining bare high-entropy ≥24-char token run anywhere in the message.
-*
-* This is BEST-EFFORT defense-in-depth, NOT a guarantee: a short, prefix-less
-* secret under a non-secret-named key (and embedded credentials in shapes not
-* enumerated here) can still slip through. Treat it as a backstop — prefer
-* structured logging that never serializes raw env/secret fields in the first
-* place over relying on post-hoc scrubbing of untrusted data.
-*
-* Exported because it is independently useful — call it before logging anything
-* derived from `env`, request bodies, or thrown errors.
-*/
-declare const redactSecrets: (message: string) => string;
-/** One key's validation failure, secrets already redacted out of `message`. */
-interface EnvKeyFailure {
-  /** The env key that failed. */
-  key: string;
-  /** Redacted human-readable reason. */
-  message: string;
-}
+ * Fold a tuple of plugins onto a base table map `T`, accumulating each plugin's
+ * auto-prefixed extension tables left-to-right — the type-level mirror of
+ * {@link installPlugins} applying `mergeSchemaExtension` for each plugin in turn.
+ */
+type InstalledTables<T extends Record<string, TableDefinition>, Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? InstalledTables<ExtensionTablesOf<Head> & T, Rest> : T;
 /**
-* Thrown when one or more env keys are missing or fail validation. Carries the
-* structured list of `failures` (each with the offending `key`) so callers can
-* react programmatically; `message` is the joined, secret-redacted summary.
-*
-* Named export only (no default) per the repo export convention.
-*/
-declare class LunoraEnvError extends Error {
-  override readonly name = "LunoraEnvError";
-  readonly failures: ReadonlyArray<EnvKeyFailure>;
-  constructor(failures: ReadonlyArray<EnvKeyFailure>);
-}
-/** A record of `v.*` validators describing the expected env shape. */
-type EnvShape = Record<string, Validator>;
+ * Union every plugin's `ContextOut` in a tuple — the type-level mirror of the
+ * `ctx.api.<key>` additions {@link composePluginMiddleware} accumulates as each
+ * plugin middleware runs. Independent of the incoming context, which the builder
+ * infers at the `.use(...)` site.
+ */
+type ComposedOut<Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? ComposedOut<Rest> & (Head extends Plugin<any, any, infer Out> ? Out : unknown) : unknown;
 /**
-* The typed output of {@link defineEnv}. Optional validators (`v.optional(...)`)
-* become optional keys; everything else is required. Mirrors how `InferArgs`
-* derives an args object from a validator map.
-*/
-type InferEnv<S extends EnvShape> = { [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]> } & { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]> };
-/**
-* The accessor returned by {@link defineEnv}. A typed view over an `env` object
-* plus a `.parse(env)` escape hatch that validates every key eagerly.
-*
-* Call the accessor with the worker's `env` to get the typed, lazily-validated
-* proxy: `const config = defineEnv({ … }); const { PORT } = config(env);`.
-*/
-interface EnvAccessor<S extends EnvShape> {
-  /** Validate every key eagerly and return the typed, plain (non-proxy) object. Use for fail-fast-at-boot. */
-  parse: (env: unknown) => InferEnv<S>;
-  /** Lazily-validated, per-key-cached typed view over `env`. Keys are validated on first access. */
-  (env: unknown): InferEnv<S>;
+ * Schema fragment a plugin contributes. Same shape as the `tables` map
+ * passed to `defineSchema`. Optional `vectorIndexes` mirror the top-level
+ * `defineSchema` argument so a plugin can ship vector decls alongside its
+ * tables.
+ */
+interface SchemaExtension<T extends Record<string, TableDefinition> = Record<string, TableDefinition>> {
+  /** Stable key identifying the plugin that owns this extension. */
+  readonly key: string;
+  /**
+   * Extension tables, keyed by **bare** name (e.g. `buckets`). At merge time
+   * each is auto-prefixed with `key` (`ratelimit_buckets`) so it can't
+   * collide with an app table; do **not** namespace manually.
+   */
+  readonly tables: T;
+  /**
+   * Optional standalone vector indexes the plugin ships, keyed by index
+   * name. Merged into the host schema's `vectorIndexes`; a key collision
+   * with the base schema is a hard error (same policy as tables).
+   */
+  readonly vectorIndexes?: Record<string, VectorIndexDefinition>;
 }
 /**
-* Define a typed, validated accessor over a Worker's `env`. Pass a record of
-* `v.*` validators; receive an accessor that validates lazily per key (cached
-* per `env` identity) and infers its output type from the validators.
-*
-* ```ts
-* import { defineEnv, v } from "@lunora/server";
-*
-* const config = defineEnv({
-*     STRIPE_KEY: v.string(),
-*     PORT: v.optional(v.number()),
-* });
-*
-* export default {
-*     fetch(request, env) {
-*         const { STRIPE_KEY, PORT } = config(env); // STRIPE_KEY: string, PORT?: number
-*         // …
-*     },
-* };
-* ```
-*
-* Throws {@link LunoraEnvError} (secrets redacted) when a key is missing or
-* invalid — lazily on first access of that key, or eagerly via `config.parse(env)`.
-*/
-declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
+ * Build a {@link SchemaExtension}. The `key` is a runtime tag (used for
+ * error messages on collision) and a type-level brand.
+ */
+declare const defineSchemaExtension: <T extends Record<string, TableDefinition>>(key: string, options: {
+  tables: T;
+  vectorIndexes?: Record<string, VectorIndexDefinition>;
+}) => SchemaExtension<T>;
 /**
-* Canonical error type for Lunora procedures and middleware.
-*
-* The runtime's structural error mapper keys off `name === "LunoraError"` plus
-* the numeric `status`, so throwing one of these from a handler or middleware
-* yields the right RPC/HTTP status without any further wiring. `code` carries
-* the machine-readable reason for clients.
-*/
-declare const CODE_STATUS: {
-  readonly BAD_REQUEST: 400;
-  readonly CONFLICT: 409;
-  /**
-  * `count()` invoked against a table whose context carries an active RLS
-  * policy. The operation itself is unsupported in an RLS-restricted reader
-  * (kitcn's documented constraint) — the request is well-formed and the
-  * caller is authorized, so this is a 422 (semantic conflict) rather than a
-  * 403 (policy denial).
-  */
-  readonly COUNT_RLS_UNSUPPORTED: 422;
-  readonly FORBIDDEN: 403;
-  readonly INTERNAL_SERVER_ERROR: 500;
-  /**
-  * An analytical reduction (`aggregate` / `groupBy`) was invoked over a
-  * column that the procedure's `mask()` middleware redacts. A masked column
-  * can't be summed, averaged, or grouped without leaking the very values the
-  * mask hides (a group key *is* the raw value; an aggregate is computed from
-  * it), so the operation fails closed. The request is well-formed and the
-  * caller is authorized — this is a 422 (semantic conflict), mirroring
-  * `COUNT_RLS_UNSUPPORTED`.
-  */
-  readonly MASK_UNSUPPORTED: 422;
-  readonly NOT_FOUND: 404;
-  readonly NOT_IMPLEMENTED: 501;
-  /**
-  * A write policy's `when` returned a relation-crossing predicate
-  * (`some`/`none`/`every`/`is`/`isNot`). The in-memory write-policy evaluator
-  * has no child fetcher and cannot resolve a relation node, so the policy is
-  * unsupported as written. Relation predicates are valid in *read* policies
-  * and query `where` clauses (the pre-resolver handles them there). The
-  * request is well-formed; this is a 422 (semantic conflict), mirroring the
-  * sibling `*_UNSUPPORTED` codes.
-  */
-  readonly RELATION_PREDICATE_UNSUPPORTED: 422;
-  readonly TOO_MANY_REQUESTS: 429;
-  readonly UNAUTHORIZED: 401;
-  readonly UNPROCESSABLE: 422;
-};
-type LunoraErrorCode = keyof typeof CODE_STATUS;
-declare class LunoraError extends Error {
-  override readonly name = "LunoraError";
-  readonly code: LunoraErrorCode;
-  readonly status: number;
-  constructor(code: LunoraErrorCode, message?: string);
-}
-/**
-* The per-table `ctx.db` accessor (the `ctx.db.messages.findMany(...)` form) and
-* the kitcn-style `ctx.orm` namespace, as plain runtime helpers. This is the ONE
-* source of truth for the facade shape, shared by two callers so they can never
-* drift (a drift here is security-relevant — a facade accessor the RLS
-* middleware forgot to re-bind would read around policy). `@lunora/codegen`
-* emits `ctx.db`/`ctx.orm` by calling these over the raw shard writer (and the
-* D1 `globalDb` writer for `.global()` tables); the RLS middleware re-binds the
-* policy tables by calling them over the policy-enforcing wrapped writer.
-*
-* `bindTableFacade(writer, table)` pins `tableName` on the structural writer so
-* callers address rows by id (`get`/`delete`/`patch`/`replace`) or by the bound
-* table (everything else). The binding is identical regardless of which writer
-* is passed — that's the whole point.
-*/
-/**
-* Minimal structural writer the facade binds over. Declared with **method**
-* syntax (not arrow properties) so a more-specifically-typed writer — both
-* `@lunora/do`'s `DatabaseWriterLike` and the RLS middleware's wrapped writer —
-* stays assignable under bivariant parameter checking. That is the whole reason
-* the shared helper can serve both callers, hence the rule exemption.
-*/
-interface FacadeWriterLike {
-  aggregate(tableName: string, options: unknown): Promise<unknown>;
-  count(tableName: string, where?: unknown): Promise<number>;
-  delete(id: string, expectedTable?: string): Promise<void>;
-  deleteMany?(ids: ReadonlyArray<string>, options?: {
-    limit?: number;
-  }, expectedTable?: string): Promise<{
-    deleted: number;
-  }>;
-  findFirst(tableName: string, args?: unknown): Promise<unknown>;
-  findFirstOrThrow(tableName: string, args?: unknown): Promise<unknown>;
-  findMany(tableName: string, args?: unknown): Promise<unknown>;
-  get(id: string, expectedTable?: string): Promise<unknown>;
-  groupBy(tableName: string, options: unknown): Promise<unknown>;
-  insert(tableName: string, document: Record<string, unknown>): Promise<string>;
-  insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    limit?: number;
-  }): Promise<string[]>;
-  patch(id: string, patch: Record<string, unknown>, expectedTable?: string): Promise<void>;
-  patchMany?(patches: ReadonlyArray<{
-    id: string;
-    patch: Record<string, unknown>;
-  }>, options?: {
-    limit?: number;
-  }, expectedTable?: string): Promise<void>;
-  query(tableName: string): {
-    withSearchIndex(indexName: string, search: (q: unknown) => unknown): unknown;
-  };
-  rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
-  rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
-  replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+ * A plugin packages an optional schema extension and optional middleware.
+ * Both are independently usable: an app can install only the schema (e.g.
+ * for plugins that ship background workers but no per-request behavior)
+ * or only the middleware (plugins that augment ctx without persistent
+ * state).
+ */
+interface Plugin<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn> {
+  /**
+   * Optional schema extension. Apps install via
+   * `defineSchema(...).extend(plugin.extension)`.
+   */
+  readonly extension?: SchemaExtension<TExtension>;
+  /** Stable key identifying the plugin. Matches `extension.key` when set. */
+  readonly key: string;
+  /**
+   * Optional middleware. Users attach with `c.query.use(plugin.middleware)`.
+   * The middleware can extend `ctx`; convention is to attach helpers under
+   * `ctx.api.<key>`, e.g.
+   *
+   * ```ts
+   * middleware: ({ ctx, next }) =>
+   *     next({ ctx: { api: { ...ctx.api, ratelimit: api } } })
+   * ```
+   */
+  readonly middleware?: Middleware<TContextIn, TContextOut>;
 }
-/** The per-table accessor object returned for the `ctx.db` table form. */
-interface FacadeEntry {
-  aggregate: (options: unknown) => Promise<unknown>;
-  count: (where?: unknown) => Promise<number>;
-  delete: (id: string) => Promise<void>;
-  deleteMany: (ids: ReadonlyArray<string>, options?: {
-    limit?: number;
-  }) => Promise<{
-    deleted: number;
-  }>;
-  findFirst: (args?: unknown) => Promise<unknown>;
-  findFirstOrThrow: (args?: unknown) => Promise<unknown>;
-  findMany: (args?: unknown) => Promise<unknown>;
-  get: (id: string) => Promise<unknown>;
-  groupBy: (options: unknown) => Promise<unknown>;
-  insert: (document: Record<string, unknown>) => Promise<string>;
-  insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    limit?: number;
-  }) => Promise<string[]>;
-  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
-  patchMany: (patches: ReadonlyArray<{
-    id: string;
-    values: Record<string, unknown>;
-  }>, options?: {
-    limit?: number;
-  }) => Promise<void>;
-  rank: (indexName: string, options: unknown) => Promise<unknown>;
-  rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
-  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
-  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
+/** Options to {@link definePlugin}. */
+interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut> {
+  extension?: SchemaExtension<TExtension>;
+  middleware?: Middleware<TContextIn, TContextOut>;
 }
 /**
-* Bind a structural writer to one table, producing its `ctx.db` table accessor.
-*
-* The by-id accessors (`get`/`delete`/`patch`/`replace`) forward the bound
-* `tableName` as `expectedTable` so the underlying writer scopes its id lookup
-* to this table. Without it, a branded `Id&lt;"posts">` carrying another table's
-* id would resolve cross-table (the writer probes every table by id), letting
-* `ctx.db.posts.get(foreignId)` read — or `.delete`/`.patch`/`.replace`
-* mutate — a row in an unrelated table (IDOR). Writers that ignore the second
-* argument keep their previous global behaviour; the scoping is opt-in via this
-* forwarded name.
-*/
-declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) => FacadeEntry;
-/** The kitcn-style `ctx.orm` namespace over a per-table facade map. */
-interface OrmLike {
-  delete: (table: string, id: string) => Promise<void>;
-  insert: (table: string) => {
-    values: (document: Record<string, unknown>) => Promise<string>;
-  };
-  query: Record<string, FacadeEntry>;
-  replace: (table: string, id: string) => {
-    with: (document: Record<string, unknown>) => Promise<void>;
-  };
-  update: (table: string, id: string) => {
-    set: (values: Record<string, unknown>) => Promise<void>;
+ * Call signatures for {@link definePlugin}. When `extension` is supplied the
+ * returned plugin's `extension` is typed as PRESENT (not `?`), so the
+ * canonical install pattern `defineSchema(...).extend(plugin.extension)`
+ * typechecks without a non-null assertion — the shape every scaffold template
+ * ships. The bare-options signature keeps `extension` optional for plugins
+ * that carry only middleware.
+ */
+interface DefinePluginFunction {
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut> & {
+    extension: SchemaExtension<TExtension>;
+  }): Plugin<TExtension, TContextIn, TContextOut> & {
+    readonly extension: SchemaExtension<TExtension>;
   };
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>): Plugin<TExtension, TContextIn, TContextOut>;
+}
+/**
+ * Package a schema extension + middleware as a reusable plugin. Either
+ * field is optional — `definePlugin("foo", {})` is valid but degenerate.
+ */
+declare const definePlugin: DefinePluginFunction;
+/**
+ * Bundle of registered functions a {@link Component} ships. Keys are the
+ * function's local name (e.g. `check`, `reset`); the registered function
+ * value carries its own kind / args / handler.
+ *
+ * Users re-export from their own lunora module so codegen picks them up:
+ *
+ * ```ts
+ * // lunora/ratelimit.ts
+ * import { ratelimit } from "@vendor/ratelimit-component";
+ * export const { check, reset } = ratelimit.functions;
+ * // Emits as `ratelimit:check` / `ratelimit:reset` in the generated `api`.
+ * ```
+ *
+ * Codegen follows the re-export back to the bundled `query/mutation/action`
+ * call (property access or destructuring both work), so the functions land in
+ * the generated `api` under the re-exporting file's namespace.
+ */
+type ComponentFunctions = Readonly<Record<string, RegisteredFunction<any, any, FunctionKind>>>;
+/**
+ * Component = {@link Plugin} with a bundle of registered functions. The
+ * extension + middleware + functions are independent: a component can ship
+ * functions without a schema (e.g. a stateless utility), or a schema
+ * without functions (e.g. shared table definitions), and any combination.
+ */
+interface Component<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn, F extends ComponentFunctions = ComponentFunctions> extends Plugin<TExtension, TContextIn, TContextOut> {
+  readonly functions: F;
+}
+interface DefineComponentOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut, F extends ComponentFunctions> extends DefinePluginOptions<TExtension, TContextIn, TContextOut> {
+  /** Registered functions the component ships. Keys are the function's local name. */
+  functions?: F;
 }
-/** Build `ctx.orm` over a per-table facade map (table name → FacadeEntry). */
-declare const bindOrm: (facade: Record<string, FacadeEntry>) => OrmLike;
-/** HTTP verbs the typed {@link httpRoute} builder can bind to. */
-type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
 /**
-* Context handed to an HTTP action handler. A narrower view of {@link ActionContext}:
-* HTTP actions run in the worker (the "action runtime"), separate from the
-* transactional store, so there is no direct `db` / `vectors` / `scheduler` /
-* `storage` surface — reach the data layer through `runQuery` / `runMutation` /
-* `runAction`, which forward to the owning shard.
-*/
-type HttpActionCtx = Pick<ActionCtx, "auth" | "fetch" | "runAction" | "runMutation" | "runQuery">;
-/** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
-type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
+ * Convenience wrapper around {@link definePlugin} that also bundles a set
+ * of registered functions. The resulting `component.functions` object is a
+ * record of `name → registered query/mutation/action`; consumers
+ * re-export entries so codegen discovers them as user functions:
+ *
+ * ```ts
+ * export const ratelimit = defineComponent("ratelimit", {
+ *     // Bare `buckets` merges in as `ratelimit_buckets`.
+ *     extension: defineSchemaExtension("ratelimit", { tables: { buckets } }),
+ *     middleware: ({ ctx, next }) => next({ ctx: { ...ctx, ratelimit: api(ctx) } }),
+ *     functions: {
+ *         check: query.input({ key: v.string() }).query(async ({ ctx, args }) => ...),
+ *         reset: mutation.input({ key: v.string() }).mutation(async ({ ctx, args }) => ...),
+ *     },
+ * });
+ * ```
+ *
+ * Re-exporting an entry (by property access or destructuring) is enough for
+ * codegen to discover it in the host app's namespace — the discovery resolver
+ * chases the re-export back to the bundled registration call.
+ */
+declare const defineComponent: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn, F extends ComponentFunctions = ComponentFunctions>(key: string, options: DefineComponentOptions<TExtension, TContextIn, TContextOut, F>) => Component<TExtension, TContextIn, TContextOut, F>;
 /**
-* The hono {@link https://hono.dev | Hono} environment used by {@link httpRouter}.
-* The runtime injects the per-request {@link HttpActionCtx} on the private
-* `__lunoraCtx` binding; the router's lifting middleware promotes it to
-* `c.var.lunora` so handlers can read it as a typed variable.
-*/
-interface LunoraHttpEnv {
-  Bindings: Record<string, unknown> & {
-    __lunoraCtx?: HttpActionCtx;
-  };
-  Variables: {
-    lunora: HttpActionCtx;
-  };
-}
-/** The hono app type {@link httpRouter} returns. */
-type LunoraHttpApp = Hono<LunoraHttpEnv>;
-/** A compiled route handler: a hono handler that resolves to a raw {@link Response}. */
-type LunoraRouteHandler = (c: Context<LunoraHttpEnv>) => Promise<Response>;
+ * Map every key `K` of an extension's table map `X` to its auto-prefixed name
+ * `${Key}_${K}`. Mirrors the runtime prefixing in {@link mergeSchemaExtension}
+ * so the typed `.extend(...)` chain reflects the real merged table names.
+ */
+type PrefixedTables<X extends Record<string, TableDefinition>, Key extends string> = { [K in keyof X as K extends string ? `${Key}_${K}` : K]: X[K]; };
+/**
+ * Merge a {@link SchemaExtension} into an existing schema. Returns a new
+ * schema object — never mutates the input.
+ *
+ * Extension tables are auto-namespaced: each bare table name is prefixed with
+ * the extension `key` (`buckets` → `ratelimit_buckets`), Convex-Components
+ * style, and every intra-extension reference (relation targets, aggregate /
+ * rank index `on`, standalone vector index `table`) is rewritten to match.
+ * References to base/app tables are left untouched.
+ *
+ * Because each extension lives in its own `key` namespace, app↔component
+ * collisions are impossible. The only remaining hard error is two extensions
+ * sharing the same `key` and producing the same prefixed table (or vector
+ * index) name — silent shadow would let one plugin hijack another's data.
+ *
+ * Re-runs {@link validateIndexFields} against the merged table set before
+ * returning: `defineSchema` only validates the tables it was called with, so
+ * without this an extension-contributed index with a typo'd/out-of-shape
+ * field (or a duplicate name within one kind) would never be checked at all.
+ * Re-validating the whole merged set (base + prefixed extension tables) is
+ * cheap and idempotent for the base tables, which already passed this same
+ * check when the base schema was built. Both callers of this function —
+ * `withExtend.extend()` (`./schema`) and `installPlugins` (below) — get the
+ * re-validation for free from this single call site (plan 258 §4/§9 Q3).
+ */
+declare const mergeSchemaExtension: <T extends Record<string, TableDefinition>, X extends Record<string, TableDefinition>, Key extends string = string>(base: Schema<T>, extension: SchemaExtension<X> & {
+  readonly key: Key;
+}) => Schema<PrefixedTables<X, Key> & T>;
 /**
-* Wrap a `(ctx, request) => Response` handler as a hono handler. The raw escape
-* hatch — mount it with `app.all(path, httpAction(fn))`. `ctx` is the
-* runtime-injected {@link HttpActionCtx} lifted into `c.var.lunora` by
-* {@link httpRouter}; `request` is the underlying `c.req.raw`.
-*/
-declare const httpAction: (handler: HttpActionHandler) => LunoraRouteHandler;
+ * Install several plugins' schema extensions in one call — the one-shot
+ * counterpart to chaining `defineSchema(...).extend(a).extend(b)`. Plugins
+ * without an `extension` (middleware-only) are skipped; tables from those that
+ * do are auto-prefixed and reference-rewritten exactly as
+ * {@link mergeSchemaExtension} does for a single `.extend(...)`.
+ *
+ * ```ts
+ * const schema = installPlugins(defineSchema({ todos }), [ratelimit, audit]);
+ * // → todos + ratelimit_* + audit_*
+ * ```
+ *
+ * Pair it with {@link composePluginMiddleware} to attach every plugin's
+ * middleware in a single `.use(...)`, so installing N plugins is two calls
+ * rather than N `.extend(...)` + N `.use(...)`.
+ */
+declare const installPlugins: <T extends Record<string, TableDefinition>, const Plugins extends ReadonlyArray<Plugin<any, any, any>>>(base: Schema<T>, plugins: Plugins) => Schema<InstalledTables<T, Plugins>>;
 /**
-* Create the hono app for HTTP actions. Pre-wired with a middleware that lifts
-* the runtime-injected `c.env.__lunoraCtx` into `c.var.lunora`, so both
-* {@link httpAction} and the typed {@link httpRoute} builder can read the action
-* context. The full hono surface is available — plugins, path params, `.route`:
-*
-* ```ts
-* const app = httpRouter();
-* app.use("*", cors());
-* app.post("/webhook", httpAction(onWebhook));
-* app.get("/users/:id", getUser);
-* export default createWorker({ httpRouter: app, ... });
-* ```
-*
-* The lifting middleware throws if the context is absent. `createWorker` injects
-* it on every request the router sees, so this only trips when the app is run
-* outside the runtime — a misconfiguration we surface loudly rather than let
-* `c.var.lunora` be silently `undefined` despite its non-optional type.
-*/
-declare const httpRouter: () => LunoraHttpApp;
-/** The `{ ctx, searchParams, body, params }` a typed route handler receives. */
-interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator> {
-  body: InferArgs<Body>;
-  ctx: HttpActionCtx;
-  params: InferArgs<Params>;
-  searchParams: InferArgs<SearchParams>;
+ * Compose every plugin's middleware into a single middleware you attach with one
+ * `.use(...)`. Plugins without middleware (schema-only) are skipped; the rest run
+ * in array order, each seeing the context the previous one widened, so the final
+ * `next({ ctx })` the builder receives carries every plugin's `ctx.api.<key>`
+ * additions. Equivalent to `.use(a.middleware).use(b.middleware)…` but as one
+ * value, the middleware sibling of {@link installPlugins}.
+ *
+ * `ContextIn` is left free so the builder infers it from the context at the
+ * `.use(...)` site; the result type widens it by the union of the plugins'
+ * outputs.
+ */
+declare const composePluginMiddleware: <ContextIn = unknown, const Plugins extends ReadonlyArray<Plugin<any, any, any>> = ReadonlyArray<Plugin<any, any, any>>>(plugins: Plugins) => Middleware<ContextIn, ComposedOut<Plugins> & ContextIn>;
+/** Options for `.vectorize(field, opts)` (DSL Shape A). */
+interface VectorizeOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  dimensions: number;
+  embed: VectorEmbedder;
+  /** Logical index name; must match a `[[vectorize]]` binding in wrangler. */
+  index: string;
+  /** Fields mirrored into Vectorize metadata for filtering. */
+  metadata?: ReadonlyArray<keyof Shape & string>;
+  metric: VectorMetric;
 }
-/**
-* The `{ ctx, searchParams, params, request, signal }` a streaming HTTP
-* handler receives. There is no parsed `body` — streams are typically GET, and
-* the raw `request` is exposed if a handler needs to read the body itself.
-* `signal` is tripped when the client disconnects.
-*/
-interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
-  ctx: HttpActionCtx;
-  params: InferArgs<Params>;
-  request: Request;
-  searchParams: InferArgs<SearchParams>;
-  signal: AbortSignal;
+/** A `one` (many-to-one) relation descriptor; phantom `Target` carries the target table name. */
+interface OneRelation<Target extends string = string> extends RelationDefinition {
+  readonly __target?: Target;
+  readonly kind: "one";
 }
-/**
-* A typed REST route under construction. `.searchParams()` / `.body()` /
-* `.params()` accumulate validator maps (later calls merge, a colliding key
-* wins) that decode the URL query, JSON body, and hono path params into the
-* handler's typed `searchParams` / `body` / `params`. Like the procedure
-* builder, `.output(validator)` defaults to the `undefined` sentinel — while
-* unset the handler is generic over its own return; once set the handler must
-* return that type and the result is parsed through the validator before
-* serialization. `[Output] extends [undefined]` is tuple-wrapped so a union
-* `Output` doesn't distribute and the test is for the exact sentinel.
-*
-* The terminal `.handler()` yields a {@link LunoraRouteHandler} — mount it
-* directly with `app.get(path, route)`.
-*/
-interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
-  body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
-  handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
-  output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
-  params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
-  searchParams: <S extends ArgsValidator>(validators: S) => HttpRouteBuilder<S & SearchParams, Body, Params, Output>;
-  /**
-  * Terminal: declare this route as a streaming Server-Sent Events endpoint.
-  * The handler is an async generator (or any function returning an
-  * `AsyncIterable&lt;R>`) that yields one chunk per SSE `data:` frame; on
-  * iterator completion the route writes a final `event: complete` frame; on
-  * throw, an `event: error` frame is written with `{code, message}` before
-  * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
-  * handler's yielded type.
-  */
-  stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+/** A `many` (one-to-many) relation descriptor; phantom `Target` carries the target table name. */
+interface ManyRelation<Target extends string = string> extends RelationDefinition {
+  readonly __target?: Target;
+  readonly kind: "many";
 }
-/** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
-type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;
-/** The verb-keyed entry point: `httpRoute.get("/api/todos")…`. */
-interface HttpRoute {
-  delete: HttpRouteFactory;
-  get: HttpRouteFactory;
-  head: HttpRouteFactory;
-  options: HttpRouteFactory;
-  patch: HttpRouteFactory;
-  post: HttpRouteFactory;
-  put: HttpRouteFactory;
+/** The `r` argument passed to `.relations((r) => …)`. */
+interface RelationBuilder {
+  /** One-to-many: the FK `field` lives on the target table, matching this table's `references` (default `_id`). */
+  many: <Target extends string>(table: Target, options: {
+    field: string;
+    references?: string;
+  }) => ManyRelation<Target>;
+  /** Many-to-one: the FK `field` lives on this table, pointing at `table`.`references` (default `_id`). */
+  one: <Target extends string>(table: Target, options: {
+    field: string;
+    onDelete?: OnDeleteAction;
+    references?: string;
+  }) => OneRelation<Target>;
 }
 /**
-* Typed REST route builder. Compiles down to a {@link LunoraRouteHandler}, so a
-* typed route and a hand-written {@link httpAction} are interchangeable when
-* mounted on {@link httpRouter}:
-*
-* ```ts
-* export const listTodos = httpRoute
-*     .get("/api/todos")
-*     .searchParams({ limit: v.number(), q: v.optional(v.string()) })
-*     .output(v.array(v.object({ id: v.string(), text: v.string() })))
-*     .handler(async ({ ctx, searchParams }) => ctx.runQuery(api.todos.list, searchParams));
-*
-* export const getTodo = httpRoute
-*     .get("/api/todos/:id")
-*     .params({ id: v.string() })
-*     .handler(async ({ ctx, params }) => ctx.runQuery(api.todos.get, params));
-*
-* const app = httpRouter();
-* app.get("/api/todos", listTodos);
-* app.get("/api/todos/:id", getTodo);
-* ```
-*/
-declare const httpRoute: HttpRoute;
+ * Options for the inline `.aggregateIndex(name, opts)` builder. `op` defaults to
+ * `count` so `aggregateIndex("byUser", { by: ["userId"] })` is a single-line
+ * `COUNT(*) GROUP BY userId` accelerator.
+ */
+interface InlineAggregateIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  /** Group keys; counter rows are one per distinct tuple. Omitted = single-row aggregate over the whole table. */
+  by?: ReadonlyArray<keyof Shape & string>;
+  /** The column the reducer applies to. Required for `sum`/`min`/`max`/`avg`; ignored for `count`. */
+  field?: keyof Shape & string;
+  /** Reducer (default `count`). */
+  op?: AggregateOp;
+  /** Static predicate baked into the counter — only matching rows are aggregated. */
+  where?: Record<string, unknown>;
+}
 /**
-* Structural view of an R2 object body, as returned by `@lunora/storage`'s
-* `download()`. Re-declared here (not imported) so `@lunora/server` takes no
-* runtime dependency on `@lunora/storage`; the real binding satisfies the shape.
-*/
-interface StorageObjectBody {
-  /** The object body stream (`null` for a zero-byte object). */
-  body: ReadableStream | null;
-  etag: string;
-  httpMetadata?: {
-    contentType?: string;
-  };
-  key: string;
+ * Options for the inline `.rankIndex(name, opts)` builder. `sortBy` is required;
+ * accepts either an array of `{ field, direction }` keys, or the shorthand
+ * `["field"]` (asc) / `{ field: "desc" }` map entries. `partitionBy` scopes the
+ * rank — omitted ⇒ one global rank over the whole table.
+ */
+interface InlineRankIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  /** Columns that scope each ranking; omitted ⇒ one global rank. */
+  partitionBy?: ReadonlyArray<keyof Shape & string>;
+  /** Ordered sort keys driving the rank. Required. */
+  sortBy: ReadonlyArray<{
+    direction?: "asc" | "desc";
+    field: keyof Shape & string;
+  }>;
+  /** Static predicate baked into the index; only matching rows enter. */
+  where?: Record<string, unknown>;
+}
+interface TableBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> extends TableDefinition<Shape> {
+  /** Declare an aggregate (counter/sum/…) maintained by triggers for O(1) reads. */
+  aggregateIndex: (name: string, options?: InlineAggregateIndexOptions<Shape>) => TableBuilder<Shape>;
+  /**
+   * Stamp every row with `_commitSeq` — a per-shard integer, allocated once
+   * per mutation and strictly increasing in **commit order**, refreshed on
+   * every write to the row (insert, patch, replace, and the marker flip a
+   * `.softDelete()` performs).
+   *
+   * `_creationTime` is wall-clock and therefore cannot order commits: the
+   * clock is read when the handler runs, the write lands when the transaction
+   * commits, and nothing ties those instants together. A changefeed paging on
+   * `_creationTime` can skip a row permanently. Paging on `_commitSeq`
+   * (`where: { _commitSeq: { gt: cursor } }, orderBy: ["_commitSeq"]`) cannot.
+   *
+   * It orders COMMITS, not rows: one mutation's rows share a value. A bounded
+   * page can therefore end mid-group, so a consumer must checkpoint at a
+   * sequence it has seen the whole of, never at the last row of a full page.
+   * An action's writes are the exception to the grouping — they commit
+   * independently, so each gets its own sequence.
+   *
+   * Ordered, not contiguous — read a gap as "nothing to see", never as loss.
+   * Per-shard, not global: two shards allocate independently, so a cursor is
+   * only meaningful against the shard it came from. Rejected on `.global()`
+   * tables, which have no shard-local transaction to allocate inside.
+   *
+   * **A hard delete is invisible to the feed.** The sequence lives on the row,
+   * so a physically removed row takes it along: the row stops appearing, but
+   * no event says it went away. Pair `.commitOrdered()` with `.softDelete()`
+   * when the feed must observe deletes — the tombstone flip is an UPDATE, so
+   * it advances the sequence and pages through like any other change.
+   */
+  commitOrdered: () => TableBuilder<Shape>;
+  /**
+   * Mark this table as written outside Lunora's discoverable insert path —
+   * by an adapter, a migration, or framework middleware (e.g. `@lunora/auth`'s
+   * better-auth tables, `@lunora/ratelimit`'s store). Advisor insert-path lints
+   * (`table_without_insert`) then skip it instead of flagging the absent
+   * `ctx.db.insert(...)`.
+   */
+  externallyManaged: () => TableBuilder<Shape>;
+  /**
+   * Declare a geospatial index over a `v.geoPoint()` column. The runtime keeps
+   * a geohash companion so `withGeoIndex(name, q => q.near(point, radius))` and
+   * `.within(bbox)` resolve as a geohash-prefix range scan + Haversine
+   * refine/sort. `options.precision` tunes the geohash length (default 9).
+   */
+  geoIndex: (name: string, options: {
+    field: keyof Shape & string;
+    precision?: number;
+  }) => TableBuilder<Shape>;
+  /**
+   * Mark this table as global (cross-shard). Backed by **D1** by default;
+   * pass `{ backend: "hyperdrive" }` to store it in a Postgres/MySQL database
+   * via Cloudflare Hyperdrive (PlanetScale, Neon, …) instead. Either way the
+   * table stays reactive — live queries re-run on write.
+   */
+  global: (options?: {
+    backend?: GlobalBackend;
+  }) => TableBuilder<Shape>;
+  /** Add a secondary index. */
+  index: (name: string, fields: ReadonlyArray<(keyof Shape & string) | (typeof SYSTEM_INDEX_FIELDS)[number]>, options?: {
+    unique?: boolean;
+  }) => TableBuilder<Shape>;
+  /**
+   * Declare this table EPHEMERAL — state the shard rebuilds rather than
+   * remembers.
+   *
+   * A memory table is a full `ctx.db` table: indexes, `where`, `orderBy`,
+   * pagination, relations, live queries. What it is not is durable. Its rows
+   * are wiped the moment the Durable Object is reconstructed — which happens
+   * on every eviction, and a WebSocket-hibernating shard is evicted often — so
+   * a memory table holds only what can be derived again: presence and cursors,
+   * a live participant list, a rate-limit window, an actor's scratch state.
+   *
+   * Pair it with `onShardInit` to rebuild whatever the app needs present.
+   * The framework guarantees the ordering: every memory table is cleared, and
+   * every init hook has run, before any handler can read one. Without a hook a
+   * memory table simply comes back empty, which is a correct state for
+   * presence and a wrong one for a cache someone is treating as authoritative.
+   *
+   * **On Cloudflare the rows still transit the DO's SQLite.** workerd exposes
+   * exactly one SQL handle and no memory-backed database, so `.memory()` buys
+   * the LIFETIME (and skips the CDC changelog, so an append-heavy presence
+   * table does not grow the op-log), not the write. Treat it as "state I am
+   * happy to lose", not as "state that is free to write" — see
+   * `PlatformCapabilities.memoryTables`, rated `emulated` for exactly this
+   * reason.
+   *
+   * Rejected alongside `.global()` (a D1 table is not this shard's to clear),
+   * `.commitOrdered()` (a sequence that resets is not a sequence), and
+   * `.source()` (an externally-materialized table is not ours to wipe).
+   */
+  memory: () => TableBuilder<Shape>;
+  /**
+   * Name the column holding the owning user's id, so "only the owner sees these
+   * rows" is declared once here rather than restated in every shape.
+   *
+   * A `defineShape({ table, owner: true })` over this table derives its predicate
+   * from the field: the subscriber's verified `ctx.auth.userId` must match, and an
+   * anonymous subscriber is denied. Pairs naturally with `.shardBy(field)` on the
+   * same column — the shard key routes the storage, `ownedBy` states who the rows
+   * belong to — but the two are independent and either can be used alone.
+   *
+   * This is a *shape* declaration, not an RLS policy: it narrows what a shape
+   * replicates. Guarding procedure reads/writes is still `rls(...)`'s job.
+   */
+  ownedBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+   * Opt this table OUT of secure-by-default RLS. Under a schema marked
+   * `.rls("required")`, every table is protected (the write path denies raw,
+   * non-RLS `ctx.db` access); calling `.public()` exempts this one table so a
+   * plain `query`/`mutation` may read/write it without an RLS policy. No effect
+   * when the schema does not require RLS.
+   */
+  public: () => TableBuilder<Shape>;
+  /**
+   * Declare a rank index (sorted companion table, btree-backed) for
+   * `rank(row)` / `rankPage()` reads in O(log n). See {@link RankIndexDefinition}.
+   */
+  rankIndex: (name: string, options: InlineRankIndexOptions<Shape>) => TableBuilder<Shape>;
+  /** Declare relations to other tables, loaded via `findMany({ with })`. */
+  relations: (build: (r: RelationBuilder) => Record<string, RelationDefinition>) => TableBuilder<Shape>;
+  /**
+   * Add a full-text search index over `field`, queried with
+   * `.withSearchIndex(name, q => q.search(field, term))`. `field` may be a
+   * dot-separated path into a nested object (`"properties.name"`).
+   * `filterFields` (at most 16) lists the columns `.eq()` may narrow by inside
+   * the search. `language` selects the text analysis (accent folding always,
+   * plus that language's stopwords). `staged: true` skips the migration-time
+   * backfill on a large existing table — pre-existing rows stay unsearchable
+   * until `__lunora_admin__:backfillSearch` is run against the deployment. `strategy: "native"` uses the engine's
+   * own full-text index where it has one (Postgres) — faster on large corpora,
+   * at the cost of the engine ranking rather than the shared scorer.
+   */
+  searchIndex: (name: string, options: {
+    field: string;
+    filterFields?: ReadonlyArray<string>;
+    language?: SearchLanguage;
+    staged?: boolean;
+    strategy?: SearchStrategy;
+  }) => TableBuilder<Shape>;
+  /** Route storage by the named field — one DO per distinct value. */
+  shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+   * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
+   * default `deletedAt`) and changes `ctx.db.<table>.delete()` to **set** it
+   * instead of removing the row; `onDelete: "cascade"` children are recursively
+   * soft-deleted too. **List reads** (`findMany`/`findFirst`/`query()`/`count`/
+   * `aggregate`/relation loads) then hide soft-deleted rows unless they pass
+   * `includeDeleted: true`; by-id `get`/`patch`/`replace` and the new
+   * `restore()` still address the row directly. `hardDelete()` physically
+   * removes it (cascading as a real delete). Note: `includeDeleted` is a read
+   * scope, not access control — anyone who can run the read can set it; a unique
+   * index still rejects a new row that collides with a soft-deleted one (the row
+   * physically persists).
+   */
+  softDelete: (options?: {
+    field?: string;
+  }) => TableBuilder<Shape>;
+  /**
+   * Materialize this table from an external Postgres/MySQL behind Cloudflare
+   * Hyperdrive (plan 077). A system-driven poll loop reads the tenant slice
+   * (`query`, with params bound from `tenantBy`) and lands it in the DO's SQLite,
+   * after which `defineShape` carries it to clients unchanged. Implies
+   * `.externallyManaged()` (rows come from the ingest loop, not user mutations).
+   *
+   * Orthogonal to `.shardBy()` — combine them for per-tenant DOs. **Under
+   * `.shardBy()` `tenantBy` is mandatory** (the tenant-isolation boundary); the
+   * `external_source_unscoped` advisor lint fails the build when it is absent, and
+   * `external_source_on_global` rejects combining `.source()` with `.global()`.
+   */
+  source: (definition: ExternalSourceDefinition) => TableBuilder<Shape>;
+  /** Declare named lifecycle triggers fired inline within the write path. */
+  triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
+  /**
+   * Declare a table-level TTL: a DO alarm-driven sweep auto-deletes rows whose
+   * expiry has passed (or soft-deletes them when the table also
+   * `.softDelete()`s). `field` is an epoch-millisecond column; without
+   * `options.after` its value is the absolute expiry instant, with `after` the
+   * row expires `after` ms past `field` (`field + after`). Coarse, cheap,
+   * table-level — for per-row schedules use `@lunora/scheduler`.
+   */
+  ttl: (field: keyof Shape & string, options?: {
+    after?: number;
+  }) => TableBuilder<Shape>;
+  /** Declare a vector index over a single text field on this table. */
+  vectorize: (field: keyof Shape & string, options: VectorizeOptions<Shape>) => TableBuilder<Shape>;
+}
+/** Options for `defineVectorIndex(...)` (DSL Shape B). */
+interface VectorIndexOptions {
+  dimensions: number;
+  embed: VectorEmbedder;
+  /** Optional projection of the source row into Vectorize metadata. */
+  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  metric: VectorMetric;
+  /** The vector source: which table, and how to derive the embedded text. */
+  source: {
+    select: (row: Record<string, unknown>) => string;
+    table: string;
+  };
+}
+/**
+ * Build a table definition. Returned object is both the table definition (for
+ * `defineSchema`) and a fluent builder for indexes + sharding metadata.
+ */
+declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
+/**
+ * Declare a standalone vector index (DSL Shape B). Pass the returned value in
+ * the `vectorIndexes` map of {@link defineSchema} when the source is derived
+ * from multiple fields or a computation rather than a single column.
+ */
+declare const defineVectorIndex: (options: VectorIndexOptions) => VectorIndexDefinition;
+/**
+ * Options for the standalone `defineAggregateIndex(name, opts)` helper (DSL
+ * Shape B). Unlike the inline `.aggregateIndex(...)` builder, this form takes
+ * the owning table explicitly via `on` — handy when a single counter wants to
+ * live next to the schema map rather than inside a table chain.
+ */
+interface AggregateIndexOptions {
+  by?: ReadonlyArray<string>;
+  field?: string;
+  on: string;
+  op?: AggregateOp;
+  where?: Record<string, unknown>;
+}
+/**
+ * Declare a standalone aggregate index. Pass the returned value to
+ * `defineSchema(tables, vectorIndexes, aggregateIndexes)` keyed by index name —
+ * the schema attaches it to `tables[on].aggregateIndexes` so runtime consumers
+ * (DO + D1) read every index uniformly off the table definition.
+ */
+declare const defineAggregateIndex: (name: string, options: AggregateIndexOptions) => AggregateIndexDefinition;
+/**
+ * Options for the standalone `defineRankIndex(name, opts)` helper (DSL Shape B).
+ * Mirrors the inline `.rankIndex(...)` builder but takes the owning table via
+ * `table` so it can sit next to the schema map.
+ */
+interface RankIndexOptions {
+  partitionBy?: ReadonlyArray<string>;
+  sortBy: ReadonlyArray<{
+    direction?: "asc" | "desc";
+    field: string;
+  }>;
+  table: string;
+  where?: Record<string, unknown>;
+}
+/**
+ * Declare a standalone rank index. Pass the returned value to
+ * `defineSchema(tables, vectorIndexes, aggregateIndexes, rankIndexes)` keyed
+ * by index name — the schema attaches it to `tables[on].rankIndexes`.
+ */
+declare const defineRankIndex: (name: string, options: RankIndexOptions) => RankIndexDefinition;
+/**
+ * Build the application schema. The first argument is the table map; the
+ * optional second argument registers standalone `defineVectorIndex(...)`
+ * declarations (DSL Shape B) keyed by index name. The optional third argument
+ * registers standalone `defineAggregateIndex(...)` declarations (DSL Shape B);
+ * the optional fourth argument registers standalone `defineRankIndex(...)`
+ * declarations. Both are folded into the matching `tables[on].*Indexes` array
+ * so runtime backends read every index uniformly off the table definition.
+ */
+/**
+ * Schema with an in-place `.extend(plugin.extension)` method. Used so apps
+ * can compose plugin schemas: `defineSchema({...}).extend(authPlugin.extension)`.
+ *
+ * `extend` is non-mutating — returns a fresh `ExtendableSchema` containing
+ * the merged tables. Extension tables are auto-namespaced by the extension
+ * `key` (`buckets` → `ratelimit_buckets`), so the merged type carries the
+ * prefixed names via {@link PrefixedTables}. Chains:
+ * `defineSchema(...).extend(a).extend(b)` is the typed equivalent of merging
+ * `a`'s prefixed tables then `b`'s.
+ */
+type ExtendableSchema<T extends Record<string, TableDefinition>> = {
+  extend: <X extends Record<string, TableDefinition>, Key extends string>(extension: SchemaExtension<X> & {
+    readonly key: Key;
+  }) => ExtendableSchema<PrefixedTables<X, Key> & T>;
+  /**
+   * Pin every Durable Object the app reaches — shards, fan-out, subscriptions,
+   * the scheduler, and `ctx.containers` — to a Cloudflare data-residency
+   * jurisdiction (`"eu"`, `"us"`, `"fedramp"`). Codegen reads this off the
+   * schema and emits it into the generated worker's `createWorker({ jurisdiction })`
+   * (and `ctx.scheduler` / `ctx.containers`). Non-mutating: returns a fresh
+   * `ExtendableSchema`, so it composes with `.rls(...)` / `.extend(...)` in any order.
+   *
+   * ⚠️ **Set this once, before your first deploy — changing or removing it
+   * strands data.** A Durable Object name maps to a *different* ID in each
+   * jurisdiction, so toggling this on an existing app makes every shard, scheduler
+   * job, and session DO resolve to a NEW, empty DO; the previous data stays in the
+   * old jurisdiction's DOs and is no longer reachable. There is no in-place
+   * migration — you would have to export from the old jurisdiction and import
+   * into the new one.
+   *
+   * Note: this pins **DO-backed** state only. D1-backed state — `.global()`
+   * tables and `@lunora/auth` sessions alike — is governed by D1's own location
+   * settings, not this option.
+   * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+   */
+  jurisdiction: (jurisdiction: DurableObjectJurisdiction) => ExtendableSchema<T>;
+  /**
+   * Turn on secure-by-default RLS for the whole schema. Every table is then
+   * protected — the DO/D1 write path denies raw, non-RLS `ctx.db` access, so a
+   * procedure that forgets `.use(rls(...))` fails closed. Opt a table out with
+   * `.public()`. Non-mutating: returns a fresh `ExtendableSchema` carrying the
+   * mode, so `.rls("required")` composes with `.extend(...)` either order.
+   */
+  rls: (mode: "required") => ExtendableSchema<T>;
+} & Schema<T>;
+/**
+ * Columns every row carries implicitly (never part of a table's declared
+ * `shape`), so `.index()` may legitimately name them. The single source for
+ * both the compile-time allow-list (`TableBuilder["index"]`'s `fields` type,
+ * via `(typeof SYSTEM_INDEX_FIELDS)[number]`) and the runtime cross-check
+ * below (via `SYSTEM_INDEX_FIELDS_SET`) — declared once so the two can't
+ * drift apart.
+ */
+declare const SYSTEM_INDEX_FIELDS: readonly ["_commitSeq", "_creationTime", "_id"];
+/**
+ * Per-table, per-KIND index→declared-fields map: for each table, each index
+ * KIND (`index` | `rank` | `geo`) that has at least one declared index maps
+ * to a name→fields record for that kind only. Distilled by
+ * {@link indexFieldsFromSchema}; this is the shape `mask()`'s
+ * `MaskOptions.indexFields` expects (see `./mask/types`), so a table not
+ * present here (no declared indexes of any kind) is simply absent from the
+ * map rather than mapped to `{}`, and a kind with no declared indexes on a
+ * table that HAS other kinds is simply absent from that table's entry.
+ *
+ * Kept per kind (rather than one flat name→fields record) because the engine
+ * resolves `withIndex`/`withGeoIndex`/rank reads in THREE separate
+ * namespaces (`tableDefinition.indexes` / `.geoIndexes` / `.rankIndexes` —
+ * see `@lunora/shard-engine`'s `ctx-db.ts`), so the same name can legally and
+ * unambiguously denote a different index per kind. A flat map would let one
+ * kind's fields silently shadow another's for a colliding name, producing a
+ * wrong-namespace answer from the mask guard (checking the wrong index's
+ * fields) instead of the documented fail-open (missing lookup) — see plan 258.
+ */
+type IndexFieldsByTable = Readonly<Record<string, {
+  readonly geo?: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly index?: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly rank?: Readonly<Record<string, ReadonlyArray<string>>>;
+}>>;
+declare const indexFieldsFromSchema: (schema: Schema) => IndexFieldsByTable;
+declare const defineSchema: <T extends Record<string, TableDefinition>>(tables: T, vectorIndexes?: Record<string, VectorIndexDefinition>, aggregateIndexes?: Record<string, AggregateIndexDefinition>, rankIndexes?: Record<string, RankIndexDefinition>) => ExtendableSchema<T>;
+/** Default lifetime of a cached entry: one hour. */
+declare const DEFAULT_ACTION_CACHE_TTL_MS: number;
+declare const ACTION_CACHE_BARE_TABLE = "entries";
+/**
+ * The prefixed table name the extension produces at merge time. The handlers and
+ * helpers read/write this name directly so they always agree with the merged
+ * schema.
+ */
+declare const ACTION_CACHE_TABLE: "actionCache_entries";
+/**
+ * The slice of an index-range builder this preset uses. Mirrors `IndexRangeBuilder`
+ * field-for-field so the real `ctx.db` query builder is assignable — the generated
+ * `ctx.db.query` is typed per table, and a helper holding a runtime string needs
+ * the wide overload.
+ */
+interface ActionCacheIndexRange {
+  eq: (field: string, value: unknown) => ActionCacheIndexRange;
+  gt: (field: string, value: unknown) => ActionCacheIndexRange;
+  gte: (field: string, value: unknown) => ActionCacheIndexRange;
+  lt: (field: string, value: unknown) => ActionCacheIndexRange;
+  lte: (field: string, value: unknown) => ActionCacheIndexRange;
+}
+/** The slice of a `ctx.db` table query this preset relies on. */
+interface ActionCacheQuery {
+  first: () => Promise<Record<string, unknown> | null>;
+  order: (direction: "asc" | "desc") => ActionCacheQuery;
+  take: (limit: number) => Promise<Record<string, unknown>[]>;
+  withIndex: (indexName: string, range?: (q: ActionCacheIndexRange) => ActionCacheIndexRange) => ActionCacheQuery;
+}
+/**
+ * The slice of the ORM writer (`ctx.db` on an action or mutation) the helpers
+ * need. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
+ * directly.
+ */
+interface ActionCacheDatabase {
+  delete: <T extends string>(id: Id<T>) => Promise<void>;
+  insert: (table: string, document: Record<string, unknown>) => Promise<unknown>;
+  patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
+  query: (table: string) => ActionCacheQuery;
+}
+/** The slice of a function context the helpers need — just its writer. */
+interface ActionCacheContext {
+  db: ActionCacheDatabase;
+}
+/** Options for {@link defineActionCache}. */
+interface DefineActionCacheOptions {
+  /**
+   * Cap on the serialized size (bytes) of one cached value. A larger result is
+   * returned but not stored. Defaults to 512 KB; a non-finite value falls back
+   * to the default.
+   */
+  maxValueBytes?: number;
+  /**
+   * How long (ms) an entry stays fresh. A read past it reports a miss.
+   * Defaults to one hour.
+   */
+  ttlMs?: number;
+}
+/** The registered functions an action-cache component ships. */
+interface ActionCacheFunctions {
+  /**
+   * Internal mutation that hard-deletes expired entries, oldest first, and
+   * reports how many it removed. Every miss already reaps a few rows
+   * opportunistically, so an app with steady traffic stays bounded without
+   * this; schedule it on a cron to reclaim entries whose names went quiet.
+   *
+   * Returns `{ deleted }`; compare it against `limit` to decide whether to run
+   * again rather than assuming one pass drained the table. A caller-supplied
+   * `limit` is clamped — `take()` has no ceiling of its own.
+   */
+  purgeExpired: RegisteredMutation<{
+    limit: ReturnType<typeof v.optional>;
+  }, {
+    deleted: number;
+  }>;
+}
+/**
+ * SHA-256 of `name` and the serialized args, hex.
+ *
+ * Hashed rather than stored: call sites routinely pass an entire model request,
+ * which is tens of kilobytes. As an indexed column that would be wasteful and
+ * would run into column-size limits; a digest is fixed-width and indexes cleanly.
+ * The NUL separator keeps `("ab", "c")` and `("a", "bc")` from colliding.
+ * @param name the logical cache namespace (usually the action's name)
+ * @param argumentsKey the arguments, already serialized by {@link serializeArgs}
+ */
+declare const cacheKeyFor: (name: string, argumentsKey: string) => Promise<string>;
+/**
+ * The component shape {@link defineActionCache} returns: the extension, the
+ * registered functions, and the helpers an action calls directly.
+ */
+type ActionCacheComponent = {
+  functions: ActionCacheFunctions;
+  /** Drop the entry for exactly this `name` + `args`. Resolves whether or not one existed. */
+  invalidate: (context: ActionCacheContext, name: string, args: unknown) => Promise<void>;
+  /**
+   * Drop every entry under `name`, whatever its arguments.
+   *
+   * `complete` is `false` when the paging bound was reached with rows still
+   * matching — call again. A plain count could not tell "dropped all of them"
+   * apart from "dropped the first few thousand".
+   */
+  invalidateAll: (context: ActionCacheContext, name: string) => Promise<{
+    complete: boolean;
+    deleted: number;
+  }>;
+  /**
+   * Return the cached result for `name` + `args`, or run `compute` and cache it.
+   *
+   * `args` is keyed through the wire codec with sorted keys, so two calls agree
+   * whenever their arguments are structurally equal — key order does not matter,
+   * and `bigint` / `Date` / bytes arguments key distinctly rather than colliding.
+   */
+  wrap: <T>(context: ActionCacheContext, name: string, args: unknown, compute: () => Promise<T>) => Promise<T>;
+} & Component<{
+  [ACTION_CACHE_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
+/**
+ * The action-cache schema extension: one `entries` table, auto-namespaced to
+ * `actionCache_entries` at merge time.
+ */
+declare const actionCacheExtension: SchemaExtension<{
+  [ACTION_CACHE_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
+/**
+ * Build an action-cache {@link Component} — schema extension, `purgeExpired`, and
+ * the `wrap` / `invalidate` / `invalidateAll` helpers — wired to one TTL.
+ * @param options cache configuration (TTL, value-size cap).
+ * @returns a component bundling the extension, the functions, and the helpers.
+ */
+declare const defineActionCache: (options?: DefineActionCacheOptions) => ActionCacheComponent;
+/**
+ * Make any resolved storage capability bucket-aware so `ctx.storage.bucket(name)`
+ * always resolves. A `createBucketStorage(...)` result already carries
+ * `.bucket` / `.bucketName` and is returned as-is; a single `createStorage(...)`
+ * (or the no-storage stub) gets `.bucket(name)` as the identity — single-bucket
+ * apps address one binding under every name.
+ *
+ * Its `bucketName` tag is the storage's OWN name when it has one, and only
+ * `"default"` when it does not. The tag is what `storageRules(...)` matches
+ * `(bucket, operation)` rules against and what `assertRuleBucketsReachable`
+ * checks, while `getSignedUrl` signs with the name the storage was built with —
+ * stamping `"default"` over a `createStorage({ bucketName: "avatars" })` split
+ * those two apart, so URLs were signed as `avatars` while an `avatars` rule was
+ * rejected as unreachable and the storage was governed as `default`.
+ *
+ * Lives here rather than in `@lunora/server` because two packages need it and
+ * neither may depend on the other: `@lunora/server` re-exports it as the runtime
+ * counterpart `_generated/shard.ts` imports, and `@lunora/runtime` uses it to
+ * build `ctx.storage` for an HTTP action from the worker's own R2 bindings.
+ * Inlined into each `dist` by the bundler, so no dependency edge is created.
+ *
+ * The input is genuinely heterogeneous (a thunk result cast through `unknown`),
+ * so the signature is `unknown → unknown`; callers cast the result.
+ */
+declare const asBucketStorage: (raw: unknown) => unknown;
+/**
+ * Entry point for the procedure builder. `dataModel<DM>()` binds the generated
+ * `DataModel` (phantom for now), and `.create()` yields the public root builders
+ * plus their `internal*` counterparts.
+ */
+declare const initLunora: {
+  dataModel: <DataModel>() => DataModelInit<DataModel>;
+};
+/**
+ * Build the `ctx.secrets` reader from the worker `env`. `get(name)` resolves
+ * `env[name].get()` — the `secrets_store_secrets[]` binding of that name. An
+ * absent or non-Secrets-Store binding throws a directed error pointing at the
+ * wrangler config; the lookup is lazy, so an unused secret never resolves.
+ */
+declare const createSecrets: (env: Record<string, unknown>) => Secrets;
+/**
+ * Wrap a storage facade so it also accepts `deleteAfterCommit(key)`.
+ *
+ * Call once per dispatch, outside any read-stamping wrapper: `bucket()` delegates
+ * to the wrapped facade, so a sub-facade is still stamped by whatever wrapped it.
+ * @param storage the bucket-aware facade from `asBucketStorage`
+ */
+declare const withDeferredDeletes: (storage: unknown) => unknown;
+/** How a flush ended, so a caller can assert on it without this module owning a logger. */
+interface DeferredDeleteFlushResult {
+  /** How many keys were attempted. */
+  attempted: number;
+  /** Keys whose delete did not happen, with the reason. Empty when everything succeeded. */
+  failures: {
+    error: unknown;
+    key: string;
+  }[];
+}
+/**
+ * Delete everything queued on `context.storage`, draining the queue as it goes,
+ * and report each failure through `context.log`.
+ *
+ * Draining first means a second flush of the same dispatch is a no-op rather than
+ * a second round of deletes.
+ *
+ * Never throws. A flush runs after the write committed, so there is no longer
+ * anything to fail into: rejecting here could only turn a leaked object into a
+ * failed response for a write that already succeeded. Failures are logged and
+ * also returned, so a dispatch can call this and ignore the result.
+ * @param context the dispatch context; a context with no queued deletes is a no-op
+ */
+declare const flushDeferredDeletes: (context: unknown) => Promise<DeferredDeleteFlushResult>;
+/** The slice of a function context the window needs. */
+interface DeferredScheduleContext {
+  scheduler?: unknown;
+}
+/**
+ * The scheduler surface the facade wraps — the two methods it intercepts, plus
+ * whatever else the concrete scheduler carries (spread through untouched).
+ *
+ * A structural mirror rather than an import: `@lunora/scheduler`'s `Scheduler`,
+ * `@lunora/shard-engine`'s `SchedulerLike` and the test harness's fake all reach
+ * here, and their `target`/`args` parameters disagree. `never` parameters accept
+ * every one of them while still pinning the shape and the `Promise<string>` a
+ * caller depends on.
+ *
+ * `args` is REQUIRED here and that is load-bearing, not a typo. A parameter
+ * declared optional widens to `never | undefined` — i.e. `undefined` — and
+ * `undefined` is not assignable to the `ScheduleTargetArgs<T>` that
+ * `@lunora/scheduler`'s `Scheduler.runAfter`/`runAt` require, so with `args?`
+ * the one scheduler this facade exists to wrap was the one scheduler that could
+ * not be passed to it: `withDeferredSchedules(createScheduler(env))` failed to
+ * compile and every real call site had to cast. Required, `never` is assignable
+ * to anything, so the real `Scheduler`, the shard-engine mirror (whose `args` IS
+ * optional) and the harness fake all satisfy it.
+ */
+interface SchedulerLike {
+  runAfter: (delayMs: number, target: never, args: never, options?: never) => Promise<string>;
+  runAt: (timestampMs: number, target: never, args: never, options?: never) => Promise<string>;
+}
+/**
+ * Wrap a scheduler so `runAfter`/`runAt` can be held for a transaction.
+ *
+ * Call once per dispatch, OUTSIDE the read-stamping wrapper: the spread reads
+ * through that proxy's `get` trap, so `get`/`list` stay stamped.
+ *
+ * Generic so the facade comes back as the SAME scheduler type it was handed:
+ * every method but `runAfter`/`runAt` is spread through unchanged, and a caller
+ * that had to widen to `unknown` and cast back — the generated shard among them
+ * — could not be type-checked against the contract this docblock describes.
+ * @param scheduler the `ctx.scheduler` implementation to wrap
+ */
+declare const withDeferredSchedules: <S extends SchedulerLike>(scheduler: S) => S;
+/**
+ * Open a deferral window on `context.scheduler` and return its settle function.
+ *
+ * Call it around the transaction, then settle with `true` once the commit has
+ * landed (the buffered calls are dispatched, in order) or `false` when it rolled
+ * back (they are dropped). The window owns the calls made while IT was the
+ * innermost open one, so a rollback drops those and nothing else; on a commit an
+ * enclosing window takes them over, which is how a `ctx.runMutation` inside an
+ * open transaction hands its schedules to the span that actually commits them.
+ *
+ * A context whose scheduler was never wrapped gets an inert settle, so a caller
+ * needs no branch.
+ *
+ * The settle NEVER stops early. It runs after the commit, so a job that fails to
+ * enqueue can no longer fail the write that queued it — and abandoning the rest
+ * of the batch on the first failure loses jobs the caller was told (by the id it
+ * was handed) were scheduled. So every buffered call is attempted, in declaration
+ * order, and what failed is reported once at the end — as itself when one job
+ * failed, so its code and status survive, and as an `AggregateError` when several
+ * did.
+ * The caller's own post-commit work must still run: a settle that throws does not
+ * excuse skipping the deferred-delete flush behind it.
+ * @param context the dispatch context whose `scheduler` carries the queue
+ */
+declare const beginDeferredSchedules: (context: DeferredScheduleContext) => ((committed: boolean) => Promise<void>);
+/**
+ * Fields never written into a snapshot, whatever table they appear on.
+ *
+ * Names rather than types, because that is the only signal available here: a
+ * trigger sees values, not the column metadata that would say "this one is a
+ * secret". Extend it per app rather than relying on this list being complete.
+ */
+declare const DEFAULT_REDACTED_FIELDS: ReadonlyArray<string>;
+declare const DOCUMENT_HISTORY_BARE_TABLE = "versions";
+/** The prefixed table name the extension produces at merge time. */
+declare const DOCUMENT_HISTORY_TABLE: "documentHistory_versions";
+/** One recorded version, as {@link DocumentHistoryFunctions.listForDocument} returns it. */
+interface DocumentHistoryEntry {
+  /** The row as it stood after the write, redacted. Absent for a delete, and when `truncated`. */
+  doc?: Record<string, unknown>;
+  /** The row this version belongs to. */
+  documentId: string;
+  /** Which write produced this version. */
+  op: "delete" | "insert" | "update";
+  /** The row as it stood before the write, redacted. Absent for an insert, and when `truncated`. */
+  previous?: Record<string, unknown>;
+  /** When the write happened (epoch ms). */
+  recordedAt: number;
+  /** The table the row lives in. */
+  tableName: string;
+  /** `true` when the snapshots were dropped for exceeding `maxSnapshotBytes`. */
+  truncated?: boolean;
+}
+/** Options for {@link defineDocumentHistory}. */
+interface DefineDocumentHistoryOptions {
+  /**
+   * Cap on one serialized snapshot (bytes). Past it the entry is written
+   * without its snapshots and marked `truncated`. Defaults to 64 KB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Extra field names to drop from every snapshot, on top of the built-in
+   * secret-shaped defaults.
+   */
+  redact?: ReadonlyArray<string>;
+  /**
+   * How long (ms) an entry is kept. `vacuum` deletes entries older than this.
+   * Defaults to 90 days.
+   */
+  retentionMs?: number;
+}
+/** The registered functions a document-history component ships. */
+interface DocumentHistoryFunctions {
+  /**
+   * **Internal** query: the recorded versions of one row, newest first.
+   *
+   * Internal because an entry is a full row snapshot, including columns the
+   * table's own RLS hides — wrap it in a procedure of your own that applies
+   * whatever authorization the surface needs.
+   *
+   * Pass `before` to read the history as of an instant: the first entry back is
+   * the last version at or before it, which is what a point-in-time
+   * reconstruction needs.
+   */
+  listForDocument: RegisteredQuery<{
+    before: ReturnType<typeof v.optional>;
+    documentId: ReturnType<typeof v.string>;
+    limit: ReturnType<typeof v.optional>;
+  }, DocumentHistoryEntry[]>;
+  /**
+   * Internal mutation that deletes entries older than the retention window,
+   * oldest first, and reports how many it removed. Schedule it on a cron.
+   *
+   * Compare `deleted` against `limit` to decide whether to run again rather
+   * than assuming one pass drained the backlog.
+   */
+  vacuum: RegisteredMutation<{
+    limit: ReturnType<typeof v.optional>;
+  }, {
+    deleted: number;
+  }>;
+}
+/** The component shape {@link defineDocumentHistory} returns. */
+type DocumentHistoryComponent = {
+  functions: DocumentHistoryFunctions;
+  /**
+   * The `.triggers(...)` argument that records this table's versions —
+   * `.triggers(history.record)`.
+   *
+   * `after*` on all three ops: a `before*` handler runs while the write can
+   * still be aborted, and a history entry for a write that never happened is a
+   * lie the reader has no way to detect.
+   */
+  record: (t: TriggerBuilder) => Record<string, TriggerDefinition>;
+} & Component<{
+  [DOCUMENT_HISTORY_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
+/**
+ * The document-history schema extension: one `versions` table, auto-namespaced
+ * to `documentHistory_versions` at merge time.
+ */
+declare const documentHistoryExtension: SchemaExtension<{
+  [DOCUMENT_HISTORY_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
+/**
+ * Build a document-history {@link Component} — schema extension, the
+ * `.triggers()` recorder, and the `listForDocument` / `vacuum` functions.
+ * @param options history configuration (retention, redaction, snapshot cap).
+ * @returns a component bundling the extension, the functions, and the recorder.
+ */
+declare const defineDocumentHistory: (options?: DefineDocumentHistoryOptions) => DocumentHistoryComponent;
+/**
+ * Redact secrets from a free-form message. Masks, in order: any quoted value
+ * whose contents look like a credential (so a value surfaced as `received string
+ * "sk_live_…"` is masked even though the surrounding text is not a token); a
+ * `scheme://user:password@host` URL credential (the password segment); any
+ * known-prefix credential token wherever it appears, at any length; any value
+ * following a secret-named key in `KEY=value` / `KEY: value` form; and any
+ * remaining bare high-entropy ≥24-char token run anywhere in the message.
+ *
+ * This is BEST-EFFORT defense-in-depth, NOT a guarantee: a short, prefix-less
+ * secret under a non-secret-named key (and embedded credentials in shapes not
+ * enumerated here) can still slip through. Treat it as a backstop — prefer
+ * structured logging that never serializes raw env/secret fields in the first
+ * place over relying on post-hoc scrubbing of untrusted data.
+ *
+ * Exported because it is independently useful — call it before logging anything
+ * derived from `env`, request bodies, or thrown errors.
+ */
+declare const redactSecrets: (message: string) => string;
+/** One key's validation failure, secrets already redacted out of `message`. */
+interface EnvKeyFailure {
+  /** The env key that failed. */
+  key: string;
+  /** Redacted human-readable reason. */
+  message: string;
+}
+/**
+ * Thrown when one or more env keys are missing or fail validation. Carries the
+ * structured list of `failures` (each with the offending `key`) so callers can
+ * react programmatically; `message` is the joined, secret-redacted summary.
+ *
+ * Named export only (no default) per the repo export convention.
+ */
+declare class LunoraEnvError extends LunoraError {
+  readonly failures: ReadonlyArray<EnvKeyFailure>;
+  constructor(failures: ReadonlyArray<EnvKeyFailure>);
+}
+/** A record of `v.*` validators describing the expected env shape. */
+type EnvShape = Record<string, Validator>;
+/**
+ * The typed output of {@link defineEnv}. Optional validators (`v.optional(...)`)
+ * become optional keys; everything else is required. Mirrors how `InferArgs`
+ * derives an args object from a validator map.
+ */
+type InferEnv<S extends EnvShape> = { [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]>; } & { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]>; };
+/**
+ * The accessor returned by {@link defineEnv}. A typed view over an `env` object
+ * plus a `.parse(env)` escape hatch that validates every key eagerly.
+ *
+ * Call the accessor with the worker's `env` to get the typed, lazily-validated
+ * proxy: `const config = defineEnv({ … }); const { PORT } = config(env);`.
+ */
+interface EnvAccessor<S extends EnvShape> {
+  /** Validate every key eagerly and return the typed, plain (non-proxy) object. Use for fail-fast-at-boot. */
+  parse: (env: unknown) => InferEnv<S>;
+  /** Lazily-validated, per-key-cached typed view over `env`. Keys are validated on first access. */
+  (env: unknown): InferEnv<S>;
+}
+/**
+ * Define a typed, validated accessor over a Worker's `env`. Pass a record of
+ * `v.*` validators; receive an accessor that validates lazily per key (cached
+ * per `env` identity) and infers its output type from the validators.
+ *
+ * ```ts
+ * import { defineEnv, v } from "@lunora/server";
+ *
+ * const config = defineEnv({
+ *     STRIPE_KEY: v.string(),
+ *     PORT: v.optional(v.number()),
+ * });
+ *
+ * export default {
+ *     fetch(request, env) {
+ *         const { STRIPE_KEY, PORT } = config(env); // STRIPE_KEY: string, PORT?: number
+ *         // …
+ *     },
+ * };
+ * ```
+ *
+ * Throws {@link LunoraEnvError} (secrets redacted) when a key is missing or
+ * invalid — lazily on first access of that key, or eagerly via `config.parse(env)`.
+ */
+declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
+/**
+ * Minimal structural writer the facade binds over. Declared with **method**
+ * syntax (not arrow properties) so a more-specifically-typed writer — both
+ * `@lunora/do`'s `DatabaseWriterLike` and the RLS middleware's wrapped writer —
+ * stays assignable under bivariant parameter checking. That is the whole reason
+ * the shared helper can serve both callers, hence the rule exemption.
+ */
+interface FacadeWriterLike {
+  aggregate(tableName: string, options: unknown): Promise<unknown>;
+  count(tableName: string, where?: unknown): Promise<number>;
+  delete(id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }): Promise<void>;
+  deleteMany?(ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }, expectedTable?: string): Promise<{
+    deleted: number;
+  }>;
+  deleteWhere?(tableName: string, where: Record<string, unknown>, options?: {
+    limit?: number;
+  }): Promise<{
+    deleted: number;
+  }>;
+  findFirst(tableName: string, args?: unknown): Promise<unknown>;
+  findFirstOrThrow(tableName: string, args?: unknown): Promise<unknown>;
+  findMany(tableName: string, args?: unknown): Promise<unknown>;
+  get(id: string, expectedTable?: string): Promise<unknown>;
+  groupBy(tableName: string, options: unknown): Promise<unknown>;
+  insert(tableName: string, document: Record<string, unknown>): Promise<string>;
+  insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+    skipDuplicates?: boolean;
+  }): Promise<(string | null)[]>;
+  patch(id: string, patch: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  patchMany?(patches: ReadonlyArray<{
+    id: string;
+    patch: Record<string, unknown>;
+  }>, options?: {
+    limit?: number;
+  }, expectedTable?: string): Promise<{
+    patched: number;
+  }>;
+  patchWhere?(tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: Record<string, unknown>;
+  }, options?: {
+    limit?: number;
+  }): Promise<{
+    patched: number;
+  }>;
+  query(tableName: string): {
+    withGeoIndex(indexName: string, build: (q: unknown) => unknown): unknown;
+    withSearchIndex(indexName: string, search: (q: unknown) => unknown): unknown;
+  };
+  rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
+  rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
+  replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  restore?(id: string, expectedTable?: string): Promise<void>;
+}
+/** The per-table accessor object returned for the `ctx.db` table form. */
+interface FacadeEntry {
+  aggregate: (options: unknown) => Promise<unknown>;
+  count: (where?: unknown) => Promise<number>;
+  delete: (id: string) => Promise<void>;
+  deleteMany: {
+    (ids: ReadonlyArray<string>, options?: {
+      limit?: number;
+    }): Promise<{
+      deleted: number;
+    }>;
+    (args: {
+      limit?: number;
+      where: Record<string, unknown>;
+    }): Promise<{
+      deleted: number;
+    }>;
+  };
+  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
+  exists: (where?: unknown) => Promise<boolean>;
+  findFirst: (args?: unknown) => Promise<unknown>;
+  findFirstOrThrow: (args?: unknown) => Promise<unknown>;
+  findMany: (args?: unknown) => Promise<unknown>;
+  get: (id: string) => Promise<unknown>;
+  groupBy: (options: unknown) => Promise<unknown>;
+  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
+  hardDelete: (id: string) => Promise<void>;
+  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
+  /**
+   * Insert many documents into this table in one call. With
+   * `{ skipDuplicates: true }`, UNIQUE breaches resolve to `null` for that row
+   * instead of failing the batch. The typed facade narrows the return to
+   * `Id<T>[]` when skipDuplicates is not requested.
+   */
+  insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+    skipDuplicates?: boolean;
+  }) => Promise<(string | null)[]>;
+  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
+  patchMany: {
+    (patches: ReadonlyArray<{
+      id: string;
+      values: Record<string, unknown>;
+    }>, options?: {
+      limit?: number;
+    }): Promise<{
+      patched: number;
+    }>;
+    (args: {
+      limit?: number;
+      values: Record<string, unknown>;
+      where: Record<string, unknown>;
+    }): Promise<{
+      patched: number;
+    }>;
+  };
+  rank: (indexName: string, options: unknown) => Promise<unknown>;
+  rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
+  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
+  restore: (id: string) => Promise<void>;
+  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
+  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
+  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
+  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => unknown;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
+}
+/** Options accepted by the per-table `insert` accessor. */
+interface FacadeInsertOptions {
+  /**
+   * When `true`, a UNIQUE-constraint breach is swallowed: the insert becomes a
+   * silent no-op and resolves to `null` instead of throwing a `CONFLICT`. Any
+   * other error still propagates. Mirrors better-drizzle's `create({ skipDuplicates })`.
+   */
+  skipDuplicates?: boolean;
+}
+/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
+type UpsertTarget = ReadonlyArray<string> | string;
+/** Argument to the per-table `upsert` accessor. */
+interface UpsertArgs {
+  /** Document inserted when no existing row matches the `target`. */
+  create: Record<string, unknown>;
+  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
+  target: UpsertTarget;
+  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
+  update?: Record<string, unknown>;
+}
+/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
+interface UpsertResult {
+  created: boolean;
+  id: string;
+}
+/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
+interface UpsertManyArgs {
+  rows: ReadonlyArray<{
+    create: Record<string, unknown>;
+    update?: Record<string, unknown>;
+  }>;
+  target: UpsertTarget;
+}
+/**
+ * Bind a structural writer to one table, producing its `ctx.db` table accessor.
+ *
+ * The by-id accessors (`get`/`delete`/`patch`/`replace`) forward the bound
+ * `tableName` as `expectedTable` so the underlying writer scopes its id lookup
+ * to this table. Without it, a branded `Id<"posts">` carrying another table's
+ * id would resolve cross-table (the writer probes every table by id), letting
+ * `ctx.db.posts.get(foreignId)` read — or `.delete`/`.patch`/`.replace`
+ * mutate — a row in an unrelated table (IDOR). Writers that ignore the second
+ * argument keep their previous global behaviour; the scoping is opt-in via this
+ * forwarded name.
+ */
+declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) => FacadeEntry;
+/** The kitcn-style `ctx.orm` namespace over a per-table facade map. */
+interface OrmLike {
+  delete: (table: string, id: string) => Promise<void>;
+  insert: (table: string) => {
+    values: (document: Record<string, unknown>) => Promise<null | string>;
+  };
+  query: Record<string, FacadeEntry>;
+  replace: (table: string, id: string) => {
+    with: (document: Record<string, unknown>) => Promise<void>;
+  };
+  update: (table: string, id: string) => {
+    set: (values: Record<string, unknown>) => Promise<void>;
+  };
+}
+/** Build `ctx.orm` over a per-table facade map (table name → FacadeEntry). */
+declare const bindOrm: (facade: Record<string, FacadeEntry>) => OrmLike;
+/** HTTP verbs the typed {@link httpRoute} builder can bind to. */
+type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+/**
+ * Context handed to an HTTP action handler. A narrower view of {@link ActionContext}:
+ * HTTP actions run in the worker (the "action runtime"), separate from the
+ * transactional store, so there is no direct `db` / `vectors` surface — reach the
+ * data layer through `runQuery` / `runMutation` / `runAction`, which forward to
+ * the owning shard. `db`'s absence is principled: an HTTP handler is not
+ * transactional.
+ *
+ * `scheduler` and `storage` ARE present, because neither needs the shard — the
+ * scheduler talks to the scheduler DO, and R2 is a worker binding an HTTP
+ * handler can reach where an action does. Both are optional: each exists only
+ * when the app declared the matching capability (`.scheduler(...)` /
+ * `.storage(...)`) on the generated app builder.
+ *
+ * Omitting them was costly out of proportion to the gap. Without `scheduler`,
+ * "receive webhook → enqueue the real work → return 200" — the shape HTTP
+ * actions exist for — forced a hop through a mutation plus a closed allow-list
+ * of target strings, because a function reference cannot cross the RPC boundary
+ * and a free-form target on an unauthenticated endpoint is a "call any internal
+ * function" primitive. Without `storage`, any helper the ctx was threaded into
+ * had to be typed for its storage-touching branch, so a handler was barred from
+ * the helper even on the branches that never went near storage.
+ */
+type HttpActionCtx = {
+  readonly scheduler?: ActionCtx["scheduler"];
+  readonly storage?: ActionCtx["storage"];
+  /**
+   * The request's `ExecutionContext.waitUntil` — keep a promise alive past the
+   * returned `Response`. Present whenever the host supplied one (a real
+   * Cloudflare `ExecutionContext` always does; a partial context from a
+   * framework mount seam or a unit test may not), hence optional.
+   *
+   * An HTTP action is the one ctx that routinely returns before its work is
+   * done — "acknowledge the webhook in 200ms, then do the real thing" — and
+   * without this a handler had no way to defer anything: work started and not
+   * awaited is cancelled when the response resolves. Wrappers that need it
+   * (`@lunora/x402`'s `withX402`, whose receipt sink must outlive the
+   * response) read it structurally off whatever context they are handed, so
+   * its absence made them silently no-op rather than fail.
+   */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+} & Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery">;
+/** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
+type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
+/**
+ * The hono {@link https://hono.dev | Hono} environment used by {@link httpRouter}.
+ * The runtime injects the per-request {@link HttpActionCtx} on the private
+ * `__lunoraCtx` binding; the router's lifting middleware promotes it to
+ * `c.var.lunora` so handlers can read it as a typed variable.
+ */
+interface LunoraHttpEnv {
+  Bindings: Record<string, unknown> & {
+    __lunoraCtx?: HttpActionCtx;
+  };
+  Variables: {
+    lunora: HttpActionCtx;
+  };
+}
+/** The hono app type {@link httpRouter} returns. */
+type LunoraHttpApp = Hono<LunoraHttpEnv>;
+/** A compiled route handler: a hono handler that resolves to a raw {@link Response}. */
+type LunoraRouteHandler = (c: Context<LunoraHttpEnv>) => Promise<Response>;
+/**
+ * Wrap a `(ctx, request) => Response` handler as a hono handler. The raw escape
+ * hatch — mount it with `app.all(path, httpAction(fn))`. `ctx` is the
+ * runtime-injected {@link HttpActionCtx} lifted into `c.var.lunora` by
+ * {@link httpRouter}; `request` is the underlying `c.req.raw`.
+ */
+declare const httpAction: (handler: HttpActionHandler) => LunoraRouteHandler;
+/**
+ * Create the hono app for HTTP actions. Pre-wired with a middleware that lifts
+ * the runtime-injected `c.env.__lunoraCtx` into `c.var.lunora`, so both
+ * {@link httpAction} and the typed {@link httpRoute} builder can read the action
+ * context. The full hono surface is available — plugins, path params, `.route`:
+ *
+ * ```ts
+ * const app = httpRouter();
+ * app.use("*", cors());
+ * app.post("/webhook", httpAction(onWebhook));
+ * app.get("/users/:id", getUser);
+ * export default createWorker({ httpRouter: app, ... });
+ * ```
+ *
+ * The lifting middleware throws if the context is absent. `createWorker` injects
+ * it on every request the router sees, so this only trips when the app is run
+ * outside the runtime — a misconfiguration we surface loudly rather than let
+ * `c.var.lunora` be silently `undefined` despite its non-optional type.
+ */
+declare const httpRouter: () => LunoraHttpApp;
+/** The `{ ctx, searchParams, body, params }` a typed route handler receives. */
+interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator> {
+  body: InferArgs<Body>;
+  ctx: HttpActionCtx;
+  params: InferArgs<Params>;
+  searchParams: InferArgs<SearchParams>;
+}
+/**
+ * The `{ ctx, searchParams, params, request, signal }` a streaming HTTP
+ * handler receives. There is no parsed `body` — streams are typically GET, and
+ * the raw `request` is exposed if a handler needs to read the body itself.
+ * `signal` is tripped when the client disconnects.
+ * @experimental Part of the HTTP-SSE stream surface; reconnect/POST-body design questions are still open.
+ */
+interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
+  ctx: HttpActionCtx;
+  params: InferArgs<Params>;
+  request: Request;
+  searchParams: InferArgs<SearchParams>;
+  signal: AbortSignal;
+}
+/**
+ * A typed REST route under construction. `.searchParams()` / `.body()` /
+ * `.params()` accumulate validator maps (later calls merge, a colliding key
+ * wins) that decode the URL query, JSON body, and hono path params into the
+ * handler's typed `searchParams` / `body` / `params`. Like the procedure
+ * builder, `.output(validator)` defaults to the `undefined` sentinel — while
+ * unset the handler is generic over its own return; once set the handler must
+ * return that type and the result is parsed through the validator before
+ * serialization. `[Output] extends [undefined]` is tuple-wrapped so a union
+ * `Output` doesn't distribute and the test is for the exact sentinel.
+ *
+ * The terminal `.handler()` yields a {@link LunoraRouteHandler} — mount it
+ * directly with `app.get(path, route)`.
+ */
+interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
+  body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
+  /**
+   * Attach a `Cache-Control` header to the response. Only meaningful when
+   * Workers Cache is enabled in `wrangler.jsonc` (`"cache": { "enabled": true }`).
+   */
+  cacheControl: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+  /**
+   * Attach a `Cache-Tag` header to the response for tag-based purging via
+   * `ctx.cache.purge({ tags: [...] })`.
+   */
+  cacheTag: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+  handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
+  output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
+  params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
+  searchParams: <S extends ArgsValidator>(validators: S) => HttpRouteBuilder<S & SearchParams, Body, Params, Output>;
+  /**
+   * Terminal: declare this route as a streaming Server-Sent Events endpoint.
+   * The handler is an async generator (or any function returning an
+   * `AsyncIterable<R>`) that yields one chunk per SSE `data:` frame; on
+   * iterator completion the route writes a final `event: complete` frame; on
+   * throw, an `event: error` frame is written with `{code, message}` before
+   * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
+   * handler's yielded type.
+   * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+   */
+  stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+  /**
+   * Attach a `Vary` header to the response so Cloudflare stores separate
+   * cached variants per distinct value of the listed request headers.
+   */
+  vary: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+}
+/** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
+type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;
+/** The verb-keyed entry point: `httpRoute.get("/api/todos")…`. */
+interface HttpRoute {
+  delete: HttpRouteFactory;
+  get: HttpRouteFactory;
+  head: HttpRouteFactory;
+  options: HttpRouteFactory;
+  patch: HttpRouteFactory;
+  post: HttpRouteFactory;
+  put: HttpRouteFactory;
+}
+/**
+ * Typed REST route builder. Compiles down to a {@link LunoraRouteHandler}, so a
+ * typed route and a hand-written {@link httpAction} are interchangeable when
+ * mounted on {@link httpRouter}:
+ *
+ * ```ts
+ * export const listTodos = httpRoute
+ *     .get("/api/todos")
+ *     .searchParams({ limit: v.number(), q: v.optional(v.string()) })
+ *     .output(v.array(v.object({ id: v.string(), text: v.string() })))
+ *     .handler(async ({ ctx, searchParams }) => ctx.runQuery(api.todos.list, searchParams));
+ *
+ * export const getTodo = httpRoute
+ *     .get("/api/todos/:id")
+ *     .params({ id: v.string() })
+ *     .handler(async ({ ctx, params }) => ctx.runQuery(api.todos.get, params));
+ *
+ * const app = httpRouter();
+ * app.get("/api/todos", listTodos);
+ * app.get("/api/todos/:id", getTodo);
+ * ```
+ */
+declare const httpRoute: HttpRoute;
+/**
+ * True when `value` is safe to use as an HTTP header field-value: no CR, LF, or
+ * NUL. Guards against response-header injection / `Headers`-construction throws
+ * when reflecting attacker-influenced object metadata (e.g. a stored
+ * `Content-Type`). Exported (see the `export {}` at the file end) so an `httpAction`
+ * handler can guard a request-derived header value before writing it — the fix the
+ * `http_action_response_header_injection` advisor lint points to.
+ */
+declare const isSafeHeaderValue: (value: string) => boolean;
+/**
+ * Structural view of an R2 object body, as returned by `@lunora/storage`'s
+ * `download()`. Re-declared here (not imported) so `@lunora/server` takes no
+ * runtime dependency on `@lunora/storage`; the real binding satisfies the shape.
+ */
+interface StorageObjectBody {
+  /** The object body stream (`null` for a zero-byte object). */
+  body: ReadableStream | null;
+  etag: string;
+  httpMetadata?: {
+    contentType?: string;
+  };
+  key: string;
   /** Hex SHA-256, when R2 carries a checksum (surfaced by `@lunora/storage`). */
   sha256?: string;
   /** Base64 SHA-256 (RFC 9530 digest encoding), when R2 carries a checksum. */
@@ -605,8 +1837,22 @@ interface StorageRange {
   length: number;
   offset: number;
 }
-/** The minimal storage surface {@link serveStorageObject} needs: a metadata-rich `download`. */
-interface StorageDownloader {
+/**
+ * The minimal storage surface {@link serveStorageObject} needs: a metadata-rich
+ * `download`, plus the body-free `head` a range request resolves against.
+ *
+ * `head` is required rather than optional-with-a-fallback because the fallback
+ * is the bug: without it a ranged request has to start a full-object `download`
+ * just to learn the size, then throw that body away. `@lunora/storage`'s `head`
+ * already degrades internally to a 0-length ranged `get()` on a binding with no
+ * HEAD, so there is nothing a caller here could usefully do that it does not.
+ */
+interface StorageHead {
+  /** Object metadata with no body. `size` is the FULL object size (mirrors R2). */
+  head: (key: string) => Promise<Omit<StorageObjectBody, "body"> | null>;
+}
+/** The storage surface {@link serveStorageObject} reads through. */
+interface StorageDownloader extends StorageHead {
   download: (key: string, options?: {
     range?: StorageRange;
   }) => Promise<StorageObjectBody | null>;
@@ -615,149 +1861,428 @@ interface StorageDownloader {
 interface ContextWithStorage {
   storage: StorageDownloader;
 }
+/** The decision a {@link StorageServeAuthorizer} is asked to make. */
+interface StorageServeAuthzContext {
+  /** The object key the caller asked for — already resolved by the route. */
+  key: string;
+  /** The inbound request, so the gate can read the signed-URL query, a cookie, or a bearer. */
+  request: Request;
+}
+/**
+ * The authorization decision for THIS object — {@link serveStorageObject}'s
+ * required fourth argument, because the helper has no other way to know whether
+ * the caller may read `key`. Return `true` to stream, anything else for a
+ * **403**; a throwing gate is a denial too, never a 500 (fail closed, mirroring
+ * `@lunora/storage`'s `createUploadHandler`).
+ *
+ * For a signed-URL topology this is where `verifySignedUrl` goes:
+ * `async ({ request }) => (await verifySignedUrl(new URL(request.url), secret)).valid`.
+ */
+type StorageServeAuthorizer = (context: StorageServeAuthzContext) => boolean | Promise<boolean>;
+/**
+ * Stream a stored object as an HTTP {@link Response} from an `httpAction`
+ * handler, with correct `Content-Type`, `ETag`, and `Accept-Ranges: bytes`.
+ * Honors a single-range `Range` request → **206 Partial Content** with
+ * `Content-Range` + `Content-Length`; otherwise **200**. A missing object is a
+ * **404**; an out-of-bounds range is a **416** with a `Content-Range` of
+ * `bytes` star-slash-size.
+ *
+ * `authorize` runs FIRST and is mandatory: this helper reads bytes out of a
+ * bucket and hands them to whoever asked, so without a gate every mounted route
+ * is an open object store. It does not verify signed URLs by itself — pass
+ * `verifySignedUrl` (or a session check) as the gate.
+ *
+ * Every response carries `x-content-type-options: nosniff`, and any object whose
+ * content type is not a raster image or media file also carries
+ * `content-disposition: attachment` — an uploader-pinned `text/html` or
+ * `image/svg+xml` must never render on the serving origin.
+ *
+ * A range request resolves its window against a body-free `head()`, then issues
+ * ONE `download()` with the resolved `{ offset, length }` so R2 streams just
+ * those bytes — the slice is never buffered in the isolate, and no full-object
+ * body transfer is started only to be cancelled. A request that cannot produce a
+ * 206 at all (no `Range`, multi-range, malformed) skips the `head()` entirely and
+ * streams straight from a single `download()`. For very
+ * large objects a signed URL (`ctx.storage.getSignedUrl`) is still cheaper since
+ * the client then ranges against R2/CDN directly with no Worker hop.
+ *
+ * `cacheControl` defaults to `no-store`, which is right whenever `authorize`
+ * scopes the bytes to an identity. It is a parameter rather than something
+ * derived from `authorize` because a stub returning `true` during development
+ * would then silently publish a cache. An app fronting a genuinely public
+ * bucket passes its own value; `content-disposition` and `nosniff` stay
+ * unconditional either way. Note the default also defeats conditional
+ * revalidation, so the `etag` computed here can never answer a 304.
+ */
+declare const serveStorageObject: (context: ContextWithStorage, key: string, request: Request, authorize: StorageServeAuthorizer, cacheControl?: string) => Promise<Response>;
+/**
+ * What the worker does with a resolver's identity when it fails contract
+ * validation (a forged / malformed claim set arriving from an untrusted token).
+ * `"anonymous"` (default, safe) treats the request as anonymous, so the bad
+ * identity never reaches a policy as a valid identity (`ctx.auth.userId`
+ * becomes `undefined`). `"reject"` fails the request closed (a `401`) — use
+ * when a malformed credential should be a hard error, not a silent downgrade.
+ */
+type IdentityRejectMode = "anonymous" | "reject";
+/** Options for {@link defineIdentity}. */
+interface DefineIdentityOptions {
+  /**
+   * How to handle a resolver identity that violates the contract at the trust
+   * boundary. Defaults to `"anonymous"` (a forged claim set is downgraded to
+   * anonymous rather than flowing in as an unchecked cast).
+   */
+  readonly onInvalid?: IdentityRejectMode;
+}
+/** Result of validating a candidate identity against the contract. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
 /**
-* Stream a stored object as an HTTP {@link Response} from an `httpAction`
-* handler, with correct `Content-Type`, `ETag`, and `Accept-Ranges: bytes`.
-* Honors a single-range `Range` request → **206 Partial Content** with
-* `Content-Range` + `Content-Length`; otherwise **200**. A missing object is a
-* **404**; an out-of-bounds range is a **416** with a `Content-Range` of
-* `bytes` star-slash-size.
-*
-* A range request re-issues the `download()` with the resolved `{ offset, length }`
-* window so R2 streams only those bytes back to the Worker — the slice is never
-* buffered in the isolate. The first `download()` is used only for the object's
-* size + metadata (its body is left unread and cancelled). For very large
-* objects a signed URL (`ctx.storage.getSignedUrl`) is still cheaper since the
-* client then ranges against R2/CDN directly with no Worker hop.
-*/
-declare const serveStorageObject: (context: ContextWithStorage, key: string, request: Request) => Promise<Response>;
+ * A declared identity claim contract. Carries the codegen discovery brand, the
+ * declared claim validators, the reject policy, and a runtime `validate`. The
+ * `TClaims` type parameter is the inferred claim shape (always extending
+ * `{ userId: string }`); it is phantom (no runtime field) and exists so
+ * `@lunora/codegen` and {@link InferIdentity} can recover the type.
+ */
+interface IdentityContract<TClaims extends {
+  userId: string;
+} = {
+  userId: string;
+}> {
+  /**
+   * Phantom carrier for the inferred claim type. Never populated at runtime
+   * (`undefined`); present only so the type flows to codegen / {@link InferIdentity}.
+   */
+  readonly __claimType?: TClaims;
+  readonly __lunoraIdentity: true;
+  /** The declared claim validators (a `@lunora/values` validator map). */
+  readonly claims: ValidatorMap;
+  /** Reject policy applied at the trust boundary. See {@link IdentityRejectMode}. */
+  readonly onInvalid: IdentityRejectMode;
+  /**
+   * Validate a resolver's returned identity against the declared claims. On
+   * success the caller keeps the original identity untouched (so undeclared
+   * claims are forwarded verbatim, preserving today's behaviour); on failure
+   * the worker applies the `onInvalid` policy.
+   */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/** Recover the declared claim type from a {@link defineIdentity} contract. */
+type InferIdentity<T> = T extends IdentityContract<infer TClaims> ? TClaims : never;
+/**
+ * Declare the identity claim contract. `claims` is a `@lunora/values` validator
+ * map whose inferred type must extend `{ userId: string }` — if it does not
+ * (e.g. `userId` is missing or not a required string), the argument type
+ * collapses to `never` and the call fails to typecheck.
+ * @example
+ * export const identity = defineIdentity({ userId: v.string(), tenantId: v.optional(v.string()), scopes: v.optional(v.array(v.string())) });
+ */
+declare const defineIdentity: <A extends ValidatorMap>(claims: InferValidatorMap<A> extends {
+  userId: string;
+} ? A : never, options?: DefineIdentityOptions) => IdentityContract<InferValidatorMap<A> & {
+  userId: string;
+}>;
 /** Handler for a connection-lifecycle hook. */
 type LifecycleHandler = (context: MutationCtx, event: LifecycleEvent) => Promise<void> | void;
+/** Handler for a shard-init hook. */
+type ShardInitHandler = (context: MutationCtx, event: ShardInitEvent) => Promise<void> | void;
 /** Register a hook that fires once when a client's WebSocket connects. */
 declare const onConnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
 /** Register a hook that fires once when a client's WebSocket disconnects. */
 declare const onDisconnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
 /**
-* Context handed to a {@link MaskFn} (and to {@link MaskOptions.bypass}). The
-* `auth` shape mirrors RLS's `PolicyContext.auth` one-for-one — same identity
-* resolver, same `can(...)` permission check — so an author can branch a mask
-* on the caller's role/permission. `row` is the full pre-mask row the column
-* belongs to; `column` is the column currently being masked. Both are absent
-* when the context is used for the procedure-wide `bypass` check (no specific
-* cell is in play yet).
-*/
-interface MaskContext<Context = unknown> {
-  readonly auth: {
-    /** `true` when any of the request's `roles` grants `permission` (see {@link MaskOptions.roles}). Fails closed for unregistered roles. */
-    readonly can: (permission: Permission | string) => boolean;
-    readonly identity?: Record<string, unknown> | null;
-    readonly roles: ReadonlyArray<string>;
-    readonly userId: null | string;
-  };
-  /** The column currently being masked. Present only inside a per-cell {@link MaskFn}. */
-  readonly column?: string;
-  readonly ctx: Context;
-  /** The full pre-mask row the masked cell belongs to. Present only inside a per-cell {@link MaskFn}. */
-  readonly row?: Record<string, unknown>;
+ * Register a hook that fires ONCE per Durable Object instance, before any
+ * handler on that instance can run — the re-init half of `.memory()` tables.
+ *
+ * A shard is not a process that stays up. Cloudflare reconstructs the Durable
+ * Object after every eviction, and a shard whose sockets are hibernating is
+ * evicted routinely, so "cold start" is a steady-state event rather than a rare
+ * one. Everything the shard held in memory is gone at that moment: the JS heap,
+ * and every `.memory()` table, which the framework has already cleared by the
+ * time this hook runs.
+ *
+ * ```ts
+ * // lunora/init.ts
+ * import { onShardInit } from "@lunora/server";
+ *
+ * export const warm = onShardInit(async (ctx, event) => {
+ *     // Rebuild ephemeral state from the durable tables that outlived us.
+ *     for await (const member of ctx.db.roomMembers.iterate({ where: { roomId: event.shardKey } })) {
+ *         await ctx.db.presence.insert({ userId: member.userId, status: "away" });
+ *     }
+ * });
+ * ```
+ *
+ * **Ordering is the guarantee.** Memory tables are cleared, then every init hook
+ * runs to completion, and only then does the dispatch that triggered the cold
+ * start proceed. No handler, subscription refresh, alarm, or shape poke can
+ * observe a memory table in the gap. Hooks run sequentially in manifest order,
+ * so one may depend on state an earlier one wrote.
+ *
+ * **It is a mutation, and it runs on every cold start.** Keep it cheap and keep
+ * it idempotent: it is on the latency path of the request that woke the shard,
+ * and it will run again — many times — over the shard's life. Writing to durable
+ * tables from here is legal and occasionally right, but remember it is a
+ * rebuild, not a migration; use `defineMigration` for anything that should
+ * happen once.
+ *
+ * **No caller identity.** The hook dispatches as a trusted system call with no
+ * request identity — `ctx.auth` is anonymous and RLS does not apply even under
+ * `.rls("required")`, exactly as for a cron tick or a migration. RLS scopes rows
+ * to a user and an init hook has none, so `ctx.db` here sees every row: scope
+ * your reads yourself. (`onConnect`/`onDisconnect` are the opposite case — they
+ * carry the socket's verified identity and stay RLS-guarded.)
+ *
+ * A throw is logged and does NOT fail the dispatch that woke the shard — an init
+ * hook that cannot rebuild presence must not take the whole shard down with it.
+ * The table is then cleared but not refilled, so reads see nothing. A failure
+ * EARLIER, before the framework's clear runs, instead leaves the previous
+ * instance's rows in place: a memory table's rows live in SQLite until they are
+ * deleted, so an eviction on its own does not remove them.
+ */
+declare const onShardInit: (handler: ShardInitHandler) => RegisteredLifecycleHook;
+/** Default `limit` when the caller doesn't ask for one. */
+declare const DEFAULT_LIMIT = 25;
+/** Default ceiling on `limit`, so one request can't ask for an unbounded page. */
+declare const DEFAULT_MAX_LIMIT = 100;
+/**
+ * Per-field predicate accepted for a declared filter column. An alias of the
+ * `ctx.db` `where` DSL's own operator type rather than a copy, so the two cannot
+ * drift as operators are added.
+ */
+type ListFilterOperators<T> = WhereOperators<T>;
+/**
+ * The filter allow-list a caller may declare: a subset of the document's own
+ * columns, each with a validator for that column's type. Constraining the KEYS to
+ * `keyof Doc` is what turns a typo'd or renamed column into a compile error
+ * instead of a predicate that silently never matches.
+ */
+type ListFilterShape<TDocument> = { [K in keyof TDocument & string]?: Validator<TDocument[K]>; };
+/** The `where` argument: each declared filter column, optionally, as a bare value or an operator object. */
+type ListWhere<F> = { [K in keyof F]?: Infer<NonNullable<F[K]>> | ListFilterOperators<Infer<NonNullable<F[K]>>>; };
+/** One `orderBy` entry. `direction` defaults to `"asc"`. */
+interface ListOrderByEntry<O extends string> {
+  direction?: "asc" | "desc";
+  field: O;
+}
+/** The decoded arguments a {@link defineListArgs} endpoint receives. */
+interface ListArgsValue<F, O extends string> {
+  cursor?: null | number | string;
+  limit?: number;
+  orderBy?: ListOrderByEntry<O>[];
+  where?: ListWhere<F>;
 }
-/**
-* A custom masking function. Receives the raw cell value and the
-* {@link MaskContext}, returns the value to surface. Use it for partial masks
-* (`maskMiddle(phone)`), role-aware reveals (`ctx.auth.can(...) ? value : null`),
-* or format-preserving tokens. A function that **throws** fails closed — the
-* cell is redacted to `null`, never leaked raw.
-*/
-type MaskFn<Context = unknown> = (value: unknown, context: MaskContext<Context>) => unknown;
-/**
-* How a column is masked:
-*
-* - `"redact"` — drop the value to `null`. The simplest, safest strategy, and
-* the right choice for any value that must actually be kept secret.
-* - `"hash"` — replace with a stable token (unsalted 32-bit FNV-1a hex) so the
-* same input always yields the same token (joinable/groupable client-side).
-* **This is NOT a confidentiality control.** It is a non-cryptographic,
-* unsalted, deterministic, narrow (~2^32) digest: low-entropy values (emails,
-* phone numbers, SSNs) are brute-force-recoverable by the very caller you are
-* masking from, and identical values always produce identical tokens across
-* rows/columns/tenants (enabling correlation). Use `"hash"` ONLY when you want a
-* stable pseudonym for grouping/joining and leaking the value is acceptable —
-* never to hide sensitive PII. For PII that must stay hidden, use `"redact"`.
-* - a {@link MaskFn} — author-defined transform (partial mask, role-aware reveal).
-*/
-type MaskStrategy<Context = unknown> = "hash" | "redact" | MaskFn<Context>;
-/** Per-column strategy map for one table: `{ email: "redact", phone: maskMiddle }`. */
-type MaskColumns<Context = unknown> = Record<string, MaskStrategy<Context>>;
-/**
-* The mask declaration passed to `mask(...)`: a table → column → strategy map.
-* Deliberately a plain object literal so the codegen feeder can statically read
-* which columns a procedure masks (powering the `mask_uncovered_pii_column`
-* advisor lint), exactly as the RLS feeder reads policy tables.
-*/
-type MaskPolicies<Context = unknown> = Record<string, MaskColumns<Context>>;
-/**
-* Options for `mask(policies, options)`.
-*
-* - `roles` registers the role→permission grants that back `ctx.auth.can(...)`
-* inside a {@link MaskFn} — identical to `rls(policies, { roles })`. A role
-* not listed grants no permissions (fails closed for unknown roles).
-* - `bypass` is a procedure-wide escape hatch: when it returns `true` the whole
-* mask is skipped (the caller sees raw values). Use it for a privileged
-* viewer — `bypass: ({ auth }) => auth.can("pii:view")`. Prefer this over
-* branching every column when an entire class of caller should see clear data.
-*/
-interface MaskOptions<Context = unknown> {
-  readonly bypass?: (context: MaskContext<Context>) => boolean;
-  readonly roles?: ReadonlyArray<Role>;
+interface DefineListArgsConfig<F, O extends string> {
+  /** `limit` applied when the caller omits one. Defaults to 25. */
+  readonly defaultLimit?: number;
+  /**
+   * Allow-list of filterable columns. Publish only columns an index can serve;
+   * anything absent here is unreachable from the client.
+   */
+  readonly filter: F;
+  /** Ceiling on `in` / `notIn` array length — one bound parameter each. Defaults to 100. */
+  readonly maxInValues?: number;
+  /** Ceiling on `limit`; a larger request is clamped down, not rejected. Defaults to 100. */
+  readonly maxLimit?: number;
+  /** Ceiling on how many `orderBy` entries a request may ask for. Defaults to 8. */
+  readonly maxOrderBy?: number;
+  /** Allow-list of sortable columns. Pass `[]` to fix the order server-side. */
+  readonly orderBy: ReadonlyArray<O>;
+}
+/** The validator map handed to `.input()`. Typed precisely so `args` infers end-to-end. */
+interface ListArgsValidators<F, O extends string> {
+  cursor: ColumnValidator<null | number | string | undefined, null | number | string | undefined>;
+  limit: ColumnValidator<number | undefined, number | undefined>;
+  orderBy: ColumnValidator<ListOrderByEntry<O>[] | undefined, ListOrderByEntry<O>[] | undefined>;
+  where: ColumnValidator<ListWhere<F> | undefined, ListWhere<F> | undefined>;
+}
+interface ListArgsSpec<TDocument, F, O extends string> {
+  /** Spread into `.input(...)` — `{ cursor, limit, orderBy, where }`. */
+  readonly args: ListArgsValidators<F, O>;
+  /**
+   * Translate the decoded arguments into the `findMany` options object:
+   * `limit` clamped into `[1, maxLimit]`, `orderBy` reshaped from
+   * `{ field, direction }[]` into `ctx.db`'s `{ column: direction }[]`.
+   *
+   * Returns `QueryArgs<Doc>` — bound to the table, not free — so a mismatch
+   * between what this helper declares and what the table actually holds is a
+   * compile error at the `findMany` call site.
+   */
+  readonly toQueryArgs: (args: ListArgsValue<F, O>) => QueryArgs$2<TDocument>;
+}
+/** Clamp a caller-supplied `limit` into `[1, maxLimit]`; a non-finite value falls back to `fallback`. */
+declare const clampLimit: (limit: number | undefined, fallback: number, maxLimit: number) => number;
+/**
+ * Declare the filter / sort / page arguments for a list endpoint, plus the
+ * translation into `ctx.db.<table>.findMany(...)` options. See the module docs
+ * for the shape and the reasoning behind it.
+ *
+ * Curried on the document type: `defineListArgs<Doc<"messages">>()({ … })`. The
+ * extra `()` buys the thing that matters — with `Doc` bound, `filter` keys and
+ * `orderBy` entries are checked against the table's real columns, so a typo or a
+ * column renamed out from under the endpoint is a COMPILE error instead of a
+ * predicate that silently matches nothing. TypeScript has no partial type-argument
+ * inference, so binding `Doc` explicitly while still inferring `F` and `O` from
+ * the config requires the second call.
+ */
+declare const defineListArgs: <TDocument>() => <F extends ListFilterShape<TDocument>, O extends keyof TDocument & string>(config: DefineListArgsConfig<F, O>) => ListArgsSpec<TDocument, F, O>;
+/**
+ * Structural mirrors of `@lunora/shard-engine`'s rank-page-row shapes
+ * (`RankPageRowKey` / `RankPageRow` / `ShardRankPageResult`) — the return type
+ * of the writer's `rankPageRows` seam, the cross-shard companion to
+ * `rankPage`.
+ *
+ * Shared by `../rls/middleware` and `../mask/middleware`: both wrap
+ * `rankPageRows` structurally (no `@lunora/shard-engine` import, mirroring how
+ * every other method on their `DatabaseWriterLike`/`MaskDatabase` projections
+ * is hand-mirrored rather than imported) and both need the exact same result
+ * shape to type their overrides. A single copy here means the two wrappers
+ * can't drift out of lockstep with each other — see AGENTS.md's platform
+ * parity note on `ShardSqlExec` and the canonical binding `*Like` projections
+ * shipping wrong for exactly this reason (two hand-maintained mirrors of one
+ * upstream type).
+ */
+/** Structural mirror of `@lunora/shard-engine`'s `RankPageRowKey`. */
+interface RankPageRowKeyLike {
+  partitionKey: string;
+  rowId: string;
+  sortValues: ReadonlyArray<unknown>;
 }
-interface QueryPage$1 {
-  continueCursor: null | string;
-  isDone: boolean;
-  page: Record<string, unknown>[];
+/** Structural mirror of `@lunora/shard-engine`'s `RankPageRow`. */
+interface RankPageRowLike {
+  doc: Record<string, unknown>;
+  key: RankPageRowKeyLike;
+}
+/** Structural mirror of `@lunora/shard-engine`'s `ShardRankPageResult` — the `rankPageRows` return shape. */
+interface ShardRankPageResultLike {
+  directions: ReadonlyArray<"asc" | "desc">;
+  hasMore: boolean;
+  rows: ReadonlyArray<RankPageRowLike>;
 }
+/**
+ * Structural mirror of `@lunora/do`'s `QueryArgs` and `CountArgs`. The
+ * runtime ORM in `@lunora/do`/`@lunora/d1` reads `baseWhere` /
+ * `restrictsCounts` straight off these option objects, so as long as the
+ * fields here stay name-compatible the wrapper is portable across the two
+ * dialects without an inter-package dependency.
+ */
 interface QueryArgs$1 {
-  baseWhere?: unknown;
+  baseWhere?: WhereInput;
   cursor?: null | string;
   limit?: number;
-  where?: unknown;
+  orderBy?: ReadonlyArray<unknown>;
+  /**
+   * Per-target-table read filter the RLS wrapper attaches so a `with` relation
+   * is policy-filtered on its own hop (see `@lunora/do`'s `QueryArgs`). Mirrors
+   * the top-level read: `(table) => readBase(table).baseWhere`.
+   */
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
   with?: Record<string, unknown>;
 }
+interface CountArgs {
+  baseWhere?: WhereInput;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `AggregateOptions` — only the fields the wrapper touches. */
 interface AggregateArgs$1 {
+  baseWhere?: WhereInput;
   field?: string;
   op: string;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
 }
+/** Structural mirror of `@lunora/do`'s `GroupByOptions`. */
 interface GroupByArgs$1 {
   agg?: {
     field?: string;
     op: string;
   };
+  baseWhere?: WhereInput;
   by: ReadonlyArray<string>;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankOptions`. */
+interface RankArgs {
+  baseWhere?: WhereInput;
+  restrictsCounts?: boolean;
+  row: Record<string, unknown> | string;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankBeforeOptions`. */
+interface RankBeforeArgs {
+  partitionKey: string;
+  restrictsCounts?: boolean;
+  rowId: string;
+  sortValues: ReadonlyArray<unknown>;
+}
+/** Structural mirror of `@lunora/do`'s `RankPageOptions`. */
+interface RankPageArgs {
+  baseWhere?: WhereInput;
+  cursor?: null | string;
+  restrictsCounts?: boolean;
+  take?: number;
+  where?: WhereInput;
+}
+interface QueryPage$1 {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
 }
 interface TableReaderLike$1 {
   collect: () => Promise<Record<string, unknown>[]>;
   filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike$1;
   first: () => Promise<Record<string, unknown> | null>;
-  order: (direction: "asc" | "desc") => TableReaderLike$1;
   paginate: (options: {
     cursor?: null | string;
     numItems: number;
   }) => Promise<QueryPage$1>;
   take: (limit: number) => Promise<Record<string, unknown>[]>;
-  unique: () => Promise<Record<string, unknown> | null>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => TableReaderLike$1;
   withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike$1;
   withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike$1;
 }
 /**
-* Structural projection of the runtime ORM writer — the same subset
-* `../rls/middleware` mirrors, so the wrapper is interchangeable between
-* `@lunora/do`'s and `@lunora/d1`'s `DatabaseWriterLike` without an
-* inter-package dependency. `rankBefore` is optional (the D1 twin omits it).
-*/
-interface MaskDatabase {
+ * Structural projection of the runtime ORM writer. The wrapper relies only
+ * on these fields, so it's interchangeable between `@lunora/do`'s
+ * `DatabaseWriterLike` and `@lunora/d1`'s `DatabaseWriterLike`.
+ */
+interface DatabaseWriterLike {
+  /**
+   * Reduce matching rows to a scalar. The RLS wrapper AND-merges the read
+   * `baseWhere` into `options` so the reduction only sees policy-visible rows
+   * (safe: an aggregate scoped to `where` never reveals a hidden row — see
+   * `@lunora/do`'s `RestrictableQueryOptions`). Required: the only writer ever
+   * wrapped is `@lunora/do`'s `createShardCtxDb`, which always implements it.
+   */
   aggregate: (tableName: string, options: AggregateArgs$1) => Promise<null | number>;
-  count: (tableName: string, whereOrArgs?: unknown) => Promise<number>;
-  delete: (id: string, expectedTable?: string) => Promise<void>;
+  count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
+  delete: (id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }) => Promise<void>;
+  /** Uncapped, chunked erase of a whole table. The RLS wrapper gates each row like a single delete. */
+  deleteAll?: (tableName: string, options?: {
+    chunkSize?: number;
+    hard?: boolean;
+  }) => Promise<{
+    deleted: number;
+  }>;
   deleteMany: (ids: ReadonlyArray<string>, options?: {
     limit?: number;
+  }, expectedTable?: string) => Promise<{
+    deleted: number;
+  }>;
+  deleteWhere?: (tableName: string, where: WhereInput, options?: {
+    limit?: number;
   }) => Promise<{
     deleted: number;
   }>;
@@ -765,6 +2290,11 @@ interface MaskDatabase {
   findFirstOrThrow: (tableName: string, args?: QueryArgs$1) => Promise<Record<string, unknown>>;
   findMany: (tableName: string, args?: QueryArgs$1) => Promise<QueryPage$1>;
   get: (id: string, expectedTable?: string) => Promise<Record<string, unknown> | null>;
+  /**
+   * Group + reduce. Same `baseWhere` injection as `aggregate`: the per-group
+   * reduction is scoped to policy-visible rows, so a group count tallies only
+   * rows the caller may read. Required for the same reason as `aggregate`.
+   */
   groupBy: (tableName: string, options: GroupByArgs$1) => Promise<ReadonlyArray<{
     key: Record<string, unknown>;
     value: null | number;
@@ -772,7 +2302,20 @@ interface MaskDatabase {
   insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
   insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
+    skipDuplicates?: boolean;
+  }) => Promise<(string | null)[]>;
+  insertManyUnsafe: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    allowExplicitId?: boolean;
+    limit?: number;
   }) => Promise<string[]>;
+  /**
+   * Optional table-aware lookup. The underlying writer (e.g. `@lunora/do`)
+   * already knows the owning table of an id internally, so it can return
+   * `{ row, tableName }` in a single round-trip. When present, the RLS wrapper
+   * uses it to collapse the per-call membership-probe fan-out (1 `get` + N
+   * `findFirst` across every policy table) down to one lookup. Writers that
+   * don't implement it fall back to the probe path.
+   */
   lookupById?: (id: string, expectedTable?: string) => Promise<null | {
     row: Record<string, unknown>;
     tableName: string;
@@ -783,511 +2326,497 @@ interface MaskDatabase {
     patch: Record<string, unknown>;
   }>, options?: {
     limit?: number;
-  }) => Promise<void>;
+  }, expectedTable?: string) => Promise<{
+    patched: number;
+  }>;
+  patchWhere?: (tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: WhereInput;
+  }, options?: {
+    limit?: number;
+  }) => Promise<{
+    patched: number;
+  }>;
   query: (tableName: string) => TableReaderLike$1;
-  rank: (tableName: string, indexName: string, options: unknown) => Promise<null | {
+  /**
+   * Rank a row within its partition. A position is a count-of-rows-before, so
+   * — exactly like `count()` — it can't be trusted in an RLS-restricted
+   * reader: the wrapper fails it closed with `COUNT_RLS_UNSUPPORTED`. Required
+   * for the same reason as `aggregate`.
+   */
+  rank: (tableName: string, indexName: string, options: RankArgs) => Promise<null | {
     position: number;
     total: number;
   }>;
-  rankBefore?: (tableName: string, indexName: string, options: unknown) => Promise<{
+  /** Cross-shard rank primitive — same count-of-before RLS hazard as `rank`; failed closed under a read policy. */
+  rankBefore?: (tableName: string, indexName: string, options: RankBeforeArgs) => Promise<{
     before: number;
     total: number;
   }>;
-  rankPage: (tableName: string, indexName: string, options?: unknown) => Promise<QueryPage$1>;
+  /**
+   * Sorted pagination over a rank companion. The companion stores only the
+   * partition + sort keys + id, so an arbitrary read `baseWhere` can't be
+   * enforced against it (and re-filtering the fetched rows would break page
+   * sizing). RLS therefore fails it closed rather than leak hidden rows.
+   * Required for the same reason as `aggregate`.
+   */
+  rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage$1>;
+  /**
+   * Cross-shard companion to `rankPage`: same ranked slice, but each row
+   * keeps its rank-key tuple for the query coordinator's k-way merge. Same
+   * count-of-partition RLS hazard as `rankPage` — failed closed under a read
+   * policy for the identical reason (see `rankPage` above).
+   */
+  rankPageRows?: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<ShardRankPageResultLike>;
   replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
+  /**
+   * Whole-shard erase. The RLS wrapper deliberately **fails this closed** rather
+   * than wrapping it — see the wrapper's `wipeShard`.
+   */
+  wipeShard?: (options?: {
+    chunkSize?: number;
+    exclude?: ReadonlyArray<string>;
+    tables?: ReadonlyArray<string>;
+  }) => Promise<{
+    deleted: number;
+    tables: Record<string, number>;
+  }>;
 }
-/** Roles list source on the context. Tolerant of older auth states (mirrors RLS's `AuthLike`). */
-type AuthLike$1 = {
+/**
+ * What a procedure's `ctx.db` must structurally satisfy for the middleware
+ * to wrap it. We deliberately mirror `@lunora/do`'s `DatabaseWriterLike`
+ * rather than `@lunora/server`'s nominal `DatabaseWriter`/`DatabaseReader`:
+ * the runtime adapter that flows in is the `DatabaseWriterLike`-shaped one,
+ * and structural matching keeps this module free of an `@lunora/do`-typed
+ * `ctx`.
+ */
+type RlsDatabase = DatabaseWriterLike;
+/**
+ * The slice of `ctx.auth` the policy middlewares read.
+ *
+ * `roles` has TWO sources and the effective list is their union, because the two
+ * answer different questions and neither subsumes the other.
+ *
+ * The `roles` CLAIM on the resolved identity ({@link readIdentityRoles}) is what
+ * the identity provider asserted about the caller. `ctx.auth.roles`, set by an
+ * upstream middleware, is what a request-time mapping derived —
+ * `@lunora/cloudflare-access`'s `accessRoles()` is the shipped example: the
+ * Access envelope carries `groups`, never `roles`, and that middleware's entire
+ * job is to map verified groups onto role labels here.
+ *
+ * Reading only the claim silently drops the second, which does not fail loudly —
+ * a role-gated ALLOW branch stops firing and users lose access, and a role-gated
+ * DENY branch stops firing and rows LEAK. `accessRoles` declares its own context
+ * type, so there is no compile-time signal either way.
+ *
+ * What is deliberately absent is the same field on the TEST harness: see
+ * `TestIdentity` in `./testing`. A middleware setting `ctx.auth.roles` is a real
+ * request-path producer; a test setting it directly is a world with no producer
+ * at all, which is how role-gated policies passed their tests while evaluating
+ * against an empty list in production.
+ */
+type AuthLike = {
   getIdentity?: () => Promise<Record<string, unknown> | null>;
+  /** Role labels contributed by an upstream middleware, unioned with the identity's `roles` claim. */
   roles?: ReadonlyArray<string>;
   userId?: null | string;
 };
-interface MaskContextIn {
-  auth?: AuthLike$1;
-  db: MaskDatabase;
-}
-/**
-* Procedure-builder middleware. Apply per-request via `.use(mask(policies))`.
-* Closes over the policy map at builder-construction time; resolves identity +
-* the `bypass` decision per call against the live ctx.
-*
-* IMPORTANT: a mask is in scope only for procedures whose builder chain
-* includes this middleware — opt-in, never global (the same invariant as RLS).
-*/
-declare const mask: <Context extends MaskContextIn = MaskContextIn>(policies: MaskPolicies<Context>, options?: MaskOptions<Context>) => Middleware<Context, Context>;
-/**
-* Online data-migration authoring API.
-*
-* `defineMigration` declares a per-document backfill over one table: `up`
-* transforms every existing row, `down` (optional) reverses it. Unlike the D1
-* SQL schema migrations in `@lunora/d1`, these run *inside each shard's*
-* Durable Object against live documents, in keyset batches, and are resumable —
-* the per-shard runner in `@lunora/do` tracks progress in a reserved
-* `__lunora_migrations` table so an interrupted run picks up where it stopped.
-*
-* The returned object carries a `__lunoraMigration` brand so codegen can
-* discover declarations through the type checker (mirroring the procedure
-* builder's `__lunoraProcedure` brand) and emit them into a `LUNORA_MIGRATIONS`
-* registry the DO and CLI look migrations up by id.
-*/
-/** A document handed to a migration transform: the stored row including `_id`/`_creationTime`. */
-type MigrationDocument = Record<string, unknown>;
-/**
-* Transform applied to one document. Return a new document to rewrite the row,
-* or `undefined` to leave it untouched (skipped, not counted as changed). The
-* runner always preserves the original `_id` and `_creationTime`, so the
-* returned document neither needs to nor should change row identity.
-*/
-type MigrationTransform = (document: MigrationDocument) => MigrationDocument | undefined | void;
-interface MigrationDefinition {
-  /** Rows fetched and rewritten per batch. Defaults to the runner's batch size when omitted. */
-  readonly batchSize?: number;
-  /** Optional reverse transform, applied by `migrate down`. */
-  readonly down?: MigrationTransform;
-  /** Stable, unique identifier — the key per-shard run-state is tracked under. */
-  readonly id: string;
-  /** Table whose documents this migration iterates. */
-  readonly table: string;
-  /** Forward transform, applied to every row by `migrate up`. */
-  readonly up: MigrationTransform;
-}
-/** A {@link MigrationDefinition} plus the codegen discovery marker. */
-interface RegisteredMigration extends MigrationDefinition {
-  readonly __lunoraMigration: true;
+/** Minimal shape the middleware needs on the incoming ctx. */
+interface RlsContextIn {
+  auth?: AuthLike;
+  db: RlsDatabase;
 }
-/** Declare an online data migration. See the module docs for runtime semantics. */
-declare const defineMigration: (definition: MigrationDefinition) => RegisteredMigration;
+declare const rls: <Context extends RlsContextIn = RlsContextIn>(policies: ReadonlyArray<Policy<Context>>, options?: RlsOptions) => Middleware<Context, Context>;
 /**
-* The prefixed tables a single plugin `P` contributes, or an empty map when it
-* ships no schema extension. Mirrors {@link PrefixedTables} at the plugin level
-* so {@link InstalledTables} can fold a tuple of plugins.
-*/
-type ExtensionTablesOf<P> = P extends {
-  readonly extension: SchemaExtension<infer X> & {
-    readonly key: infer K;
+ * Context handed to a {@link MaskFn} (and to {@link MaskOptions.bypass}). The
+ * `auth` shape mirrors RLS's `PolicyContext.auth` one-for-one — same identity
+ * resolver, same `can(...)` permission check — so an author can branch a mask
+ * on the caller's role/permission. `row` is the full pre-mask row the column
+ * belongs to; `column` is the column currently being masked. Both are absent
+ * when the context is used for the procedure-wide `bypass` check (no specific
+ * cell is in play yet).
+ */
+interface MaskContext<Context = unknown> {
+  readonly auth: {
+    /** `true` when any of the request's `roles` grants `permission` (see {@link MaskOptions.roles}). Fails closed for unregistered roles. */
+    readonly can: (permission: Permission | string) => boolean;
+    readonly identity?: Record<string, unknown> | null;
+    /** Role labels from the identity's `roles` claim (see `PolicyContext.auth.roles`). */
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
   };
-} ? K extends string ? PrefixedTables<X, K> : Record<never, never> : Record<never, never>;
-/**
-* Fold a tuple of plugins onto a base table map `T`, accumulating each plugin's
-* auto-prefixed extension tables left-to-right — the type-level mirror of
-* {@link installPlugins} applying `mergeSchemaExtension` for each plugin in turn.
-*/
-type InstalledTables<T extends Record<string, TableDefinition>, Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? InstalledTables<ExtensionTablesOf<Head> & T, Rest> : T;
-/**
-* Union every plugin's `ContextOut` in a tuple — the type-level mirror of the
-* `ctx.api.&lt;key>` additions {@link composePluginMiddleware} accumulates as each
-* plugin middleware runs. Independent of the incoming context, which the builder
-* infers at the `.use(...)` site.
-*/
-type ComposedOut<Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? ComposedOut<Rest> & (Head extends Plugin<any, any, infer Out> ? Out : unknown) : unknown;
-/**
-* Schema fragment a plugin contributes. Same shape as the `tables` map
-* passed to `defineSchema`. Optional `vectorIndexes` mirror the top-level
-* `defineSchema` argument so a plugin can ship vector decls alongside its
-* tables.
-*/
-interface SchemaExtension<T extends Record<string, TableDefinition> = Record<string, TableDefinition>> {
-  /** Stable key identifying the plugin that owns this extension. */
-  readonly key: string;
-  /**
-  * Extension tables, keyed by **bare** name (e.g. `buckets`). At merge time
-  * each is auto-prefixed with `key` (`ratelimit_buckets`) so it can't
-  * collide with an app table; do **not** namespace manually.
-  */
-  readonly tables: T;
-  /**
-  * Optional standalone vector indexes the plugin ships, keyed by index
-  * name. Merged into the host schema's `vectorIndexes`; a key collision
-  * with the base schema is a hard error (same policy as tables).
-  */
-  readonly vectorIndexes?: Record<string, VectorIndexDefinition>;
-}
-/**
-* Build a {@link SchemaExtension}. The `key` is a runtime tag (used for
-* error messages on collision) and a type-level brand.
-*/
-declare const defineSchemaExtension: <T extends Record<string, TableDefinition>>(key: string, options: {
-  tables: T;
-  vectorIndexes?: Record<string, VectorIndexDefinition>;
-}) => SchemaExtension<T>;
-/**
-* A plugin packages an optional schema extension and optional middleware.
-* Both are independently usable: an app can install only the schema (e.g.
-* for plugins that ship background workers but no per-request behavior)
-* or only the middleware (plugins that augment ctx without persistent
-* state).
-*/
-interface Plugin<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn> {
-  /**
-  * Optional schema extension. Apps install via
-  * `defineSchema(...).extend(plugin.extension)`.
-  */
-  readonly extension?: SchemaExtension<TExtension>;
-  /** Stable key identifying the plugin. Matches `extension.key` when set. */
-  readonly key: string;
-  /**
-  * Optional middleware. Users attach with `c.query.use(plugin.middleware)`.
-  * The middleware can extend `ctx`; convention is to attach helpers under
-  * `ctx.api.&lt;key>`, e.g.
-  *
-  * ```ts
-  * middleware: ({ ctx, next }) =>
-  *     next({ ctx: { api: { ...ctx.api, ratelimit: api } } })
-  * ```
-  */
-  readonly middleware?: Middleware<TContextIn, TContextOut>;
-}
-/** Options to {@link definePlugin}. */
-interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut> {
-  extension?: SchemaExtension<TExtension>;
-  middleware?: Middleware<TContextIn, TContextOut>;
-}
-/**
-* Package a schema extension + middleware as a reusable plugin. Either
-* field is optional — `definePlugin("foo", {})` is valid but degenerate.
-*/
-declare const definePlugin: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>) => Plugin<TExtension, TContextIn, TContextOut>;
-/**
-* Bundle of registered functions a {@link Component} ships. Keys are the
-* function's local name (e.g. `check`, `reset`); the registered function
-* value carries its own kind / args / handler.
-*
-* Users re-export from their own lunora module so codegen picks them up:
-*
-* ```ts
-* // lunora/ratelimit.ts
-* import { ratelimit } from "@vendor/ratelimit-component";
-* export const { check, reset } = ratelimit.functions;
-* // Emits as `ratelimit:check` / `ratelimit:reset` in the generated `api`.
-* ```
-*
-* Codegen follows the re-export back to the bundled `query/mutation/action`
-* call (property access or destructuring both work), so the functions land in
-* the generated `api` under the re-exporting file's namespace.
-*/
-type ComponentFunctions = Readonly<Record<string, RegisteredFunction<any, any, FunctionKind>>>;
-/**
-* Component = {@link Plugin} with a bundle of registered functions. The
-* extension + middleware + functions are independent: a component can ship
-* functions without a schema (e.g. a stateless utility), or a schema
-* without functions (e.g. shared table definitions), and any combination.
-*/
-interface Component<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn, F extends ComponentFunctions = ComponentFunctions> extends Plugin<TExtension, TContextIn, TContextOut> {
-  readonly functions: F;
-}
-interface DefineComponentOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut, F extends ComponentFunctions> extends DefinePluginOptions<TExtension, TContextIn, TContextOut> {
-  /** Registered functions the component ships. Keys are the function's local name. */
-  functions?: F;
+  /** The column currently being masked. Present only inside a per-cell {@link MaskFn}. */
+  readonly column?: string;
+  readonly ctx: Context;
+  /** The full pre-mask row the masked cell belongs to. Present only inside a per-cell {@link MaskFn}. */
+  readonly row?: Record<string, unknown>;
 }
 /**
-* Convenience wrapper around {@link definePlugin} that also bundles a set
-* of registered functions. The resulting `component.functions` object is a
-* record of `name → registered query/mutation/action`; consumers
-* re-export entries so codegen discovers them as user functions:
-*
-* ```ts
-* export const ratelimit = defineComponent("ratelimit", {
-*     // Bare `buckets` merges in as `ratelimit_buckets`.
-*     extension: defineSchemaExtension("ratelimit", { tables: { buckets } }),
-*     middleware: ({ ctx, next }) => next({ ctx: { ...ctx, ratelimit: api(ctx) } }),
-*     functions: {
-*         check: query.input({ key: v.string() }).query(async ({ ctx, args }) => ...),
-*         reset: mutation.input({ key: v.string() }).mutation(async ({ ctx, args }) => ...),
-*     },
-* });
-* ```
-*
-* Re-exporting an entry (by property access or destructuring) is enough for
-* codegen to discover it in the host app's namespace — the discovery resolver
-* chases the re-export back to the bundled registration call.
-*/
-declare const defineComponent: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn, F extends ComponentFunctions = ComponentFunctions>(key: string, options: DefineComponentOptions<TExtension, TContextIn, TContextOut, F>) => Component<TExtension, TContextIn, TContextOut, F>;
+ * A custom masking function. Receives the raw cell value and the
+ * {@link MaskContext}, returns the value to surface. Use it for partial masks
+ * (`maskMiddle(phone)`), role-aware reveals (`ctx.auth.can(...) ? value : null`),
+ * or format-preserving tokens. A function that **throws** fails closed — the
+ * cell is redacted to `null`, never leaked raw.
+ */
+type MaskFn<Context = unknown> = (value: unknown, context: MaskContext<Context>) => unknown;
 /**
-* Map every key `K` of an extension's table map `X` to its auto-prefixed name
-* `${Key}_${K}`. Mirrors the runtime prefixing in {@link mergeSchemaExtension}
-* so the typed `.extend(...)` chain reflects the real merged table names.
-*/
-type PrefixedTables<X extends Record<string, TableDefinition>, Key extends string> = { [K in keyof X as K extends string ? `${Key}_${K}` : K]: X[K] };
-/**
-* Merge a {@link SchemaExtension} into an existing schema. Returns a new
-* schema object — never mutates the input.
-*
-* Extension tables are auto-namespaced: each bare table name is prefixed with
-* the extension `key` (`buckets` → `ratelimit_buckets`), Convex-Components
-* style, and every intra-extension reference (relation targets, aggregate /
-* rank index `on`, standalone vector index `table`) is rewritten to match.
-* References to base/app tables are left untouched.
-*
-* Because each extension lives in its own `key` namespace, app↔component
-* collisions are impossible. The only remaining hard error is two extensions
-* sharing the same `key` and producing the same prefixed table (or vector
-* index) name — silent shadow would let one plugin hijack another's data.
-*/
-declare const mergeSchemaExtension: <T extends Record<string, TableDefinition>, X extends Record<string, TableDefinition>, Key extends string = string>(base: Schema<T>, extension: SchemaExtension<X> & {
-  readonly key: Key;
-}) => Schema<PrefixedTables<X, Key> & T>;
+ * How a column is masked:
+ *
+ * - `"redact"` — drop the value to `null`. The simplest, safest strategy, and
+ * the right choice for any value that must actually be kept secret.
+ * - `"hash"` — replace with a stable token (unsalted 32-bit FNV-1a hex) so the
+ * same input always yields the same token (joinable/groupable client-side).
+ * **This is NOT a confidentiality control.** It is a non-cryptographic,
+ * unsalted, deterministic, narrow (~2^32) digest: low-entropy values (emails,
+ * phone numbers, SSNs) are brute-force-recoverable by the very caller you are
+ * masking from, and identical values always produce identical tokens across
+ * rows/columns/tenants (enabling correlation). Use `"hash"` ONLY when you want a
+ * stable pseudonym for grouping/joining and leaking the value is acceptable —
+ * never to hide sensitive PII. For PII that must stay hidden, use `"redact"`.
+ * - a {@link MaskFn} — author-defined transform (partial mask, role-aware reveal).
+ */
+type MaskStrategy<Context = unknown> = "hash" | "redact" | MaskFn<Context>;
+/** Per-column strategy map for one table: `{ email: "redact", phone: maskMiddle }`. */
+type MaskColumns<Context = unknown> = Record<string, MaskStrategy<Context>>;
 /**
-* Install several plugins' schema extensions in one call — the one-shot
-* counterpart to chaining `defineSchema(...).extend(a).extend(b)`. Plugins
-* without an `extension` (middleware-only) are skipped; tables from those that
-* do are auto-prefixed and reference-rewritten exactly as
-* {@link mergeSchemaExtension} does for a single `.extend(...)`.
-*
-* ```ts
-* const schema = installPlugins(defineSchema({ todos }), [ratelimit, audit]);
-* // → todos + ratelimit_* + audit_*
-* ```
-*
-* Pair it with {@link composePluginMiddleware} to attach every plugin's
-* middleware in a single `.use(...)`, so installing N plugins is two calls
-* rather than N `.extend(...)` + N `.use(...)`.
-*/
-declare const installPlugins: <T extends Record<string, TableDefinition>, const Plugins extends ReadonlyArray<Plugin<any, any, any>>>(base: Schema<T>, plugins: Plugins) => Schema<InstalledTables<T, Plugins>>;
+ * The mask declaration passed to `mask(...)`: a table → column → strategy map.
+ * Deliberately a plain object literal so the codegen feeder can statically read
+ * which columns a procedure masks (powering the `mask_uncovered_pii_column`
+ * advisor lint), exactly as the RLS feeder reads policy tables.
+ */
+type MaskPolicies<Context = unknown> = Record<string, MaskColumns<Context>>;
 /**
-* Compose every plugin's middleware into a single middleware you attach with one
-* `.use(...)`. Plugins without middleware (schema-only) are skipped; the rest run
-* in array order, each seeing the context the previous one widened, so the final
-* `next({ ctx })` the builder receives carries every plugin's `ctx.api.&lt;key>`
-* additions. Equivalent to `.use(a.middleware).use(b.middleware)…` but as one
-* value, the middleware sibling of {@link installPlugins}.
-*
-* `ContextIn` is left free so the builder infers it from the context at the
-* `.use(...)` site; the result type widens it by the union of the plugins'
-* outputs.
-*/
-declare const composePluginMiddleware: <ContextIn = unknown, const Plugins extends ReadonlyArray<Plugin<any, any, any>> = ReadonlyArray<Plugin<any, any, any>>>(plugins: Plugins) => Middleware<ContextIn, ComposedOut<Plugins> & ContextIn>;
-/** Options for `.vectorize(field, opts)` (DSL Shape A). */
-interface VectorizeOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
-  dimensions: number;
-  embed: VectorEmbedder;
-  /** Logical index name; must match a `[[vectorize]]` binding in wrangler. */
-  index: string;
-  /** Fields mirrored into Vectorize metadata for filtering. */
-  metadata?: ReadonlyArray<keyof Shape & string>;
-  metric: VectorMetric;
+ * Options for `mask(policies, options)`.
+ *
+ * - `roles` registers the role→permission grants that back `ctx.auth.can(...)`
+ * inside a {@link MaskFn} — identical to `rls(policies, { roles })`. A role
+ * not listed grants no permissions (fails closed for unknown roles).
+ * - `bypass` is a procedure-wide escape hatch: when it returns `true` the whole
+ * mask is skipped (the caller sees raw values). Use it for a privileged
+ * viewer — `bypass: ({ auth }) => auth.can("pii:view")`. Prefer this over
+ * branching every column when an entire class of caller should see clear data.
+ * - `indexFields` closes the bare-index-scan / rank / geo position oracle (see
+ * the `mask/middleware` module docblock's "Residual read-position oracles" section).
+ */
+interface MaskOptions<Context = unknown> {
+  readonly bypass?: (context: MaskContext<Context>) => boolean;
+  /**
+   * Per-table, per-KIND index→declared-fields map (regular index `fields`
+   * under `index`; rank index `sortBy` ∪ `partitionBy` under `rank`; geo
+   * index `field` under `geo`). Supplied to close the bare-index-scan /
+   * rank / geo position oracle: a `withIndex(name)` with no range callback,
+   * a `rank`/`rankPage`/`rankBefore` read, or a `withGeoIndex` read, over an
+   * index whose DECLARED fields (for that read's own kind) intersect a
+   * masked column, is rejected. Kept per kind — rather than one flat
+   * name→fields map — because the engine resolves `withIndex` /
+   * `withGeoIndex` / rank reads in three separate namespaces, so the same
+   * index name can legally denote a different index per kind; a flat map
+   * would let one kind's fields shadow another's for a colliding name.
+   * OPTIONAL and additive — omit it and behaviour is unchanged (the oracle
+   * stays open, exactly as before this option existed). Build it with
+   * `indexFieldsFromSchema` (exported from `@lunora/server`):
+   * `mask(policies, { indexFields: indexFieldsFromSchema(schema) })`.
+   */
+  readonly indexFields?: IndexFieldsByTable;
+  readonly roles?: ReadonlyArray<Role>;
 }
-/** A `one` (many-to-one) relation descriptor; phantom `Target` carries the target table name. */
-interface OneRelation<Target extends string = string> extends RelationDefinition {
-  readonly __target?: Target;
-  readonly kind: "one";
+interface QueryPage {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
 }
-/** A `many` (one-to-many) relation descriptor; phantom `Target` carries the target table name. */
-interface ManyRelation<Target extends string = string> extends RelationDefinition {
-  readonly __target?: Target;
-  readonly kind: "many";
+interface QueryArgs {
+  baseWhere?: unknown;
+  cursor?: null | string;
+  limit?: number;
+  orderBy?: ReadonlyArray<Record<string, unknown>>;
+  /** Per-target-table mask applied to `with`-hydrated children — mirrors `@lunora/shard-engine`'s `RelationMask`. */
+  relationMask?: (table: string, rows: Record<string, unknown>[]) => Record<string, unknown>[];
+  where?: unknown;
+  with?: Record<string, unknown>;
 }
-/** The `r` argument passed to `.relations((r) => …)`. */
-interface RelationBuilder {
-  /** One-to-many: the FK `field` lives on the target table, matching this table's `references` (default `_id`). */
-  many: <Target extends string>(table: Target, options: {
-    field: string;
-    references?: string;
-  }) => ManyRelation<Target>;
-  /** Many-to-one: the FK `field` lives on this table, pointing at `table`.`references` (default `_id`). */
-  one: <Target extends string>(table: Target, options: {
-    field: string;
-    onDelete?: OnDeleteAction;
-    references?: string;
-  }) => OneRelation<Target>;
+interface AggregateArgs {
+  field?: string;
+  op: string;
+  where?: unknown;
 }
-/**
-* Options for the inline `.aggregateIndex(name, opts)` builder. `op` defaults to
-* `count` so `aggregateIndex("byUser", { by: ["userId"] })` is a single-line
-* `COUNT(*) GROUP BY userId` accelerator.
-*/
-interface InlineAggregateIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
-  /** Group keys; counter rows are one per distinct tuple. Omitted = single-row aggregate over the whole table. */
-  by?: ReadonlyArray<keyof Shape & string>;
-  /** The column the reducer applies to. Required for `sum`/`min`/`max`/`avg`; ignored for `count`. */
-  field?: keyof Shape & string;
-  /** Reducer (default `count`). */
-  op?: AggregateOp;
-  /** Static predicate baked into the counter — only matching rows are aggregated. */
-  where?: Record<string, unknown>;
+interface GroupByArgs {
+  agg?: {
+    field?: string;
+    op: string;
+  };
+  by: ReadonlyArray<string>;
+  where?: unknown;
 }
-/**
-* Options for the inline `.rankIndex(name, opts)` builder. `sortBy` is required;
-* accepts either an array of `{ field, direction }` keys, or the shorthand
-* `["field"]` (asc) / `{ field: "desc" }` map entries. `partitionBy` scopes the
-* rank — omitted ⇒ one global rank over the whole table.
-*/
-interface InlineRankIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
-  /** Columns that scope each ranking; omitted ⇒ one global rank. */
-  partitionBy?: ReadonlyArray<keyof Shape & string>;
-  /** Ordered sort keys driving the rank. Required. */
-  sortBy: ReadonlyArray<{
-    direction?: "asc" | "desc";
-    field: keyof Shape & string;
-  }>;
-  /** Static predicate baked into the index; only matching rows enter. */
-  where?: Record<string, unknown>;
+/** One row of a `.collectWithScores()` result — mirrors `@lunora/shard-engine`'s `ScoredDocument`. */
+type ScoredDocument = GeoScoredDocument | SearchScoredDocument;
+/** A `.withGeoIndex()` row — mirrors `@lunora/shard-engine`'s `GeoScoredDocument`. */
+interface GeoScoredDocument {
+  distanceMeters: null | number;
+  document: Record<string, unknown>;
+  score?: never;
 }
-interface TableBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> extends TableDefinition<Shape> {
-  /** Declare an aggregate (counter/sum/…) maintained by triggers for O(1) reads. */
-  aggregateIndex: (name: string, options?: InlineAggregateIndexOptions<Shape>) => TableBuilder<Shape>;
-  /**
-  * Mark this table as written outside Lunora's discoverable insert path —
-  * by an adapter, a migration, or framework middleware (e.g. `@lunora/auth`'s
-  * better-auth tables, `@lunora/ratelimit`'s store). Advisor insert-path lints
-  * (`table_without_insert`) then skip it instead of flagging the absent
-  * `ctx.db.insert(...)`.
-  */
-  externallyManaged: () => TableBuilder<Shape>;
-  /**
-  * Mark this table as global (cross-shard). Backed by **D1** by default;
-  * pass `{ backend: "hyperdrive" }` to store it in a Postgres/MySQL database
-  * via Cloudflare Hyperdrive (PlanetScale, Neon, …) instead. Either way the
-  * table stays reactive — live queries re-run on write.
-  */
-  global: (options?: {
-    backend?: GlobalBackend;
-  }) => TableBuilder<Shape>;
-  /** Add a secondary index. */
-  index: (name: string, fields: ReadonlyArray<string>, options?: {
-    unique?: boolean;
-  }) => TableBuilder<Shape>;
-  /**
-  * Opt this table OUT of secure-by-default RLS. Under a schema marked
-  * `.rls("required")`, every table is protected (the write path denies raw,
-  * non-RLS `ctx.db` access); calling `.public()` exempts this one table so a
-  * plain `query`/`mutation` may read/write it without an RLS policy. No effect
-  * when the schema does not require RLS.
-  */
-  public: () => TableBuilder<Shape>;
-  /**
-  * Declare a rank index (sorted companion table, btree-backed) for
-  * `rank(row)` / `rankPage()` reads in O(log n). See {@link RankIndexDefinition}.
-  */
-  rankIndex: (name: string, options: InlineRankIndexOptions<Shape>) => TableBuilder<Shape>;
-  /** Declare relations to other tables, loaded via `findMany({ with })`. */
-  relations: (build: (r: RelationBuilder) => Record<string, RelationDefinition>) => TableBuilder<Shape>;
-  /** Add a search index over a field with optional filter fields. */
-  searchIndex: (name: string, options: {
-    field: string;
-    filterFields?: ReadonlyArray<string>;
-  }) => TableBuilder<Shape>;
-  /** Route storage by the named field — one DO per distinct value. */
-  shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
-  /** Declare named lifecycle triggers fired inline within the write path. */
-  triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
-  /** Declare a vector index over a single text field on this table. */
-  vectorize: (field: keyof Shape & string, options: VectorizeOptions<Shape>) => TableBuilder<Shape>;
+/** A `.withSearchIndex()` row — mirrors `@lunora/shard-engine`'s `SearchScoredDocument`. */
+interface SearchScoredDocument {
+  distanceMeters?: never;
+  document: Record<string, unknown>;
+  score: number;
 }
-/** Options for `defineVectorIndex(...)` (DSL Shape B). */
-interface VectorIndexOptions {
-  dimensions: number;
-  embed: VectorEmbedder;
-  /** Optional projection of the source row into Vectorize metadata. */
-  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
-  metric: VectorMetric;
-  /** The vector source: which table, and how to derive the embedded text. */
-  source: {
-    select: (row: Record<string, unknown>) => string;
-    table: string;
-  };
+interface TableReaderLike {
+  [Symbol.asyncIterator]: () => AsyncIterator<Record<string, unknown>>;
+  collect: () => Promise<Record<string, unknown>[]>;
+  collectWithScores: () => Promise<ScoredDocument[]>;
+  filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike;
+  first: () => Promise<Record<string, unknown> | null>;
+  order: (direction: "asc" | "desc") => TableReaderLike;
+  paginate: (options: {
+    cursor?: null | string;
+    numItems: number;
+  }) => Promise<QueryPage>;
+  take: (limit: number) => Promise<Record<string, unknown>[]>;
+  unique: () => Promise<Record<string, unknown> | null>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => TableReaderLike;
+  withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike;
 }
 /**
-* Build a table definition. Returned object is both the table definition (for
-* `defineSchema`) and a fluent builder for indexes + sharding metadata.
-*/
-declare const defineTable: <Shape extends Record<string, Validator>>(shape: Shape) => TableBuilder<Shape>;
-/**
-* Declare a standalone vector index (DSL Shape B). Pass the returned value in
-* the `vectorIndexes` map of {@link defineSchema} when the source is derived
-* from multiple fields or a computation rather than a single column.
-*/
-declare const defineVectorIndex: (options: VectorIndexOptions) => VectorIndexDefinition;
-/**
-* Options for the standalone `defineAggregateIndex(name, opts)` helper (DSL
-* Shape B). Unlike the inline `.aggregateIndex(...)` builder, this form takes
-* the owning table explicitly via `on` — handy when a single counter wants to
-* live next to the schema map rather than inside a table chain.
-*/
-interface AggregateIndexOptions {
-  by?: ReadonlyArray<string>;
-  field?: string;
-  on: string;
-  op?: AggregateOp;
-  where?: Record<string, unknown>;
+ * Structural projection of the runtime ORM writer — the same subset
+ * `../rls/middleware` mirrors, so the wrapper is interchangeable between
+ * `@lunora/do`'s and `@lunora/d1`'s `DatabaseWriterLike` without an
+ * inter-package dependency. `rankBefore` is optional (the D1 twin omits it).
+ */
+interface MaskDatabase {
+  aggregate: (tableName: string, options: AggregateArgs) => Promise<null | number>;
+  count: (tableName: string, whereOrArgs?: unknown) => Promise<number>;
+  delete: (id: string, expectedTable?: string) => Promise<void>;
+  deleteMany: (ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  deleteWhere?: (tableName: string, where: Record<string, unknown>, options?: {
+    limit?: number;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  findFirst: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown> | null>;
+  findFirstOrThrow: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown>>;
+  findMany: (tableName: string, args?: QueryArgs) => Promise<QueryPage>;
+  get: (id: string, expectedTable?: string) => Promise<Record<string, unknown> | null>;
+  groupBy: (tableName: string, options: GroupByArgs) => Promise<ReadonlyArray<{
+    key: Record<string, unknown>;
+    value: null | number;
+  }>>;
+  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
+  insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+    skipDuplicates?: boolean;
+  }) => Promise<(string | null)[]>;
+  lookupById?: (id: string, expectedTable?: string) => Promise<null | {
+    row: Record<string, unknown>;
+    tableName: string;
+  }>;
+  patch: (id: string, patch: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  patchMany: (patches: ReadonlyArray<{
+    id: string;
+    patch: Record<string, unknown>;
+  }>, options?: {
+    limit?: number;
+  }) => Promise<{
+    patched: number;
+  }>;
+  patchWhere?: (tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: Record<string, unknown>;
+  }, options?: {
+    limit?: number;
+  }) => Promise<{
+    patched: number;
+  }>;
+  query: (tableName: string) => TableReaderLike;
+  rank: (tableName: string, indexName: string, options: unknown) => Promise<null | {
+    position: number;
+    total: number;
+  }>;
+  rankBefore?: (tableName: string, indexName: string, options: unknown) => Promise<{
+    before: number;
+    total: number;
+  }>;
+  rankPage: (tableName: string, indexName: string, options?: unknown) => Promise<QueryPage>;
+  /** Cross-shard companion to `rankPage`, gated the same way `rankPage` is masked below. */
+  rankPageRows?: (tableName: string, indexName: string, options?: unknown) => Promise<ShardRankPageResultLike>;
+  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+}
+interface MaskContextIn {
+  auth?: AuthLike;
+  db: MaskDatabase;
 }
 /**
-* Declare a standalone aggregate index. Pass the returned value to
-* `defineSchema(tables, vectorIndexes, aggregateIndexes)` keyed by index name —
-* the schema attaches it to `tables[on].aggregateIndexes` so runtime consumers
-* (DO + D1) read every index uniformly off the table definition.
-*/
-declare const defineAggregateIndex: (name: string, options: AggregateIndexOptions) => AggregateIndexDefinition;
+ * Procedure-builder middleware. Apply per-request via `.use(mask(policies))`.
+ * Closes over the policy map at builder-construction time; resolves identity +
+ * the `bypass` decision per call against the live ctx.
+ *
+ * IMPORTANT: a mask is in scope only for procedures whose builder chain
+ * includes this middleware — opt-in, never global (the same invariant as RLS).
+ */
+declare const mask: <Context extends MaskContextIn = MaskContextIn>(policies: MaskPolicies<Context>, options?: MaskOptions<Context>) => Middleware<Context, Context>;
+/** Project-wide masked-column registry: every table any registered function masks, unioned. */
+type MaskRegistry = ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * Build the project-wide masked-column registry from the registered functions
+ * (pass `Object.values(LUNORA_FUNCTIONS)`) — the mask-column twin of
+ * `buildRlsReadRegistry`. Unions every function's `.use(mask(...))` columns
+ * per table: a column masked by ANY registered function counts as masked in
+ * the registry — there is no "which procedure would this shape have gone
+ * through" question to narrow by, so the union is the only safe answer.
+ */
+declare const buildMaskRegistry: (functions: Iterable<unknown>) => MaskRegistry;
+/** A document handed to a migration transform: the stored row including `_id`/`_creationTime`. */
+type MigrationDocument = Record<string, unknown>;
 /**
-* Options for the standalone `defineRankIndex(name, opts)` helper (DSL Shape B).
-* Mirrors the inline `.rankIndex(...)` builder but takes the owning table via
-* `table` so it can sit next to the schema map.
-*/
-interface RankIndexOptions {
-  partitionBy?: ReadonlyArray<string>;
-  sortBy: ReadonlyArray<{
-    direction?: "asc" | "desc";
-    field: string;
+ * The read surface a transform reaches through its `ctx`.
+ *
+ * Read-only by design: the runner accounts for exactly one rewrite per row read,
+ * and a transform writing directly would make that count describe something
+ * other than what happened. Scoped to the shard the runner is walking.
+ */
+interface MigrationReader {
+  count: (table: string, where?: Record<string, unknown>) => Promise<number>;
+  findFirst: (table: string, args?: Record<string, unknown>) => Promise<MigrationDocument | null>;
+  findMany: (table: string, args?: Record<string, unknown>) => Promise<{
+    isDone: boolean;
+    page: MigrationDocument[];
   }>;
-  table: string;
-  where?: Record<string, unknown>;
+  get: (id: string, expectedTable?: string) => Promise<MigrationDocument | null>;
+}
+/** The context handed to a transform alongside the row. */
+interface MigrationCtx {
+  db: MigrationReader;
+}
+/**
+ * Transform applied to one document. Return a new document to rewrite the row,
+ * or `undefined` to leave it untouched (skipped, not counted as changed). The
+ * runner always preserves the original `_id` and `_creationTime`, so the
+ * returned document neither needs to nor should change row identity.
+ *
+ * The second parameter carries a shard-scoped reader. Without it a transform
+ * could only rewrite the row it was handed — enough for a backfill whose new
+ * value is a pure function of the old row (`displayName = name ?? "Anonymous"`),
+ * but not for the shape people actually write: read the parent, copy a field
+ * down onto its children.
+ *
+ * May return a promise, since a cross-table read is asynchronous.
+ *
+ * **A shard key cannot be backfilled this way, even with a reader.** A row whose
+ * shard-key field is unset does not belong to any shard, so a shard-scoped query
+ * will not enumerate it; and writing the key would have to MOVE the row to a
+ * different Durable Object, which a per-shard runner cannot do. Re-keying is an
+ * export → transform → import, not a migration.
+ */
+type MigrationTransform = (document: MigrationDocument, ctx: MigrationCtx) => MigrationDocument | Promise<MigrationDocument | undefined | void> | undefined | void;
+interface MigrationDefinition {
+  /** Rows fetched and rewritten per batch. Defaults to the runner's batch size when omitted. */
+  readonly batchSize?: number;
+  /** Optional reverse transform, applied by `migrate down`. */
+  readonly down?: MigrationTransform;
+  /** Stable, unique identifier — the key per-shard run-state is tracked under. */
+  readonly id: string;
+  /** Table whose documents this migration iterates. */
+  readonly table: string;
+  /** Forward transform, applied to every row by `migrate up`. */
+  readonly up: MigrationTransform;
 }
+/** A {@link MigrationDefinition} plus the codegen discovery marker. */
+interface RegisteredMigration extends MigrationDefinition {
+  readonly __lunoraMigration: true;
+}
+/** Declare an online data migration. See the module docs for runtime semantics. */
+declare const defineMigration: (definition: MigrationDefinition) => RegisteredMigration;
 /**
-* Declare a standalone rank index. Pass the returned value to
-* `defineSchema(tables, vectorIndexes, aggregateIndexes, rankIndexes)` keyed
-* by index name — the schema attaches it to `tables[on].rankIndexes`.
-*/
-declare const defineRankIndex: (name: string, options: RankIndexOptions) => RankIndexDefinition;
-/**
-* Build the application schema. The first argument is the table map; the
-* optional second argument registers standalone `defineVectorIndex(...)`
-* declarations (DSL Shape B) keyed by index name. The optional third argument
-* registers standalone `defineAggregateIndex(...)` declarations (DSL Shape B);
-* the optional fourth argument registers standalone `defineRankIndex(...)`
-* declarations. Both are folded into the matching `tables[on].*Indexes` array
-* so runtime backends read every index uniformly off the table definition.
-*/
-/**
-* Schema with an in-place `.extend(plugin.extension)` method. Used so apps
-* can compose plugin schemas: `defineSchema({...}).extend(authPlugin.extension)`.
-*
-* `extend` is non-mutating — returns a fresh `ExtendableSchema` containing
-* the merged tables. Extension tables are auto-namespaced by the extension
-* `key` (`buckets` → `ratelimit_buckets`), so the merged type carries the
-* prefixed names via {@link PrefixedTables}. Chains:
-* `defineSchema(...).extend(a).extend(b)` is the typed equivalent of merging
-* `a`'s prefixed tables then `b`'s.
-*/
-type ExtendableSchema<T extends Record<string, TableDefinition>> = {
-  extend: <X extends Record<string, TableDefinition>, Key extends string>(extension: SchemaExtension<X> & {
-    readonly key: Key;
-  }) => ExtendableSchema<PrefixedTables<X, Key> & T>;
+ * A mutator declaration. `server` is authoritative; `client` is the optimistic
+ * twin (optional — omit it to let the optimistic write fall through to the
+ * server round-trip with no local preview). Both receive the same validated
+ * `args`.
+ */
+interface MutatorDefinition<Args extends ValidatorMap = ValidatorMap, ServerContext = MutationCtx, ClientTx = unknown, R = unknown> {
   /**
-  * Turn on secure-by-default RLS for the whole schema. Every table is then
-  * protected — the DO/D1 write path denies raw, non-RLS `ctx.db` access, so a
-  * procedure that forgets `.use(rls(...))` fails closed. Opt a table out with
-  * `.public()`. Non-mutating: returns a fresh `ExtendableSchema` carrying the
-  * mode, so `.rls("required")` composes with `.extend(...)` either order.
-  */
-  rls: (mode: "required") => ExtendableSchema<T>;
-} & Schema<T>;
-declare const defineSchema: <T extends Record<string, TableDefinition>>(tables: T, vectorIndexes?: Record<string, VectorIndexDefinition>, aggregateIndexes?: Record<string, AggregateIndexDefinition>, rankIndexes?: Record<string, RankIndexDefinition>) => ExtendableSchema<T>;
+   * Validator for the mutator's arguments. Validated on the DO before `server`
+   * runs and (when present) on the client before `client` runs, so both impls
+   * see the same parsed shape. Omit for a parameterless mutator.
+   */
+  readonly args?: Args;
+  /**
+   * Optimistic client implementation. Runs in a TanStack DB transaction
+   * against the local collections; its writes are applied immediately and
+   * automatically rolled back / rebased as the authoritative result syncs
+   * back. Pure and side-effect-free beyond the local store. Omit to skip the
+   * local preview.
+   */
+  readonly client?: (tx: ClientTx, args: InferValidatorMap<Args>) => Promise<void> | void;
+  /**
+   * Owner-scope the write: names the column carrying the row owner (e.g.
+   * `owner: "userId"`). Before `server` runs, the mutator requires a verified
+   * identity, rejects a client-supplied owner that disagrees with it, and sets
+   * the column to the verified value — so the impl reads `args[owner]` without
+   * trusting the client and never repeats the check by hand.
+   *
+   * This replaces the "every mutator opens with `assertOwner(ctx, args.userId)`"
+   * pattern, and is the write-side counterpart to an `owner`-scoped
+   * {@link import("./shapes").ShapeDefinition}. Unlike a shape it takes the column
+   * NAME rather than `true`: a shape is bound to one `table`, so the table's
+   * `.ownedBy(field)` resolves unambiguously, whereas one mutator may write
+   * several tables and has no single owning table to read it from.
+   *
+   * Declare the column `v.optional(...)` to leave it off the wire entirely; it is
+   * injected either way.
+   */
+  readonly owner?: string;
+  /**
+   * Authoritative server implementation. Runs inside the shard DO with a full
+   * {@link MutationContext} (`ctx.db` writer); its writes append to `__cdc_log`
+   * and poke back to subscribers. This is the source of truth — the client
+   * impl is only a prediction of it.
+   */
+  readonly server: (context: ServerContext, args: InferValidatorMap<Args>) => Promise<R> | R;
+}
+/**
+ * A {@link MutatorDefinition} plus the codegen discovery marker and a
+ * dispatch-shaped `handler` (validates `args`, then runs `server`) so the DO
+ * invokes a mutator exactly like a registered procedure.
+ */
+interface RegisteredMutator<Args extends ValidatorMap = ValidatorMap, ServerContext = MutationCtx, ClientTx = unknown, R = unknown> extends MutatorDefinition<Args, ServerContext, ClientTx, R> {
+  readonly __lunoraMutator: true;
+  /** Validate `rawArgs`, then run the authoritative `server` impl. Used by the DO push path. */
+  readonly handler: (context: ServerContext, rawArgs: Record<string, unknown>) => Promise<R>;
+  /**
+   * Marks the dispatch kind so codegen can register the mutator in the same
+   * `LUNORA_FUNCTIONS` table queries/mutations use — the DO's `handleRpc`
+   * reads `kind === "mutation"` to wrap the authoritative `server` impl in the
+   * shard's BEGIN/COMMIT span (all-or-nothing writes), exactly like an
+   * ordinary `mutation`.
+   */
+  readonly kind: "mutation";
+}
+/** Declare a custom mutator. See the module docs for runtime semantics. */
+declare const defineMutator: <Args extends ValidatorMap = ValidatorMap, ServerContext = MutationCtx, ClientTx = unknown, R = unknown>(definition: MutatorDefinition<Args, ServerContext, ClientTx, R>) => RegisteredMutator<Args, ServerContext, ClientTx, R>;
 /** Default time-to-live for a presence row: a heartbeat keeps a member "present" for this long. */
 declare const DEFAULT_TTL_MS = 3e4;
 declare const PRESENCE_BARE_TABLE = "present";
 /**
-* The prefixed table name the extension produces at merge time. The handlers
-* read/write this name directly so they always agree with the merged schema.
-*/
+ * The prefixed table name the extension produces at merge time. The handlers
+ * read/write this name directly so they always agree with the merged schema.
+ */
 declare const PRESENCE_TABLE: "presence_present";
 /**
-* A single present member as returned by `listPresent`.
-*
-* Note: the raw client-chosen `sessionId` is deliberately NOT surfaced. It is a
-* connection secret — disclosing every member's `sessionId` would let any
-* subscriber enumerate them and target the heartbeat / disconnect write paths.
-* A "who's here" UI needs only `userId` + awareness `data`; the caller already
-* knows its own session id locally (the `usePresence` hook returns it).
-*/
+ * A single present member as returned by `listPresent`.
+ *
+ * Note: the raw client-chosen `sessionId` is deliberately NOT surfaced. It is a
+ * connection secret — disclosing every member's `sessionId` would let any
+ * subscriber enumerate them and target the heartbeat / disconnect write paths.
+ * A "who's here" UI needs only `userId` + awareness `data`; the caller already
+ * knows its own session id locally (the `usePresence` hook returns it).
+ */
 interface PresenceMember {
   /** Opaque awareness blob (selection, cursor, name, color…). */
   data?: Record<string, unknown>;
@@ -1301,41 +2830,55 @@ interface PresenceMember {
 /** Options for {@link definePresence}. */
 interface DefinePresenceOptions {
   /**
-  * Grace window (ms) before a gracefully-closed session is dropped from the
-  * present list. When `0` (the default), `onDisconnect` hard-deletes the
-  * session's row the instant its socket closes. When `> 0`, the row is
-  * instead aged so the read-time TTL filter hides it `disconnectGraceMs`
-  * from now — a reconnect with the same `sessionId` within the window
-  * re-heartbeats and restores full presence with no visible flicker (the
-  * AnyCable `presence_ttl` behaviour). Clamped to `ttlMs`.
-  */
+   * Grace window (ms) before a gracefully-closed session is dropped from the
+   * present list. When `0` (the default), `onDisconnect` hard-deletes the
+   * session's row the instant its socket closes. When `> 0`, the row is
+   * instead aged so the read-time TTL filter hides it `disconnectGraceMs`
+   * from now — a reconnect with the same `sessionId` within the window
+   * re-heartbeats and restores full presence with no visible flicker (the
+   * AnyCable `presence_ttl` behaviour). Clamped to `ttlMs`.
+   */
   disconnectGraceMs?: number;
   /**
-  * How long (ms) a heartbeat keeps a member present. `listPresent` excludes
-  * rows whose `lastSeen` is older than `now - ttlMs`. Defaults to 30s.
-  */
+   * Upper bound on SESSION ROWS `listPresent` reads per call — one row per
+   * `(roomId, sessionId)`, so one per open tab, NOT one per person. The read
+   * is newest-first over the `(roomId, lastSeen)` index, so the rows kept are
+   * always the freshest heartbeats and a room with more sessions than this
+   * has its stalest ones truncated.
+   *
+   * Because the multi-tab dedup collapses rows only AFTER the read, a cap
+   * below the room's live session count drops real, currently-heartbeating
+   * members off the bottom of the list. Size it against expected tabs (a
+   * 300-person room at two tabs each is 600 rows), not expected people.
+   * Defaults to 1024. A non-finite value falls back to the default.
+   */
+  maxSessions?: number;
+  /**
+   * How long (ms) a heartbeat keeps a member present. `listPresent` excludes
+   * rows whose `lastSeen` is older than `now - ttlMs`. Defaults to 30s.
+   */
   ttlMs?: number;
 }
 /** The registered functions a presence component ships. */
 interface PresenceFunctions {
   /**
-  * Connection-lifecycle hook: the instant a client's WebSocket drops, hard-
-  * delete its presence row so it disappears from `listPresent` with no TTL
-  * lag. Targets the row by the `{ roomId, sessionId }` the client passed as
-  * the connection `context`, and only deletes it when the disconnecting
-  * VERIFIED identity owns the row (so a forged context can't evict another
-  * member). The TTL filter + `sweep` remain the fallback for ungraceful drops
-  * where no `context` was recorded.
-  */
+   * Connection-lifecycle hook: the instant a client's WebSocket drops, hard-
+   * delete its presence row so it disappears from `listPresent` with no TTL
+   * lag. Targets the row by the `{ roomId, sessionId }` the client passed as
+   * the connection `context`, and only deletes it when the disconnecting
+   * VERIFIED identity owns the row (so a forged context can't evict another
+   * member). The TTL filter + `sweep` remain the fallback for ungraceful drops
+   * where no `context` was recorded.
+   */
   disconnect: RegisteredLifecycleHook;
   /**
-  * Upsert the caller's presence row for `roomId` and stamp `lastSeen = now`.
-  * Keyed by `(roomId, sessionId)` — re-heartbeats patch the existing row so
-  * subscribers receive a single-row delta, not a churn of insert/delete. A
-  * heartbeat may only patch a row owned by the same identity (an existing row
-  * held by a different `userId` is refused with `FORBIDDEN`), so a client
-  * can't overwrite another member's awareness data via a guessed `sessionId`.
-  */
+   * Upsert the caller's presence row for `roomId` and stamp `lastSeen = now`.
+   * Keyed by `(roomId, sessionId)` — re-heartbeats patch the existing row so
+   * subscribers receive a single-row delta, not a churn of insert/delete. A
+   * heartbeat may only patch a row owned by the same identity (an existing row
+   * held by a different `userId` is refused with `FORBIDDEN`), so a client
+   * can't overwrite another member's awareness data via a guessed `sessionId`.
+   */
   heartbeat: RegisteredMutation<{
     data: ReturnType<typeof v.optional>;
     roomId: ReturnType<typeof v.string>;
@@ -1344,17 +2887,19 @@ interface PresenceFunctions {
     lastSeen: number;
   }>;
   /**
-  * Live query returning the non-expired members of `roomId`, newest heartbeat
-  * first. Subscribe to it for a reactive "who's here" list.
-  */
+   * Live query returning the non-expired members of `roomId`, newest heartbeat
+   * first. Subscribe to it for a reactive "who's here" list.
+   */
   listPresent: RegisteredQuery<{
     roomId: ReturnType<typeof v.string>;
   }, PresenceMember[]>;
   /**
-  * Internal mutation that hard-deletes every expired row for `roomId`. Stale
-  * rows already vanish from `listPresent` via the read-time TTL filter; this
-  * only reclaims storage. Schedule it (cron / `runAfter`) if you care.
-  */
+   * Internal mutation that hard-deletes every expired row for `roomId`. Stale
+   * rows already vanish from `listPresent` via the read-time TTL filter, and
+   * active rooms self-clean via the heartbeat's opportunistic reap; this is
+   * optional hardening for bulk cleanup of rooms that went quiet with stale
+   * rows left behind (schedule it on a cron / `runAfter` if you care).
+   */
   sweep: RegisteredMutation<{
     roomId: ReturnType<typeof v.string>;
   }, {
@@ -1368,313 +2913,320 @@ type PresenceComponent = Component<{
   functions: PresenceFunctions;
 };
 /**
-* The presence schema extension: a single `present` table, auto-namespaced to
-* `presence_present` at merge time, indexed by `(roomId, sessionId)` for the
-* heartbeat upsert and by `roomId` for `listPresent`.
-*/
+ * The presence schema extension: a single `present` table, auto-namespaced to
+ * `presence_present` at merge time, indexed by `(roomId, sessionId)` for the
+ * heartbeat upsert and by `roomId` for `listPresent`.
+ */
 declare const presenceExtension: SchemaExtension<{
   [PRESENCE_BARE_TABLE]: ReturnType<typeof defineTable>;
 }>;
 declare const definePresence: (options?: DefinePresenceOptions) => PresenceComponent;
 /**
-* The middlewares `protectPublic` chains, in the order they run. Every field is
-* optional, so a bundle can be just a rate limit, just a captcha, or any mix —
-* pass the already-constructed middlewares (e.g. `rateLimit(limiter, "signup")`
-* from `@lunora/ratelimit`, `verifyTurnstileMiddleware({...})` from
-* `@lunora/auth`). They are accepted as values rather than imported here so
-* `@lunora/server` keeps no dependency on those packages (which depend on it).
-*/
+ * The middlewares `protectPublic` chains, in the order they run. Every field is
+ * optional, so a bundle can be just a rate limit, just a captcha, or any mix —
+ * pass the already-constructed middlewares (e.g. `rateLimit(limiter, "signup")`
+ * from `@lunora/ratelimit`, `verifyTurnstileMiddleware({...})` from
+ * `@lunora/auth`). They are accepted as values rather than imported here so
+ * `@lunora/server` keeps no dependency on those packages (which depend on it).
+ */
 interface ProtectPublicOptions<Context> {
   /**
-  * A CAPTCHA / bot check, run after the rate limit. Placed second on purpose:
-  * an obvious flood is cheaper to reject with the in-memory limiter than with
-  * a Turnstile siteverify round-trip.
-  */
+   * A CAPTCHA / bot check, run after the rate limit. Placed second on purpose:
+   * an obvious flood is cheaper to reject with the in-memory limiter than with
+   * a Turnstile siteverify round-trip.
+   */
   captcha?: Middleware<Context, Context>;
   /**
-  * A rate limit, run first. Cheapest gate, so it sheds obvious abuse before
-  * any network-bound check below it runs.
-  */
+   * A rate limit, run first. Cheapest gate, so it sheds obvious abuse before
+   * any network-bound check below it runs.
+   */
   rateLimit?: Middleware<Context, Context>;
   /** Extra middlewares appended after `rateLimit` and `captcha`, in order. */
   use?: ReadonlyArray<Middleware<Context, Context>>;
 }
 /**
-* Compose the recommended public-procedure protections into a single
-* `.use()`-able middleware. It is thin sugar over middleware composition — no
-* new enforcement engine — chaining (in order) a rate limit, a CAPTCHA check,
-* and any extra middlewares so a public mutation that creates users, sends
-* mail, or consumes credits is guarded in one attachment:
-*
-* ```ts
-* export const signUp = mutation
-*   .use(protectPublic({
-*     rateLimit: rateLimit(limiter, "signup"),
-*     captcha: verifyTurnstileMiddleware({ secret: env.TURNSTILE_SECRET_KEY, token: (c) => c.args.captchaToken }),
-*   }))
-*   .handler(async (ctx, args) => { ... });
-* ```
-*
-* The bundle is context-preserving — each inner middleware leaves the context
-* unchanged — so it slots into any `.use()` chain without reshaping the
-* procedure context. Omitted fields are skipped; an empty bundle is a
-* transparent pass-through.
-*/
+ * Compose the recommended public-procedure protections into a single
+ * `.use()`-able middleware. It is thin sugar over middleware composition — no
+ * new enforcement engine — chaining (in order) a rate limit, a CAPTCHA check,
+ * and any extra middlewares so a public mutation that creates users, sends
+ * mail, or consumes credits is guarded in one attachment:
+ *
+ * ```ts
+ * export const signUp = mutation
+ *   .use(protectPublic({
+ *     rateLimit: rateLimit(limiter, "signup"),
+ *     captcha: verifyTurnstileMiddleware({ secret: env.TURNSTILE_SECRET_KEY, token: (c) => c.args.captchaToken }),
+ *   }))
+ *   .handler(async (ctx, args) => { ... });
+ * ```
+ *
+ * The bundle is context-preserving — each inner middleware leaves the context
+ * unchanged — so it slots into any `.use()` chain without reshaping the
+ * procedure context. Omitted fields are skipped; an empty bundle is a
+ * transparent pass-through.
+ */
 declare const protectPublic: <Context>(options: ProtectPublicOptions<Context>) => Middleware<Context, Context>;
+/**
+ * The read a reactor watches. Runs on every flush that touched a table it read
+ * last time, so keep it indexed and bounded — this is the reactor's steady-state
+ * cost, paid whether or not the handler ends up running.
+ */
+type ReactorSelect<T> = (context: QueryCtx) => Promise<T> | T;
+/** What runs when {@link ReactorSelect}'s result changes. Receives the current result. */
+type ReactorHandler<T> = (context: MutationCtx, result: T) => Promise<void> | void;
+/**
+ * A registered reactor — an internal mutation tagged `lifecycle: "reactor"`.
+ *
+ * Typed separately from `RegisteredLifecycleHook` (which returns `void`) because
+ * a reactor dispatch reports a {@link ReactorOutcome} back to the shard: the
+ * digest becomes the next baseline, and the shard cannot compute it itself
+ * without re-running the read.
+ */
+type RegisteredReactor = RegisteredFunction<Record<string, never>, ReactorOutcome, "mutation"> & {
+  readonly lifecycle: "reactor";
+};
+/** What a reactor dispatch reports back so the shard can update the baseline. */
+interface ReactorOutcome {
+  /** Digest of the result the handler was given (or would have been). */
+  digest: string;
+  /** Whether the handler actually ran — `false` when the result was unchanged. */
+  ran: boolean;
+}
+/**
+ * Register a reactor: run `handler` after a write flush, whenever `select`'s
+ * result differs from the last result the handler saw. See the module docblock
+ * for the trigger comparison and the convergence contract.
+ *
+ * The read is an inline callback rather than a reference to a registered query
+ * on purpose. It keeps the declaration statically discoverable with no import
+ * resolution and no dependency on `_generated/api`, and it lets the read and the
+ * handler share one transaction and one read footprint.
+ *
+ * That shared footprint is deliberately conservative: it is the union of what
+ * `select` AND `handler` read, so a table the handler merely consults can wake
+ * the reactor later. The cost of that is one extra `select` — whose digest then
+ * matches and suppresses the handler — never a missed reaction.
+ */
+declare const onQueryChange: <T>(select: ReactorSelect<T>, handler: ReactorHandler<T>) => RegisteredReactor;
 declare const definePolicy: <Context = unknown>(input: DefinePolicyInput<Context>) => Policy<Context>;
 /**
-* Build a project-bound, relation-aware `definePolicy` typed against the
-* generated `DataModel` (`DM`) + `Relations` (`REL`) maps. Codegen emits a
-* `createPolicyDsl&lt;DataModel, Relations>()` binding into `_generated/server.ts`,
-* so importing `definePolicy` from the generated module constrains `table` to a
-* real table name and type-checks the `when` predicate — including Prisma-style
-* relation predicates (`is`/`some`/…) the `@lunora/do` pre-resolver now resolves
-* on reads. The runtime is byte-for-byte the untyped {@link definePolicy}; only
-* the compile-time surface narrows, so a policy authored either way is
-* discovered identically by the `rls()` chain.
-*/
-declare const createPolicyDsl: <DM, REL extends Record<keyof DM, object>>() => <T extends keyof DM, Context = unknown>(input: TypedDefinePolicyInput<DM, REL, T, Context>) => Policy<Context>;
-/**
-* Declare a named permission a policy can check with `ctx.auth.can(...)`. Grant
-* it to a role through `defineRole`'s `permissions`, register those roles with
-* the middleware via `rls(policies, { roles })`, then check it in a policy with
-* `when: ({ auth }) => auth.can(permission)`. See the `./index` JSDoc for a
-* worked example.
-*/
+ * Build a project-bound, relation-aware `definePolicy` typed against the
+ * generated `DataModel` (`DM`) + `Relations` (`REL`) maps. Codegen emits a
+ * `createPolicyDsl<DataModel, Relations>()` binding into `_generated/server.ts`,
+ * so importing `definePolicy` from the generated module constrains `table` to a
+ * real table name and type-checks the `when` predicate — including Prisma-style
+ * relation predicates (`is`/`some`/…) the `@lunora/do` pre-resolver now resolves
+ * on reads. The runtime is byte-for-byte the untyped {@link definePolicy}; only
+ * the compile-time surface narrows, so a policy authored either way is
+ * discovered identically by the `rls()` chain.
+ */
+declare const createPolicyDsl: <DM, REL extends Record<keyof DM, object>, Identity = Record<string, unknown>>() => <T extends keyof DM, Context = unknown>(input: TypedDefinePolicyInput<DM, REL, T, Context, Identity>) => Policy<Context>;
+/**
+ * Declare a named permission a policy can check with `ctx.auth.can(...)`. Grant
+ * it to a role through `defineRole`'s `permissions`, register those roles with
+ * the middleware via `rls(policies, { roles })`, then check it in a policy with
+ * `when: ({ auth }) => auth.can(permission)`. See the `./index` JSDoc for a
+ * worked example.
+ */
 declare const definePermission: (name: string, options?: Omit<Permission, "name">) => Permission;
 /**
-* Collect a list of policies into the structure the `rls()` middleware
-* consumes. Multiple read policies on the same table OR together (any one
-* matching reveals the row); multiple write policies for the same `(table,
-* op)` AND together (every one must allow). The middleware keeps them in order
-* and decides — see `./middleware`.
-*
-* Validates against an **accidentally duplicated policy** — the same
-* `(table, on)` registered with the *same* decision function (a copy-paste, or
-* the same policy object spread in twice). Because multiple DISTINCT policies
-* per `(table, on)` are intentional, the check keys on the `when` reference too:
-* only a reference-identical `when` for the same `(table, on)` is a real
-* duplicate. Throws at module load so the misconfiguration surfaces immediately
-* rather than as a silently double-evaluated predicate at request time.
-*/
+ * Collect a list of policies into the structure the `rls()` middleware
+ * consumes. Multiple read policies on the same table OR together (any one
+ * matching reveals the row); multiple write policies for the same `(table,
+ * op)` AND together (every one must allow). The middleware keeps them in order
+ * and decides — see `./middleware`.
+ *
+ * Validates against an **accidentally duplicated policy** — the same
+ * `(table, on)` registered with the *same* decision function (a copy-paste, or
+ * the same policy object spread in twice). Because multiple DISTINCT policies
+ * per `(table, on)` are intentional, the check keys on the `when` reference too:
+ * only a reference-identical `when` for the same `(table, on)` is a real
+ * duplicate. Throws at module load so the misconfiguration surfaces immediately
+ * rather than as a silently double-evaluated predicate at request time.
+ */
 declare const definePolicies: <Context = unknown>(policies: ReadonlyArray<Policy<Context>>) => ReadonlyArray<Policy<Context>>;
 declare const defineRole: (name: string, options?: Omit<Role, "name">) => Role;
 /**
-* Structural mirror of `@lunora/do`'s `QueryArgs` and `CountArgs`. The
-* runtime ORM in `@lunora/do`/`@lunora/d1` reads `baseWhere` /
-* `restrictsCounts` straight off these option objects, so as long as the
-* fields here stay name-compatible the wrapper is portable across the two
-* dialects without an inter-package dependency.
-*/
-interface QueryArgs {
-  baseWhere?: WhereInput;
-  cursor?: null | string;
-  limit?: number;
-  orderBy?: ReadonlyArray<unknown>;
-  /**
-  * Per-target-table read filter the RLS wrapper attaches so a `with` relation
-  * is policy-filtered on its own hop (see `@lunora/do`'s `QueryArgs`). Mirrors
-  * the top-level read: `(table) => readBase(table).baseWhere`.
-  */
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-  with?: Record<string, unknown>;
-}
-interface CountArgs {
-  baseWhere?: WhereInput;
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `AggregateOptions` — only the fields the wrapper touches. */
-interface AggregateArgs {
-  baseWhere?: WhereInput;
-  field?: string;
-  op: string;
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `GroupByOptions`. */
-interface GroupByArgs {
-  agg?: {
-    field?: string;
-    op: string;
-  };
-  baseWhere?: WhereInput;
-  by: ReadonlyArray<string>;
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `RankOptions`. */
-interface RankArgs {
-  baseWhere?: WhereInput;
-  restrictsCounts?: boolean;
-  row: Record<string, unknown> | string;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `RankBeforeOptions`. */
-interface RankBeforeArgs {
-  partitionKey: string;
-  restrictsCounts?: boolean;
-  rowId: string;
-  sortValues: ReadonlyArray<unknown>;
-}
-/** Structural mirror of `@lunora/do`'s `RankPageOptions`. */
-interface RankPageArgs {
-  baseWhere?: WhereInput;
-  cursor?: null | string;
-  restrictsCounts?: boolean;
-  take?: number;
-  where?: WhereInput;
-}
-interface QueryPage {
-  continueCursor: null | string;
-  isDone: boolean;
-  page: Record<string, unknown>[];
-}
-interface TableReaderLike {
-  collect: () => Promise<Record<string, unknown>[]>;
-  filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike;
-  first: () => Promise<Record<string, unknown> | null>;
-  paginate: (options: {
-    cursor?: null | string;
-    numItems: number;
-  }) => Promise<QueryPage>;
-  take: (limit: number) => Promise<Record<string, unknown>[]>;
-  withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike;
-  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike;
-}
-/**
-* Structural projection of the runtime ORM writer. The wrapper relies only
-* on these fields, so it's interchangeable between `@lunora/do`'s
-* `DatabaseWriterLike` and `@lunora/d1`'s `DatabaseWriterLike`.
-*/
-interface DatabaseWriterLike {
+ * A predicate matching **no** rows — the deny decision.
+ *
+ * `{ OR: [] }` is a disjunction over zero branches, which the where-compiler
+ * folds to a constant false. Use it (never a bare `{}`) for the unauthorized
+ * branch of a shape or policy predicate:
+ *
+ * ```ts
+ * where: (ctx, { userId }) => (ctx.auth.userId === userId ? { userId } : deny())
+ * ```
+ *
+ * A fresh object per call, so a caller can safely spread or extend the result.
+ */
+declare const deny: () => WhereInput;
+/**
+ * A predicate matching **every** row — no restriction beyond whatever it is
+ * AND-composed with. The honest spelling of "this branch adds no filter", where a
+ * bare `{}` reads like an oversight.
+ */
+declare const allowAll: () => WhereInput;
+/**
+ * `true` when `where` is the vacuously-false deny predicate — i.e. an `OR` over
+ * zero branches, carrying no other constraint. Used by the runtime to short-circuit
+ * a denied read instead of compiling and running SQL that provably matches nothing.
+ */
+declare const isDeny: (where: WhereInput) => boolean;
+/**
+ * Normalize a boolean-or-predicate decision to a {@link WhereInput}.
+ *
+ * The authoring surfaces accept `true`/`false` as sugar — they read far better
+ * than the sentinel objects in an ownership check — and every consumer downstream
+ * wants a plain predicate. `undefined` means "no opinion" and maps to
+ * {@link allowAll}, matching the RLS `PolicyDecision` contract.
+ */
+declare const toWhereInput: (decision: WhereInput | boolean | undefined) => WhereInput;
+/**
+ * One `rls()` tag's read policies for a table, paired with the role→permission
+ * grants of that SAME middleware. Keeping the role map per-group is what lets a
+ * policy's `auth.can(...)` resolve against its own middleware's roles — never a
+ * permission registered on a different `rls()` step.
+ */
+interface ScopedReadPolicies {
+  readonly policies: ReadonlyArray<Policy>;
+  readonly rolePermissions: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/** Table-indexed read-policy groups, each scoped to the roles of the rls() middleware that declared it. */
+interface RlsReadRegistry {
+  readonly byTable: ReadonlyMap<string, ReadonlyArray<ScopedReadPolicies>>;
+}
+/** The trusted, server-resolved facts a shape's RLS evaluation runs under. */
+interface ShapeReadWhereRequest {
+  /** The shape ctx (the procedure context a policy `when` reads as `ctx`). */
+  readonly ctx: unknown;
+  /** Resolved identity claims (the socket's verified identity), or `null` when anonymous. */
+  readonly identity: Record<string, unknown> | null;
+  /** `true` when the schema is `.rls("required")` — gates the fail-closed branch. */
+  readonly rlsRequired: boolean;
+  /** The shape's own predicate (`where(ctx, args)`). */
+  readonly shapeWhere: WhereInput;
+  /** Logical table the shape replicates. */
+  readonly table: string;
+  /** `true` when the table is `.public()` (exempt from `.rls("required")` denial). */
+  readonly tablePublic: boolean;
+  /** Verified user id, or `null` when anonymous. */
+  readonly userId: null | string;
+}
+/**
+ * Build the read-policy registry from the registered functions (pass
+ * `Object.values(LUNORA_FUNCTIONS)`). Only `on: "read"` policies are collected,
+ * grouped per `rls()` middleware so each group keeps its own role→permission map
+ * (a `(table, when)` pair is de-duplicated within a tag). A tag reused across
+ * several procedures (a shared `const guard = rls(...)`) is folded once. This
+ * mirrors the request-time `rls()` path exactly: a policy's `auth.can(...)`
+ * resolves against the roles of the middleware that declared it, never a union.
+ */
+declare const buildRlsReadRegistry: (functions: Iterable<unknown>) => RlsReadRegistry;
+/**
+ * Compute the effective `where` a shape replicates: the table's RLS read
+ * base-where AND the shape's own predicate. Returns the shape predicate
+ * unchanged for a table with no read policy (a `.public()` or non-RLS table),
+ * and the FALSE sentinel (replicate nothing) when a `.rls("required")` schema
+ * exposes a protected, policy-less table.
+ */
+declare const composeShapeReadWhere: (registry: RlsReadRegistry, request: ShapeReadWhereRequest) => WhereInput;
+/**
+ * A shape declaration. `where` receives the trusted procedure context and the
+ * validated client args and returns the same {@link WhereInput} shape the RLS
+ * DSL uses, so the DO can AND-merge it with the table's read base-where via the
+ * existing where-compiler (zero second predicate implementation).
+ */
+interface ShapeDefinition<Args extends ValidatorMap = ValidatorMap, Context = QueryCtx> {
   /**
-  * Reduce matching rows to a scalar. The RLS wrapper AND-merges the read
-  * `baseWhere` into `options` so the reduction only sees policy-visible rows
-  * (safe: an aggregate scoped to `where` never reveals a hidden row — see
-  * `@lunora/do`'s `RestrictableQueryOptions`). Required: the only writer ever
-  * wrapped is `@lunora/do`'s `createShardCtxDb`, which always implements it.
-  */
-  aggregate: (tableName: string, options: AggregateArgs) => Promise<null | number>;
-  count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
-  delete: (id: string, expectedTable?: string) => Promise<void>;
-  deleteMany: (ids: ReadonlyArray<string>, options?: {
-    limit?: number;
-  }, expectedTable?: string) => Promise<{
-    deleted: number;
-  }>;
-  findFirst: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown> | null>;
-  findFirstOrThrow: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown>>;
-  findMany: (tableName: string, args?: QueryArgs) => Promise<QueryPage>;
-  get: (id: string, expectedTable?: string) => Promise<Record<string, unknown> | null>;
+   * Validator for the client-supplied shape parameters. Validated on the DO
+   * before `where` runs, so a malformed `args` envelope is rejected at the
+   * subscription boundary rather than silently widening the partition. Omit
+   * for a parameterless shape.
+   */
+  readonly args?: Args;
   /**
-  * Group + reduce. Same `baseWhere` injection as `aggregate`: the per-group
-  * reduction is scoped to policy-visible rows, so a group count tallies only
-  * rows the caller may read. Required for the same reason as `aggregate`.
-  */
-  groupBy: (tableName: string, options: GroupByArgs) => Promise<ReadonlyArray<{
-    key: Record<string, unknown>;
-    value: null | number;
-  }>>;
-  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
-  insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    limit?: number;
-  }) => Promise<string[]>;
-  insertManyUnsafe: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    allowExplicitId?: boolean;
-    limit?: number;
-  }) => Promise<string[]>;
+   * Project the replicated rows to these columns (the system columns `_id` and
+   * `_creationTime` are always included). Omit to replicate every column. An
+   * empty array is rejected — it would replicate no data, which is never the
+   * intent.
+   */
+  readonly columns?: ReadonlyArray<string>;
   /**
-  * Optional table-aware lookup. The underlying writer (e.g. `@lunora/do`)
-  * already knows the owning table of an id internally, so it can return
-  * `{ row, tableName }` in a single round-trip. When present, the RLS wrapper
-  * uses it to collapse the per-call membership-probe fan-out (1 `get` + N
-  * `findFirst` across every policy table) down to one lookup. Writers that
-  * don't implement it fall back to the probe path.
-  */
-  lookupById?: (id: string, expectedTable?: string) => Promise<null | {
-    row: Record<string, unknown>;
-    tableName: string;
-  }>;
-  patch: (id: string, patch: Record<string, unknown>, expectedTable?: string) => Promise<void>;
-  patchMany: (patches: ReadonlyArray<{
-    id: string;
-    patch: Record<string, unknown>;
-  }>, options?: {
-    limit?: number;
-  }, expectedTable?: string) => Promise<void>;
-  query: (tableName: string) => TableReaderLike;
+   * Restrict this shape to rows the **subscriber owns**, without writing the
+   * predicate by hand.
+   *
+   * `true` uses the owning column declared by `.ownedBy(field)` on the table;
+   * `"field"` names the owning column here instead (for a table that has no
+   * `.ownedBy()`, or a shape that scopes by a different column).
+   *
+   * The derived predicate is `{ [field]: ctx.auth.userId }`, AND-composed with
+   * the shape's own `where` when both are present, and an anonymous subscriber is denied
+   * outright. Because the value comes from the socket's verified identity rather
+   * than from `args`, a client cannot ask for another user's partition at all —
+   * strictly safer than accepting a `userId` arg and comparing it.
+   *
+   * This is the primitive for the "every shape repeats the same ownership check"
+   * pattern: with it, an owner-scoped shape needs no `where` at all.
+   */
+  readonly owner?: string | true;
+  /** Logical table this shape replicates a partition of. */
+  readonly table: string;
   /**
-  * Rank a row within its partition. A position is a count-of-rows-before, so
-  * — exactly like `count()` — it can't be trusted in an RLS-restricted
-  * reader: the wrapper fails it closed with `COUNT_RLS_UNSUPPORTED`. Required
-  * for the same reason as `aggregate`.
-  */
-  rank: (tableName: string, indexName: string, options: RankArgs) => Promise<null | {
-    position: number;
-    total: number;
-  }>;
-  /** Cross-shard rank primitive — same count-of-before RLS hazard as `rank`; failed closed under a read policy. */
-  rankBefore?: (tableName: string, indexName: string, options: RankBeforeArgs) => Promise<{
-    before: number;
-    total: number;
-  }>;
+   * Predicate selecting the rows this shape replicates. AND-composed with the
+   * table's RLS read base-where on the DO. Runs server-side with a trusted
+   * `ctx` (identity/auth the client can't forge) and the validated client
+   * `args`; returns a {@link WhereInput} using the same operator set as the
+   * SQL compiler (`eq`/`in`/`lt`/… + `AND`/`OR`/`NOT`).
+   *
+   * `true`/`false` are accepted as sugar for "no further restriction" / "deny" —
+   * `false` compiles to the vacuously-false predicate, so a denial branch can
+   * never be mistyped as the everything-matches `{}`. Optional when `owner` is
+   * set; otherwise required.
+   */
+  readonly where?: (context: Context, args: InferValidatorMap<Args>) => WhereInput | boolean;
+}
+/** A {@link ShapeDefinition} plus the codegen discovery marker and a dispatch-shaped `compileWhere`. */
+interface RegisteredShape<Args extends ValidatorMap = ValidatorMap, Context = QueryCtx> extends ShapeDefinition<Args, Context> {
+  readonly __lunoraShape: true;
   /**
-  * Sorted pagination over a rank companion. The companion stores only the
-  * partition + sort keys + id, so an arbitrary read `baseWhere` can't be
-  * enforced against it (and re-filtering the fetched rows would break page
-  * sizing). RLS therefore fails it closed rather than leak hidden rows.
-  * Required for the same reason as `aggregate`.
-  */
-  rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage>;
-  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
-}
-/**
-* What a procedure's `ctx.db` must structurally satisfy for the middleware
-* to wrap it. We deliberately mirror `@lunora/do`'s `DatabaseWriterLike`
-* rather than `@lunora/server`'s nominal `DatabaseWriter`/`DatabaseReader`:
-* the runtime adapter that flows in is the `DatabaseWriterLike`-shaped one,
-* and structural matching keeps this module free of an `@lunora/do`-typed
-* `ctx`.
-*/
-type RlsDatabase = DatabaseWriterLike;
-/** Roles list source on the context. Tolerant of older auth states. */
-type AuthLike = {
-  getIdentity?: () => Promise<Record<string, unknown> | null>;
-  roles?: ReadonlyArray<string>;
-  userId?: null | string;
-};
-/** Minimal shape the middleware needs on the incoming ctx. */
-interface RlsContextIn {
-  auth?: AuthLike;
-  db: RlsDatabase;
-}
-declare const rls: <Context extends RlsContextIn = RlsContextIn>(policies: ReadonlyArray<Policy<Context>>, options?: RlsOptions) => Middleware<Context, Context>;
-/**
-* Operations a storage rule can gate. `read` covers `download` / `getMetadata`
-* / `getSignedUrl` / `getUrl`; `write` covers `store` / `generateUploadUrl`;
-* `delete` is `delete`; `list` is a prefix listing (governed via the file
-* browser / admin path, not `ctx.storage` which has no `list`).
-*/
+   * Validate `rawArgs`, then evaluate the shape's predicate under the trusted
+   * `ctx` and return its {@link WhereInput}. Used by the generated DO's
+   * `resolveShape` override: `ctx` is erased to `unknown` at this dispatch
+   * boundary (the DO builds it from the socket's verified identity and hands it
+   * back as the concrete {@link QueryContext} the predicate expects), exactly like
+   * `RegisteredLunoraFunction.handler` erases its context.
+   *
+   * `options.ownerField` carries the table's `.ownedBy(field)` column, which only
+   * the caller (the DO, holding the schema) can look up — it is what resolves an
+   * `owner: true` shape. Omitted for an `owner: "field"` or plain `where` shape.
+   */
+  readonly compileWhere: (context: unknown, rawArgs: Record<string, unknown>, options?: {
+    ownerField?: string;
+  }) => WhereInput;
+}
+/** Declare a replication shape. See the module docs for runtime semantics. */
+declare const defineShape: <Args extends ValidatorMap = ValidatorMap, Context = QueryCtx>(definition: ShapeDefinition<Args, Context>) => RegisteredShape<Args, Context>;
+/**
+ * Operations a storage rule can gate. `read` covers `download` / `getMetadata`
+ * / `getSignedUrl` / `getUrl`; `write` covers `store` / `generateUploadUrl`;
+ * `delete` is `delete`; `list` is a prefix listing (governed via the file
+ * browser / admin path, not `ctx.storage` which has no `list`).
+ */
 type StorageOperation = "delete" | "list" | "read" | "write";
 /** A rule's decision. `true` allows, `false` denies, `undefined` opts this rule out. */
 type StorageRuleDecision = boolean | undefined;
 /**
-* Context handed to a storage rule. `auth` mirrors RLS's `PolicyContext.auth`
-* (the per-request userId / roles / identity and the `can(permission)` helper),
-* so a rule reads `({ auth, key }) => key.startsWith(`user/${auth.userId}/`)`.
-* `key` is the object key the operation targets (for `list`, the listing
-* prefix). `ctx` is the full procedure context the middleware closed over.
-*/
+ * Context handed to a storage rule. `auth` mirrors RLS's `PolicyContext.auth`
+ * (the per-request userId / roles / identity and the `can(permission)` helper),
+ * so a rule reads `({ auth, key }) => key.startsWith(`user/${auth.userId}/`)`.
+ * `key` is the object key the operation targets (for `list`, the listing
+ * prefix). `ctx` is the full procedure context the middleware closed over.
+ */
 interface StorageRuleContext<Context = unknown> {
   readonly auth: {
     readonly can: (permission: Permission | string) => boolean;
     readonly identity?: Record<string, unknown> | null;
+    /** Role labels from the identity's `roles` claim (see `PolicyContext.auth.roles`). */
     readonly roles: ReadonlyArray<string>;
     readonly userId: null | string;
   };
@@ -1685,14 +3237,29 @@ interface StorageRuleContext<Context = unknown> {
 /** A registered storage rule as stored in the rule table. */
 interface StorageRule<Context = unknown> {
   /**
-  * Logical bucket the rule governs — matched against the accessor's bucket
-  * (`ctx.storage.bucketName`, or the bucket selected via `ctx.storage.bucket(name)`).
-  * A rule only applies to operations on its own bucket. The unnamed bucket is
-  * `"default"`. Also surfaced in the studio's access-rules view.
-  */
+   * Logical bucket the rule governs — matched against the accessor's bucket
+   * (`ctx.storage.bucketName`, or the bucket selected via `ctx.storage.bucket(name)`).
+   * A rule only applies to operations on its own bucket. The unnamed bucket is
+   * `"default"`. Also surfaced in the studio's access-rules view.
+   *
+   * Must name a bucket the request's storage can address, or the middleware
+   * throws `INTERNAL`: an unaddressable rule governs nothing, which leaves its
+   * operation open rather than locked down. Typed `string` rather than the
+   * generated `StorageBucketName` union deliberately — that union is not the
+   * set of registered buckets (it is seeded partly from these very rules), so
+   * narrowing to it would reject valid names and still admit typos. The
+   * runtime check in `./middleware` is the one that has the real set.
+   */
   readonly bucket: string;
   readonly on: StorageOperation;
-  /** Optional key-prefix scope; the rule only governs keys under it. Absent ⇒ the whole bucket. */
+  /**
+   * Optional key-prefix scope; the rule only governs keys under it. Absent (or
+   * empty) ⇒ the whole bucket.
+   *
+   * Matched on a **path-segment boundary**: `users/1` governs `users/1` and
+   * `users/1/avatar.png`, but NOT `users/10/avatar.png`. A trailing slash is
+   * cosmetic — `users/1` and `users/1/` scope the same subtree.
+   */
   readonly prefix?: string;
   readonly when: (context: StorageRuleContext<Context>) => StorageRuleDecision;
 }
@@ -1704,38 +3271,32 @@ interface DefineStorageRuleInput<Context = unknown> {
   when: (context: StorageRuleContext<Context>) => StorageRuleDecision;
 }
 /**
-* Options for the `storageRules(rules, options)` middleware. `roles` registers
-* the role→permission grants that back `ctx.auth.can(...)`, exactly as RLS's
-* `RlsOptions.roles` does — fail-closed for unlisted roles.
-*/
+ * Options for the `storageRules(rules, options)` middleware. `roles` registers
+ * the role→permission grants that back `ctx.auth.can(...)`, exactly as RLS's
+ * `RlsOptions.roles` does — fail-closed for unlisted roles.
+ */
 interface StorageRulesOptions {
   readonly roles?: ReadonlyArray<Role>;
 }
 declare const defineStorageRule: <Context = unknown>(input: DefineStorageRuleInput<Context>) => StorageRule<Context>;
 /**
-* Collect a list of storage rules into the structure the `storageRules()`
-* middleware consumes. Multiple rules for the same `(bucket, on)` OR together —
-* any one allowing grants the operation (each rule grants a slice of the
-* keyspace).
-*
-* Validates against an **accidentally duplicated rule** — the same
-* `(bucket, on, prefix)` registered with the *same* decision function (a
-* copy-paste, or the same rule object spread in twice). Because multiple
-* DISTINCT rules per `(bucket, on)` are intentional, the check keys on the
-* `when` reference too. Throws at module load so the misconfiguration surfaces
-* immediately rather than as a silently double-evaluated predicate.
-*/
+ * Collect a list of storage rules into the structure the `storageRules()`
+ * middleware consumes. Multiple rules for the same `(bucket, on)` OR together —
+ * any one allowing grants the operation (each rule grants a slice of the
+ * keyspace).
+ *
+ * Validates against an **accidentally duplicated rule** — the same
+ * `(bucket, on, prefix)` registered with the *same* decision function (a
+ * copy-paste, or the same rule object spread in twice). Because multiple
+ * DISTINCT rules per `(bucket, on)` are intentional, the check keys on the
+ * `when` reference too. Throws at module load so the misconfiguration surfaces
+ * immediately rather than as a silently double-evaluated predicate.
+ */
 declare const defineStorageRules: <Context = unknown>(rules: ReadonlyArray<StorageRule<Context>>) => ReadonlyArray<StorageRule<Context>>;
-/** The minimal `ctx.auth` shape the middleware reads — a structural subset that the full AuthState satisfies. Tolerant of older auth states (mirrors RLS's `AuthLike`). */
-type StorageAuthLike = {
-  getIdentity?: () => Promise<Record<string, unknown> | null>;
-  roles?: ReadonlyArray<string>;
-  userId?: null | string;
-};
 interface StorageContextIn {
-  auth?: StorageAuthLike;
+  auth?: AuthLike;
   storage?: unknown;
 }
 declare const storageRules: <Context extends StorageContextIn = StorageContextIn>(rules: ReadonlyArray<StorageRule<Context>>, options?: StorageRulesOptions) => Middleware<Context, Context>;
 declare const VERSION = "0.0.0";
-export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, type DataModelInit, type DefineComponentOptions, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type InferArgs, type InferEnv, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type LunoraBuilders, LunoraEnvError, LunoraError, type LunoraErrorCode, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskStrategy, type Middleware, type MiddlewareNext, type MigrationDefinition, type MigrationDocument, type MigrationTransform, type MutationBuilder, type MutationCtx, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type Role, type Schema, type SchemaExtension, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, asBucketStorage, bindOrm, bindTableFacade, composePluginMiddleware, createPolicyDsl, defineAggregateIndex, defineComponent, defineEnv, defineMigration, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, httpAction, httpRoute, httpRouter, initLunora, installPlugins, mask, mergeSchemaExtension, onConnect, onDisconnect, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules };
+export { DEFAULT_ACTION_CACHE_TTL_MS as ACTION_CACHE_DEFAULT_TTL_MS, ACTION_CACHE_TABLE, type ActionBuilder, type ActionCacheComponent, type ActionCacheContext, type ActionCacheDatabase, type ActionCacheFunctions, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_REDACTED_FIELDS as DOCUMENT_HISTORY_REDACTED_FIELDS, DOCUMENT_HISTORY_TABLE, type DataModelInit, type DeferredDeleteFlushResult, type DefineActionCacheOptions, type DefineComponentOptions, type DefineDocumentHistoryOptions, type DefineIdentityOptions, type DefineListArgsConfig, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type DocumentHistoryComponent, type DocumentHistoryEntry, type DocumentHistoryFunctions, type DurableObjectJurisdiction, type DurableStreamOptions, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExposeConfig, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type IdentityContract, type IdentityRejectMode, type IdentityValidation, type IndexFieldsByTable, type InferArgs, type InferEnv, type InferIdentity, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type ListArgsSpec, type ListArgsValidators, type ListArgsValue, type ListFilterOperators, type ListOrderByEntry, type ListWhere, type LunoraBuilders, LunoraEnvError, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskRegistry, type MaskStrategy, type Middleware, type MiddlewareContext, type MiddlewareNext, type MigrationCtx, type MigrationDefinition, type MigrationDocument, type MigrationReader, type MigrationTransform, type MutationBuilder, type MutationCtx, type MutatorDefinition, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type ReactorHandler, type ReactorOutcome, type ReactorSelect, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredMutator, type RegisteredQuery, type RegisteredReactor, type RegisteredShape, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type RlsReadRegistry, type Role, type Schema, type SchemaExtension, type ShapeDefinition, type ShapeReadWhereRequest, type ShardInitEvent, type ShardInitHandler, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type StorageServeAuthorizer, type StorageServeAuthzContext, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, actionCacheExtension, allowAll, asBucketStorage, beginDeferredSchedules, bindOrm, bindTableFacade, buildMaskRegistry, buildRlsReadRegistry, cacheKeyFor, clampLimit, composePluginMiddleware, composeShapeReadWhere, createPolicyDsl, createSecrets, defineActionCache, defineAggregateIndex, defineComponent, defineDocumentHistory, defineEnv, defineIdentity, defineListArgs, defineMigration, defineMutator, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineShape, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, deny, documentHistoryExtension, flushDeferredDeletes, httpAction, httpRoute, httpRouter, indexFieldsFromSchema, initLunora, installPlugins, isDeny, isSafeHeaderValue, mask, mergeSchemaExtension, onConnect, onDisconnect, onQueryChange, onShardInit, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules, toWhereInput, withDeferredDeletes, withDeferredSchedules };