@lunora/server 1.0.0-alpha.6 → 1.0.0-alpha.60

package/dist/index.d.mts

@@ -1,37 +1,41 @@
-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, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, 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, ValidatorMap, InferValidatorMap, ColumnValidator, v } 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, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, SearchLanguage, SearchStrategy, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } 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 PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type RestCacheConfig, 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 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 WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
+import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
+export 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 { 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-C4CMJK8x.mjs";
+export type { d as PolicyContext, e as PolicyDecision, f as PolicyDecisionOf, P as PolicyOperation } from "./packem_shared/types.d-C4CMJK8x.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.
-*/
+/**
+ * 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) is tagged as the `"default"` bucket, where
+ * `.bucket(name)` is the identity — single-bucket apps address one binding under
+ * every name.
+ *
+ * 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;
 /** 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,10 +43,10 @@ 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>;
@@ -50,17 +54,35 @@ type Middleware<ContextIn, ContextOut> = (options: {
 /** Options accepted by `initLunora.dataModel&lt;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/&lt;namespace>/&lt;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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  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 +92,48 @@ 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.
-  */
+   * 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: {
     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>;
+  /**
+   * 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/&lt;namespace>/&lt;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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  meta: (value: Record<string, unknown>) => MutationBuilder<Context, Args, Output>;
   mutation: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
     ctx: Context;
@@ -96,6 +143,13 @@ interface MutationBuilder<Context, Args extends ArgsValidator, Output = undefine
   }) => 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>;
+  /**
+   * 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 +160,56 @@ 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/&lt;namespace>/&lt;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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  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.
-*/
+  /**
+   * 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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  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>;
@@ -140,6 +230,17 @@ interface InternalMutationBuilder<Context, Args extends ArgsValidator, Output =
   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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  meta: (value: Record<string, unknown>) => InternalMutationBuilder<Context, Args, Output>;
   mutation: [Output] extends [undefined] ? <R>(handler: (options: {
     args: InferArgs<Args>;
     ctx: Context;
@@ -161,6 +262,17 @@ 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, is readable
+   * from middleware as `ctx.meta`, and is stamped onto the registration as
+   * `fn.meta` so codegen and other tooling can enumerate it.
+   *
+   * The point is policy that is DATA rather than a call: `.meta({ rateLimit:
+   * "pins/create" })` can be walked to generate a rate-limit registry or docs,
+   * where the same policy expressed only as `.use(rateLimit("pins/create"))`
+   * can only be executed. Mirrors tRPC's `.meta()`.
+   */
+  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>;
 }
@@ -179,38 +291,38 @@ 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.
-*/
+ * 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>;
 };
 /**
-* 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.
-*/
+ * 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;
 /**
-* 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.
-*/
+ * 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 {
@@ -220,32 +332,31 @@ interface EnvKeyFailure {
   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 Error {
-  override readonly name = "LunoraEnvError";
+ * 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$1 {
   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);`.
-*/
+ * 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>;
@@ -253,91 +364,40 @@ interface EnvAccessor<S extends EnvShape> {
   (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)`.
-*/
+ * 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>;
+declare class LunoraError extends LunoraError$1 {
+  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
+}
 /**
-* 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);
-}
-/**
-* 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.
-*/
+ * 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>;
@@ -349,6 +409,11 @@ interface FacadeWriterLike {
   }, 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>;
@@ -357,15 +422,27 @@ interface FacadeWriterLike {
   insert(tableName: string, document: Record<string, unknown>): Promise<string>;
   insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
-  }): Promise<string[]>;
+    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<void>;
+  }, 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>;
@@ -378,11 +455,19 @@ 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;
-  }>;
+  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>;
@@ -393,16 +478,34 @@ interface FacadeEntry {
   /** 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&lt;T>[]` when skipDuplicates is not requested.
+   */
   insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
-  }) => Promise<string[]>;
+    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<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>;
@@ -412,15 +515,16 @@ interface FacadeEntry {
   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 })`.
-  */
+   * 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. */
@@ -448,17 +552,17 @@ interface UpsertManyArgs {
   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&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.
-*/
+ * 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 {
@@ -479,21 +583,40 @@ 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">;
+ * 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 = Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery"> & {
+  readonly scheduler?: ActionCtx["scheduler"];
+  readonly storage?: ActionCtx["storage"];
+};
 /** 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.
-*/
+ * 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;
@@ -507,31 +630,31 @@ 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`.
-*/
+ * 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.
-*/
+ * 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> {
@@ -541,11 +664,12 @@ interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body exten
   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.
-*/
+ * 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>;
@@ -554,35 +678,51 @@ interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params ex
   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)`.
-*/
+ * 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&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.
-  */
+   * 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.
+   * @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>;
@@ -597,33 +737,33 @@ interface HttpRoute {
   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);
-* ```
-*/
+ * 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;
 /**
-* 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.
-*/
+ * 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;
@@ -654,325 +794,302 @@ interface ContextWithStorage {
   storage: StorageDownloader;
 }
 /**
-* 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.
-*/
+ * 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;
+/**
+ * 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>;
+/**
+ * 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;
+};
+/**
+ * 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;
 /** 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>;
-}
-/**
-* 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 QueryPage$1 {
-  continueCursor: null | string;
-  isDone: boolean;
-  page: Record<string, unknown>[];
-}
-interface QueryArgs$1 {
-  baseWhere?: unknown;
-  cursor?: null | string;
+/** 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;
-  where?: unknown;
-  with?: Record<string, unknown>;
-}
-interface AggregateArgs$1 {
-  field?: string;
-  op: string;
-}
-interface GroupByArgs$1 {
-  agg?: {
-    field?: string;
-    op: string;
-  };
-  by: ReadonlyArray<string>;
+  orderBy?: ListOrderByEntry<O>[];
+  where?: ListWhere<F>;
 }
-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>;
-  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 {
-  aggregate: (tableName: string, options: AggregateArgs$1) => 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;
-  }>;
-  findFirst: (tableName: string, args?: QueryArgs$1) => Promise<Record<string, unknown> | null>;
-  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>;
-  groupBy: (tableName: string, options: GroupByArgs$1) => 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[]>;
-  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<void>;
-  query: (tableName: string) => TableReaderLike$1;
-  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$1>;
-  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+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&lt;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.&lt;table>.findMany(...)` options. See the module docs
+ * for the shape and the reasoning behind it.
+ *
+ * Curried on the document type: `defineListArgs&lt;Doc&lt;"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>;
 }
-/** Roles list source on the context. Tolerant of older auth states (mirrors RLS's `AuthLike`). */
-type AuthLike$1 = {
-  getIdentity?: () => Promise<Record<string, unknown> | null>;
-  roles?: ReadonlyArray<string>;
-  userId?: null | string;
-};
-interface MaskContextIn {
-  auth?: AuthLike$1;
-  db: MaskDatabase;
+/** Structural mirror of `@lunora/shard-engine`'s `RankPageRow`. */
+interface RankPageRowLike {
+  doc: Record<string, unknown>;
+  key: RankPageRowKeyLike;
 }
-/**
-* 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;
+/** Structural mirror of `@lunora/shard-engine`'s `ShardRankPageResult` — the `rankPageRows` return shape. */
+interface ShardRankPageResultLike {
+  directions: ReadonlyArray<"asc" | "desc">;
+  hasMore: boolean;
+  rows: ReadonlyArray<RankPageRowLike>;
 }
-/** Declare an online data migration. See the module docs for runtime semantics. */
-declare const defineMigration: (definition: MigrationDefinition) => RegisteredMigration;
 /**
-* 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.
-*/
+ * 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>;
 /**
-* 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-  */
+   * 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).
-  */
+   * 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.
-*/
+ * 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).
-*/
+ * 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)`.
-  */
+   * 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 } } })
-  * ```
-  */
+   * 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}. */
@@ -981,35 +1098,51 @@ interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>
   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.
-*/
+ * 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.
-*/
+ * 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;
 }
@@ -1018,81 +1151,91 @@ interface DefineComponentOptions<TExtension extends Record<string, TableDefiniti
   functions?: F;
 }
 /**
-* 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.
-*/
+ * 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>;
 /**
-* 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.
-*/
+ * 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>;
 /**
-* 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(...)`.
-*/
+ * 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>>;
 /**
-* 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.
-*/
+ * 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>> {
@@ -1129,10 +1272,10 @@ interface RelationBuilder {
   }) => OneRelation<Target>;
 }
 /**
-* 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.
-*/
+ * 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>;
@@ -1144,11 +1287,11 @@ interface InlineAggregateIndexOptions<Shape extends Record<string, Validator> =
   where?: Record<string, 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.
-*/
+ * 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>;
@@ -1164,66 +1307,127 @@ interface TableBuilder<Shape extends Record<string, Validator> = Record<string,
   /** 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(...)`.
-  */
+   * 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.
-  */
+   * 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<string>, options?: {
+  index: (name: string, fields: ReadonlyArray<(keyof Shape & string) | (typeof SYSTEM_INDEX_FIELDS)[number]>, 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.
-  */
+   * 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}.
-  */
+   * 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. */
+  /**
+   * 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. `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.&lt;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).
-  */
+   * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
+   * default `deletedAt`) and changes `ctx.db.&lt;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>;
 }
@@ -1241,22 +1445,22 @@ interface VectorIndexOptions {
   };
 }
 /**
-* Build a table definition. Returned object is both the table definition (for
-* `defineSchema`) and a fluent builder for indexes + sharding metadata.
-*/
+ * 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 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.
-*/
+ * 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;
@@ -1265,17 +1469,17 @@ interface AggregateIndexOptions {
   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 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.
-*/
+ * 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<{
@@ -1286,84 +1490,493 @@ interface RankIndexOptions {
   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 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.
-*/
+ * 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/
-  */
+   * 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.
-  */
+   * 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 ["_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>;
+/**
+ * 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>;
+}
+/**
+ * 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.
+ * - `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>;
+}
+interface QueryPage$1 {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
+}
+interface QueryArgs$1 {
+  baseWhere?: unknown;
+  cursor?: null | string;
+  limit?: number;
+  orderBy?: ReadonlyArray<Record<string, unknown>>;
+  where?: unknown;
+  with?: Record<string, unknown>;
+}
+interface AggregateArgs$1 {
+  field?: string;
+  op: string;
+  where?: unknown;
+}
+interface GroupByArgs$1 {
+  agg?: {
+    field?: string;
+    op: string;
+  };
+  by: ReadonlyArray<string>;
+  where?: 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;
+}
+/** A `.withSearchIndex()` row — mirrors `@lunora/shard-engine`'s `SearchScoredDocument`. */
+interface SearchScoredDocument {
+  distanceMeters?: never;
+  document: Record<string, unknown>;
+  score: number;
+}
+interface TableReaderLike$1 {
+  [Symbol.asyncIterator]: () => AsyncIterator<Record<string, unknown>>;
+  collect: () => Promise<Record<string, unknown>[]>;
+  collectWithScores: () => Promise<ScoredDocument[]>;
+  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 {
+  aggregate: (tableName: string, options: AggregateArgs$1) => 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$1) => Promise<Record<string, unknown> | null>;
+  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>;
+  groupBy: (tableName: string, options: GroupByArgs$1) => 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$1;
+  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$1>;
+  /** 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>;
+}
+/** Roles list source on the context. Tolerant of older auth states (mirrors RLS's `AuthLike`). */
+type AuthLike$1 = {
+  getIdentity?: () => Promise<Record<string, unknown> | null>;
+  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>;
+/** 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>;
+/**
+ * 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[];
+  }>;
+  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;
+/**
+ * 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> {
+  /**
+   * 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>;
@@ -1377,41 +1990,41 @@ 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.
-  */
+   * 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>;
@@ -1420,17 +2033,17 @@ 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; this
+   * only reclaims storage. Schedule it (cron / `runAfter`) if you care.
+   */
   sweep: RegisteredMutation<{
     roomId: ReturnType<typeof v.string>;
   }, {
@@ -1444,114 +2057,114 @@ 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>;
 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&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>, 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.
-*/
+ * 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`.
-  */
+   * 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;
@@ -1620,41 +2233,54 @@ interface TableReaderLike {
     numItems: number;
   }) => Promise<QueryPage>;
   take: (limit: number) => Promise<Record<string, unknown>[]>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => TableReaderLike;
   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`.
-*/
+ * 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.
-  */
+   * 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, 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;
+  }>;
   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>;
   /**
-  * 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`.
-  */
+   * 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;
@@ -1662,19 +2288,20 @@ interface DatabaseWriterLike {
   insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
   insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
-  }) => Promise<string[]>;
+    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.
-  */
+   * 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;
@@ -1685,14 +2312,24 @@ interface DatabaseWriterLike {
     patch: Record<string, unknown>;
   }>, options?: {
     limit?: number;
-  }, expectedTable?: string) => 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;
   /**
-  * 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 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;
@@ -1703,24 +2340,43 @@ interface DatabaseWriterLike {
     total: number;
   }>;
   /**
-  * 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`.
-  */
+   * 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>;
+  /**
+   * 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>;
+  }>;
 }
 /**
-* 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`.
-*/
+ * 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 = {
@@ -1735,21 +2391,183 @@ interface RlsContextIn {
 }
 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`).
-*/
+ * 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;
+  /** Role labels the request carries (drives `auth.can(...)`). */
+  readonly roles: ReadonlyArray<string>;
+  /** 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> {
+  /**
+   * 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;
+  /**
+   * 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>;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
@@ -1764,11 +2582,11 @@ 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.
+   */
   readonly bucket: string;
   readonly on: StorageOperation;
   /** Optional key-prefix scope; the rule only governs keys under it. Absent ⇒ the whole bucket. */
@@ -1783,27 +2601,27 @@ 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 = {
@@ -1817,4 +2635,4 @@ interface StorageContextIn {
 }
 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 DurableObjectJurisdiction, 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, createSecrets, 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 { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, type DataModelInit, type DefineComponentOptions, type DefineIdentityOptions, type DefineListArgsConfig, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type DurableObjectJurisdiction, 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, LunoraError, 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 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 RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredMutator, type RegisteredQuery, type RegisteredShape, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type RlsReadRegistry, type Role, type Schema, type SchemaExtension, type ShapeDefinition, type ShapeReadWhereRequest, 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, allowAll, asBucketStorage, bindOrm, bindTableFacade, buildMaskRegistry, buildRlsReadRegistry, clampLimit, composePluginMiddleware, composeShapeReadWhere, createPolicyDsl, createSecrets, defineAggregateIndex, defineComponent, defineEnv, defineIdentity, defineListArgs, defineMigration, defineMutator, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineShape, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, deny, httpAction, httpRoute, httpRouter, indexFieldsFromSchema, initLunora, installPlugins, isDeny, isSafeHeaderValue, mask, mergeSchemaExtension, onConnect, onDisconnect, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules, toWhereInput };