@lunora/server 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,1985 @@
+import { Validator, Infer, ValidatorMap, InferValidatorMap, 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, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.js";
+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.js";
+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-BDY0FYHK.js";
+export type { d as PolicyContext, e as PolicyDecision, f as PolicyDecisionOf, P as PolicyOperation } from "./packem_shared/types.d-BDY0FYHK.js";
+export { type CronJob, type CronJobsBuilder, type CronScheduleKind, type DailySchedule, type IntervalSchedule, type MonthlySchedule, type WeeklySchedule, cronJobs } from '@lunora/scheduler';
+import "./data-model.js";
+/**
+* Make any `config.storage` result bucket-aware so `ctx.storage.bucket(name)`
+* always resolves. A `createBucketStorage(...)` result already carries
+* `.bucket` / `.bucketName` and is returned as-is; a single `createStorage(...)`
+* (or the no-storage stub) is tagged as the `"default"` bucket, where
+* `.bucket(name)` is the identity — single-bucket apps address one binding under
+* every name.
+*
+* This is the runtime counterpart the generated `_generated/shard.ts` imports to
+* wrap `ctx.storage`; it lives here (the single source) rather than being stamped
+* inline into every generated file, so the bucket-tagging behaviour has one home
+* alongside the storage ctx types. The input is genuinely heterogeneous (a thunk
+* result cast through `unknown`), so the signature is `unknown → unknown`; the
+* generated caller casts the result to its storage type.
+*/
+declare const asBucketStorage: (raw: unknown) => unknown;
+/** 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.
+*/
+interface MiddlewareNext<ContextIn> {
+  (): Promise<ContextIn>;
+  <Extension extends Record<string, unknown>>(options: {
+    ctx: Extension;
+  }): 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.
+*/
+type Middleware<ContextIn, ContextOut> = (options: {
+  ctx: ContextIn;
+  next: MiddlewareNext<ContextIn>;
+}) => ContextOut | Promise<ContextOut>;
+/** Options accepted by `initLunora.dataModel&lt;DM>().create(...)`. Reserved for transformer/error-formatter wiring. */
+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.
+*/
+interface QueryBuilder<Context, Args extends ArgsValidator, Output = undefined> {
+  readonly __lunoraProcedure: "query";
+  input: <A extends ArgsValidator>(validators: A) => QueryBuilder<Context, A & Args, Output>;
+  output: <V extends Validator>(validator: V) => QueryBuilder<Context, Args, Infer<V>>;
+  query: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredQuery<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredQuery<Args, Output>;
+  /**
+  * Terminal: declare this procedure as a streaming query. The handler is an
+  * async generator (or any function returning an `AsyncIterable&lt;R>`) that
+  * yields one chunk per server-pushed frame. The third `signal` argument is
+  * tripped when the client cancels — break out of the loop or check
+  * `signal.aborted` between yields. `.output()` does not apply: per-chunk
+  * validation is opt-in via the handler itself.
+  */
+  stream: <R>(handler: (options: {
+    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>;
+}
+interface MutationBuilder<Context, Args extends ArgsValidator, Output = undefined> {
+  readonly __lunoraProcedure: "mutation";
+  input: <A extends ArgsValidator>(validators: A) => MutationBuilder<Context, A & Args, Output>;
+  mutation: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredMutation<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredMutation<Args, Output>;
+  output: <V extends Validator>(validator: V) => MutationBuilder<Context, Args, Infer<V>>;
+  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => MutationBuilder<ContextOut, Args, Output>;
+}
+interface ActionBuilder<Context, Args extends ArgsValidator, Output = undefined> {
+  readonly __lunoraProcedure: "action";
+  action: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredAction<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredAction<Args, Output>;
+  input: <A extends ArgsValidator>(validators: A) => ActionBuilder<Context, A & 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.
+*/
+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>;
+  output: <V extends Validator>(validator: V) => InternalQueryBuilder<Context, Args, Infer<V>>;
+  query: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredQuery<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredQuery<Args, Output>;
+  /** See {@link QueryBuilder.stream}; the internal variant routes the registration into `internal` instead of `api`. */
+  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>) => InternalQueryBuilder<ContextOut, Args, Output>;
+}
+interface InternalMutationBuilder<Context, Args extends ArgsValidator, Output = undefined> {
+  readonly __lunoraProcedure: "mutation";
+  readonly __lunoraVisibility: "internal";
+  input: <A extends ArgsValidator>(validators: A) => InternalMutationBuilder<Context, A & Args, Output>;
+  mutation: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredMutation<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredMutation<Args, Output>;
+  output: <V extends Validator>(validator: V) => InternalMutationBuilder<Context, Args, Infer<V>>;
+  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => InternalMutationBuilder<ContextOut, Args, Output>;
+}
+interface InternalActionBuilder<Context, Args extends ArgsValidator, Output = undefined> {
+  readonly __lunoraProcedure: "action";
+  readonly __lunoraVisibility: "internal";
+  action: [Output] extends [undefined] ? <R>(handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Promise<R> | R) => RegisteredAction<Args, Awaited<R>> : (handler: (options: {
+    args: InferArgs<Args>;
+    ctx: Context;
+  }) => Output | Promise<Output>) => RegisteredAction<Args, Output>;
+  input: <A extends ArgsValidator>(validators: A) => InternalActionBuilder<Context, A & Args, Output>;
+  output: <V extends Validator>(validator: V) => InternalActionBuilder<Context, Args, Infer<V>>;
+  use: <ContextOut>(middleware: Middleware<Context, ContextOut>) => InternalActionBuilder<ContextOut, Args, Output>;
+}
+/** The public root builders plus their `internal*` counterparts, returned by `.create()`. */
+interface LunoraBuilders {
+  action: ActionBuilder<ActionCtx, EmptyArgs>;
+  internalAction: InternalActionBuilder<ActionCtx, EmptyArgs>;
+  internalMutation: InternalMutationBuilder<MutationCtx, EmptyArgs>;
+  internalQuery: InternalQueryBuilder<QueryCtx, EmptyArgs>;
+  mutation: MutationBuilder<MutationCtx, EmptyArgs>;
+  query: QueryBuilder<QueryCtx, EmptyArgs>;
+}
+interface DataModelInit<DataModel> {
+  /** Phantom carrier for the generated `DataModel`; reserved for typed `ctx.db` (Plan2 1.2.7). */
+  readonly __dataModel?: DataModel;
+  create: (options?: CreateOptions) => LunoraBuilders;
+}
+/**
+* Entry point for the procedure builder. `dataModel&lt;DM>()` binds the generated
+* `DataModel` (phantom for now), and `.create()` yields the public root builders
+* plus their `internal*` counterparts.
+*/
+declare const initLunora: {
+  dataModel: <DataModel>() => DataModelInit<DataModel>;
+};
+/**
+* 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.
+*/
+declare const redactSecrets: (message: string) => string;
+/** One key's validation failure, secrets already redacted out of `message`. */
+interface EnvKeyFailure {
+  /** The env key that failed. */
+  key: string;
+  /** Redacted human-readable reason. */
+  message: string;
+}
+/**
+* Thrown when one or more env keys are missing or fail validation. Carries the
+* structured list of `failures` (each with the offending `key`) so callers can
+* react programmatically; `message` is the joined, secret-redacted summary.
+*
+* Named export only (no default) per the repo export convention.
+*/
+declare class LunoraEnvError extends Error {
+  override readonly name = "LunoraEnvError";
+  readonly failures: ReadonlyArray<EnvKeyFailure>;
+  constructor(failures: ReadonlyArray<EnvKeyFailure>);
+}
+/** A record of `v.*` validators describing the expected env shape. */
+type EnvShape = Record<string, Validator>;
+/**
+* The typed output of {@link defineEnv}. Optional validators (`v.optional(...)`)
+* become optional keys; everything else is required. Mirrors how `InferArgs`
+* derives an args object from a validator map.
+*/
+type InferEnv<S extends EnvShape> = { [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]> } & { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]> };
+/**
+* The accessor returned by {@link defineEnv}. A typed view over an `env` object
+* plus a `.parse(env)` escape hatch that validates every key eagerly.
+*
+* Call the accessor with the worker's `env` to get the typed, lazily-validated
+* proxy: `const config = defineEnv({ … }); const { PORT } = config(env);`.
+*/
+interface EnvAccessor<S extends EnvShape> {
+  /** Validate every key eagerly and return the typed, plain (non-proxy) object. Use for fail-fast-at-boot. */
+  parse: (env: unknown) => InferEnv<S>;
+  /** Lazily-validated, per-key-cached typed view over `env`. Keys are validated on first access. */
+  (env: unknown): InferEnv<S>;
+}
+/**
+* Define a typed, validated accessor over a Worker's `env`. Pass a record of
+* `v.*` validators; receive an accessor that validates lazily per key (cached
+* per `env` identity) and infers its output type from the validators.
+*
+* ```ts
+* import { defineEnv, v } from "@lunora/server";
+*
+* const config = defineEnv({
+*     STRIPE_KEY: v.string(),
+*     PORT: v.optional(v.number()),
+* });
+*
+* export default {
+*     fetch(request, env) {
+*         const { STRIPE_KEY, PORT } = config(env); // STRIPE_KEY: string, PORT?: number
+*         // …
+*     },
+* };
+* ```
+*
+* Throws {@link LunoraEnvError} (secrets redacted) when a key is missing or
+* invalid — lazily on first access of that key, or eagerly via `config.parse(env)`.
+*/
+declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
+/**
+* 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; the optional `data` carries a
+* structured, JSON+wire-encodable payload propagated verbatim to the client
+* (e.g. `{ retryAfterMs }`). Only an explicit `LunoraError`'s `data` crosses the
+* wire — an unhandled throw is still redacted to a generic message server-side.
+*/
+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;
+  /** Structured, JSON+wire-encodable payload surfaced to the client alongside `code`. */
+  readonly data?: unknown;
+  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
+}
+/**
+* Minimal structural writer the facade binds over. Declared with **method**
+* syntax (not arrow properties) so a more-specifically-typed writer — both
+* `@lunora/do`'s `DatabaseWriterLike` and the RLS middleware's wrapped writer —
+* stays assignable under bivariant parameter checking. That is the whole reason
+* the shared helper can serve both callers, hence the rule exemption.
+*/
+interface FacadeWriterLike {
+  aggregate(tableName: string, options: unknown): Promise<unknown>;
+  count(tableName: string, where?: unknown): Promise<number>;
+  delete(id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }): Promise<void>;
+  deleteMany?(ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }, expectedTable?: string): Promise<{
+    deleted: number;
+  }>;
+  findFirst(tableName: string, args?: unknown): Promise<unknown>;
+  findFirstOrThrow(tableName: string, args?: unknown): Promise<unknown>;
+  findMany(tableName: string, args?: unknown): Promise<unknown>;
+  get(id: string, expectedTable?: string): Promise<unknown>;
+  groupBy(tableName: string, options: unknown): Promise<unknown>;
+  insert(tableName: string, document: Record<string, unknown>): Promise<string>;
+  insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+  }): Promise<string[]>;
+  patch(id: string, patch: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  patchMany?(patches: ReadonlyArray<{
+    id: string;
+    patch: Record<string, unknown>;
+  }>, options?: {
+    limit?: number;
+  }, expectedTable?: string): Promise<void>;
+  query(tableName: string): {
+    withSearchIndex(indexName: string, search: (q: unknown) => unknown): unknown;
+  };
+  rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
+  rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
+  replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  restore?(id: string, expectedTable?: string): Promise<void>;
+}
+/** The per-table accessor object returned for the `ctx.db` table form. */
+interface FacadeEntry {
+  aggregate: (options: unknown) => Promise<unknown>;
+  count: (where?: unknown) => Promise<number>;
+  delete: (id: string) => Promise<void>;
+  deleteMany: (ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
+  exists: (where?: unknown) => Promise<boolean>;
+  findFirst: (args?: unknown) => Promise<unknown>;
+  findFirstOrThrow: (args?: unknown) => Promise<unknown>;
+  findMany: (args?: unknown) => Promise<unknown>;
+  get: (id: string) => Promise<unknown>;
+  groupBy: (options: unknown) => Promise<unknown>;
+  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
+  hardDelete: (id: string) => Promise<void>;
+  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
+  insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+  }) => Promise<string[]>;
+  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
+  patchMany: (patches: ReadonlyArray<{
+    id: string;
+    values: Record<string, unknown>;
+  }>, options?: {
+    limit?: number;
+  }) => Promise<void>;
+  rank: (indexName: string, options: unknown) => Promise<unknown>;
+  rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
+  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
+  restore: (id: string) => Promise<void>;
+  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
+  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
+  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
+  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
+}
+/** Options accepted by the per-table `insert` accessor. */
+interface FacadeInsertOptions {
+  /**
+  * When `true`, a UNIQUE-constraint breach is swallowed: the insert becomes a
+  * silent no-op and resolves to `null` instead of throwing a `CONFLICT`. Any
+  * other error still propagates. Mirrors better-drizzle's `create({ skipDuplicates })`.
+  */
+  skipDuplicates?: boolean;
+}
+/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
+type UpsertTarget = ReadonlyArray<string> | string;
+/** Argument to the per-table `upsert` accessor. */
+interface UpsertArgs {
+  /** Document inserted when no existing row matches the `target`. */
+  create: Record<string, unknown>;
+  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
+  target: UpsertTarget;
+  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
+  update?: Record<string, unknown>;
+}
+/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
+interface UpsertResult {
+  created: boolean;
+  id: string;
+}
+/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
+interface UpsertManyArgs {
+  rows: ReadonlyArray<{
+    create: Record<string, unknown>;
+    update?: Record<string, unknown>;
+  }>;
+  target: UpsertTarget;
+}
+/**
+* Bind a structural writer to one table, producing its `ctx.db` table accessor.
+*
+* The by-id accessors (`get`/`delete`/`patch`/`replace`) forward the bound
+* `tableName` as `expectedTable` so the underlying writer scopes its id lookup
+* to this table. Without it, a branded `Id&lt;"posts">` carrying another table's
+* id would resolve cross-table (the writer probes every table by id), letting
+* `ctx.db.posts.get(foreignId)` read — or `.delete`/`.patch`/`.replace`
+* mutate — a row in an unrelated table (IDOR). Writers that ignore the second
+* argument keep their previous global behaviour; the scoping is opt-in via this
+* forwarded name.
+*/
+declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) => FacadeEntry;
+/** The kitcn-style `ctx.orm` namespace over a per-table facade map. */
+interface OrmLike {
+  delete: (table: string, id: string) => Promise<void>;
+  insert: (table: string) => {
+    values: (document: Record<string, unknown>) => Promise<null | string>;
+  };
+  query: Record<string, FacadeEntry>;
+  replace: (table: string, id: string) => {
+    with: (document: Record<string, unknown>) => Promise<void>;
+  };
+  update: (table: string, id: string) => {
+    set: (values: Record<string, unknown>) => Promise<void>;
+  };
+}
+/** Build `ctx.orm` over a per-table facade map (table name → FacadeEntry). */
+declare const bindOrm: (facade: Record<string, FacadeEntry>) => OrmLike;
+/** HTTP verbs the typed {@link httpRoute} builder can bind to. */
+type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+/**
+* Context handed to an HTTP action handler. A narrower view of {@link ActionContext}:
+* HTTP actions run in the worker (the "action runtime"), separate from the
+* transactional store, so there is no direct `db` / `vectors` / `scheduler` /
+* `storage` surface — reach the data layer through `runQuery` / `runMutation` /
+* `runAction`, which forward to the owning shard.
+*/
+type HttpActionCtx = Pick<ActionCtx, "auth" | "fetch" | "runAction" | "runMutation" | "runQuery">;
+/** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
+type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
+/**
+* The hono {@link https://hono.dev | Hono} environment used by {@link httpRouter}.
+* The runtime injects the per-request {@link HttpActionCtx} on the private
+* `__lunoraCtx` binding; the router's lifting middleware promotes it to
+* `c.var.lunora` so handlers can read it as a typed variable.
+*/
+interface LunoraHttpEnv {
+  Bindings: Record<string, unknown> & {
+    __lunoraCtx?: HttpActionCtx;
+  };
+  Variables: {
+    lunora: HttpActionCtx;
+  };
+}
+/** The hono app type {@link httpRouter} returns. */
+type LunoraHttpApp = Hono<LunoraHttpEnv>;
+/** A compiled route handler: a hono handler that resolves to a raw {@link Response}. */
+type LunoraRouteHandler = (c: Context<LunoraHttpEnv>) => Promise<Response>;
+/**
+* Wrap a `(ctx, request) => Response` handler as a hono handler. The raw escape
+* hatch — mount it with `app.all(path, httpAction(fn))`. `ctx` is the
+* runtime-injected {@link HttpActionCtx} lifted into `c.var.lunora` by
+* {@link httpRouter}; `request` is the underlying `c.req.raw`.
+*/
+declare const httpAction: (handler: HttpActionHandler) => LunoraRouteHandler;
+/**
+* Create the hono app for HTTP actions. Pre-wired with a middleware that lifts
+* the runtime-injected `c.env.__lunoraCtx` into `c.var.lunora`, so both
+* {@link httpAction} and the typed {@link httpRoute} builder can read the action
+* context. The full hono surface is available — plugins, path params, `.route`:
+*
+* ```ts
+* const app = httpRouter();
+* app.use("*", cors());
+* app.post("/webhook", httpAction(onWebhook));
+* app.get("/users/:id", getUser);
+* export default createWorker({ httpRouter: app, ... });
+* ```
+*
+* The lifting middleware throws if the context is absent. `createWorker` injects
+* it on every request the router sees, so this only trips when the app is run
+* outside the runtime — a misconfiguration we surface loudly rather than let
+* `c.var.lunora` be silently `undefined` despite its non-optional type.
+*/
+declare const httpRouter: () => LunoraHttpApp;
+/** The `{ ctx, searchParams, body, params }` a typed route handler receives. */
+interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator> {
+  body: InferArgs<Body>;
+  ctx: HttpActionCtx;
+  params: InferArgs<Params>;
+  searchParams: InferArgs<SearchParams>;
+}
+/**
+* The `{ ctx, searchParams, params, request, signal }` a streaming HTTP
+* handler receives. There is no parsed `body` — streams are typically GET, and
+* the raw `request` is exposed if a handler needs to read the body itself.
+* `signal` is tripped when the client disconnects.
+*/
+interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
+  ctx: HttpActionCtx;
+  params: InferArgs<Params>;
+  request: Request;
+  searchParams: InferArgs<SearchParams>;
+  signal: AbortSignal;
+}
+/**
+* A typed REST route under construction. `.searchParams()` / `.body()` /
+* `.params()` accumulate validator maps (later calls merge, a colliding key
+* wins) that decode the URL query, JSON body, and hono path params into the
+* handler's typed `searchParams` / `body` / `params`. Like the procedure
+* builder, `.output(validator)` defaults to the `undefined` sentinel — while
+* unset the handler is generic over its own return; once set the handler must
+* return that type and the result is parsed through the validator before
+* serialization. `[Output] extends [undefined]` is tuple-wrapped so a union
+* `Output` doesn't distribute and the test is for the exact sentinel.
+*
+* The terminal `.handler()` yields a {@link LunoraRouteHandler} — mount it
+* directly with `app.get(path, route)`.
+*/
+interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
+  body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
+  handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
+  output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
+  params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
+  searchParams: <S extends ArgsValidator>(validators: S) => HttpRouteBuilder<S & SearchParams, Body, Params, Output>;
+  /**
+  * Terminal: declare this route as a streaming Server-Sent Events endpoint.
+  * The handler is an async generator (or any function returning an
+  * `AsyncIterable&lt;R>`) that yields one chunk per SSE `data:` frame; on
+  * iterator completion the route writes a final `event: complete` frame; on
+  * throw, an `event: error` frame is written with `{code, message}` before
+  * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
+  * handler's yielded type.
+  */
+  stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+}
+/** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
+type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;
+/** The verb-keyed entry point: `httpRoute.get("/api/todos")…`. */
+interface HttpRoute {
+  delete: HttpRouteFactory;
+  get: HttpRouteFactory;
+  head: HttpRouteFactory;
+  options: HttpRouteFactory;
+  patch: HttpRouteFactory;
+  post: HttpRouteFactory;
+  put: HttpRouteFactory;
+}
+/**
+* Typed REST route builder. Compiles down to a {@link LunoraRouteHandler}, so a
+* typed route and a hand-written {@link httpAction} are interchangeable when
+* mounted on {@link httpRouter}:
+*
+* ```ts
+* export const listTodos = httpRoute
+*     .get("/api/todos")
+*     .searchParams({ limit: v.number(), q: v.optional(v.string()) })
+*     .output(v.array(v.object({ id: v.string(), text: v.string() })))
+*     .handler(async ({ ctx, searchParams }) => ctx.runQuery(api.todos.list, searchParams));
+*
+* export const getTodo = httpRoute
+*     .get("/api/todos/:id")
+*     .params({ id: v.string() })
+*     .handler(async ({ ctx, params }) => ctx.runQuery(api.todos.get, params));
+*
+* const app = httpRouter();
+* app.get("/api/todos", listTodos);
+* app.get("/api/todos/:id", getTodo);
+* ```
+*/
+declare const httpRoute: HttpRoute;
+/**
+* Structural view of an R2 object body, as returned by `@lunora/storage`'s
+* `download()`. Re-declared here (not imported) so `@lunora/server` takes no
+* runtime dependency on `@lunora/storage`; the real binding satisfies the shape.
+*/
+interface StorageObjectBody {
+  /** The object body stream (`null` for a zero-byte object). */
+  body: ReadableStream | null;
+  etag: string;
+  httpMetadata?: {
+    contentType?: string;
+  };
+  key: string;
+  /** Hex SHA-256, when R2 carries a checksum (surfaced by `@lunora/storage`). */
+  sha256?: string;
+  /** Base64 SHA-256 (RFC 9530 digest encoding), when R2 carries a checksum. */
+  sha256Base64?: string;
+  size: number;
+}
+/** Byte window forwarded to `download()` so R2 streams just the requested slice. */
+interface StorageRange {
+  length: number;
+  offset: number;
+}
+/** The minimal storage surface {@link serveStorageObject} needs: a metadata-rich `download`. */
+interface StorageDownloader {
+  download: (key: string, options?: {
+    range?: StorageRange;
+  }) => Promise<StorageObjectBody | null>;
+}
+/** Any ctx that carries a {@link StorageDownloader} on `.storage` (Query/Mutation/Action ctx all do). */
+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.
+*/
+declare const serveStorageObject: (context: ContextWithStorage, key: string, request: Request) => Promise<Response>;
+/** 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;
+  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>;
+}
+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>;
+}
+/** 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>;
+/**
+* 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;
+}
+/** 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;
+  /**
+  * 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>;
+/**
+* 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.
+*/
+type InstalledTables<T extends Record<string, TableDefinition>, Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? InstalledTables<ExtensionTablesOf<Head> & T, Rest> : T;
+/**
+* Union every plugin's `ContextOut` in a tuple — the type-level mirror of the
+* `ctx.api.&lt;key>` additions {@link composePluginMiddleware} accumulates as each
+* plugin middleware runs. Independent of the incoming context, which the builder
+* infers at the `.use(...)` site.
+*/
+type ComposedOut<Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? ComposedOut<Rest> & (Head extends Plugin<any, any, infer Out> ? Out : unknown) : unknown;
+/**
+* Schema fragment a plugin contributes. Same shape as the `tables` map
+* passed to `defineSchema`. Optional `vectorIndexes` mirror the top-level
+* `defineSchema` argument so a plugin can ship vector decls alongside its
+* tables.
+*/
+interface SchemaExtension<T extends Record<string, TableDefinition> = Record<string, TableDefinition>> {
+  /** Stable key identifying the plugin that owns this extension. */
+  readonly key: string;
+  /**
+  * Extension tables, keyed by **bare** name (e.g. `buckets`). At merge time
+  * each is auto-prefixed with `key` (`ratelimit_buckets`) so it can't
+  * collide with an app table; do **not** namespace manually.
+  */
+  readonly tables: T;
+  /**
+  * Optional standalone vector indexes the plugin ships, keyed by index
+  * name. Merged into the host schema's `vectorIndexes`; a key collision
+  * with the base schema is a hard error (same policy as tables).
+  */
+  readonly vectorIndexes?: Record<string, VectorIndexDefinition>;
+}
+/**
+* Build a {@link SchemaExtension}. The `key` is a runtime tag (used for
+* error messages on collision) and a type-level brand.
+*/
+declare const defineSchemaExtension: <T extends Record<string, TableDefinition>>(key: string, options: {
+  tables: T;
+  vectorIndexes?: Record<string, VectorIndexDefinition>;
+}) => SchemaExtension<T>;
+/**
+* A plugin packages an optional schema extension and optional middleware.
+* Both are independently usable: an app can install only the schema (e.g.
+* for plugins that ship background workers but no per-request behavior)
+* or only the middleware (plugins that augment ctx without persistent
+* state).
+*/
+interface Plugin<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn> {
+  /**
+  * Optional schema extension. Apps install via
+  * `defineSchema(...).extend(plugin.extension)`.
+  */
+  readonly extension?: SchemaExtension<TExtension>;
+  /** Stable key identifying the plugin. Matches `extension.key` when set. */
+  readonly key: string;
+  /**
+  * Optional middleware. Users attach with `c.query.use(plugin.middleware)`.
+  * The middleware can extend `ctx`; convention is to attach helpers under
+  * `ctx.api.&lt;key>`, e.g.
+  *
+  * ```ts
+  * middleware: ({ ctx, next }) =>
+  *     next({ ctx: { api: { ...ctx.api, ratelimit: api } } })
+  * ```
+  */
+  readonly middleware?: Middleware<TContextIn, TContextOut>;
+}
+/** Options to {@link definePlugin}. */
+interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut> {
+  extension?: SchemaExtension<TExtension>;
+  middleware?: Middleware<TContextIn, TContextOut>;
+}
+/**
+* Package a schema extension + middleware as a reusable plugin. Either
+* field is optional — `definePlugin("foo", {})` is valid but degenerate.
+*/
+declare const definePlugin: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>) => Plugin<TExtension, TContextIn, TContextOut>;
+/**
+* Bundle of registered functions a {@link Component} ships. Keys are the
+* function's local name (e.g. `check`, `reset`); the registered function
+* value carries its own kind / args / handler.
+*
+* Users re-export from their own lunora module so codegen picks them up:
+*
+* ```ts
+* // lunora/ratelimit.ts
+* import { ratelimit } from "@vendor/ratelimit-component";
+* export const { check, reset } = ratelimit.functions;
+* // Emits as `ratelimit:check` / `ratelimit:reset` in the generated `api`.
+* ```
+*
+* Codegen follows the re-export back to the bundled `query/mutation/action`
+* call (property access or destructuring both work), so the functions land in
+* the generated `api` under the re-exporting file's namespace.
+*/
+type ComponentFunctions = Readonly<Record<string, RegisteredFunction<any, any, FunctionKind>>>;
+/**
+* Component = {@link Plugin} with a bundle of registered functions. The
+* extension + middleware + functions are independent: a component can ship
+* functions without a schema (e.g. a stateless utility), or a schema
+* without functions (e.g. shared table definitions), and any combination.
+*/
+interface Component<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn, F extends ComponentFunctions = ComponentFunctions> extends Plugin<TExtension, TContextIn, TContextOut> {
+  readonly functions: F;
+}
+interface DefineComponentOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut, F extends ComponentFunctions> extends DefinePluginOptions<TExtension, TContextIn, TContextOut> {
+  /** Registered functions the component ships. Keys are the function's local name. */
+  functions?: F;
+}
+/**
+* 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.
+*/
+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(...)`.
+*/
+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.
+*/
+declare const composePluginMiddleware: <ContextIn = unknown, const Plugins extends ReadonlyArray<Plugin<any, any, any>> = ReadonlyArray<Plugin<any, any, any>>>(plugins: Plugins) => Middleware<ContextIn, ComposedOut<Plugins> & ContextIn>;
+/** Options for `.vectorize(field, opts)` (DSL Shape A). */
+interface VectorizeOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  dimensions: number;
+  embed: VectorEmbedder;
+  /** Logical index name; must match a `[[vectorize]]` binding in wrangler. */
+  index: string;
+  /** Fields mirrored into Vectorize metadata for filtering. */
+  metadata?: ReadonlyArray<keyof Shape & string>;
+  metric: VectorMetric;
+}
+/** A `one` (many-to-one) relation descriptor; phantom `Target` carries the target table name. */
+interface OneRelation<Target extends string = string> extends RelationDefinition {
+  readonly __target?: Target;
+  readonly kind: "one";
+}
+/** A `many` (one-to-many) relation descriptor; phantom `Target` carries the target table name. */
+interface ManyRelation<Target extends string = string> extends RelationDefinition {
+  readonly __target?: Target;
+  readonly kind: "many";
+}
+/** The `r` argument passed to `.relations((r) => …)`. */
+interface RelationBuilder {
+  /** One-to-many: the FK `field` lives on the target table, matching this table's `references` (default `_id`). */
+  many: <Target extends string>(table: Target, options: {
+    field: string;
+    references?: string;
+  }) => ManyRelation<Target>;
+  /** Many-to-one: the FK `field` lives on this table, pointing at `table`.`references` (default `_id`). */
+  one: <Target extends string>(table: Target, options: {
+    field: string;
+    onDelete?: OnDeleteAction;
+    references?: string;
+  }) => OneRelation<Target>;
+}
+/**
+* Options for the inline `.aggregateIndex(name, opts)` builder. `op` defaults to
+* `count` so `aggregateIndex("byUser", { by: ["userId"] })` is a single-line
+* `COUNT(*) GROUP BY userId` accelerator.
+*/
+interface InlineAggregateIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  /** Group keys; counter rows are one per distinct tuple. Omitted = single-row aggregate over the whole table. */
+  by?: ReadonlyArray<keyof Shape & string>;
+  /** The column the reducer applies to. Required for `sum`/`min`/`max`/`avg`; ignored for `count`. */
+  field?: keyof Shape & string;
+  /** Reducer (default `count`). */
+  op?: AggregateOp;
+  /** Static predicate baked into the counter — only matching rows are aggregated. */
+  where?: Record<string, unknown>;
+}
+/**
+* Options for the inline `.rankIndex(name, opts)` builder. `sortBy` is required;
+* accepts either an array of `{ field, direction }` keys, or the shorthand
+* `["field"]` (asc) / `{ field: "desc" }` map entries. `partitionBy` scopes the
+* rank — omitted ⇒ one global rank over the whole table.
+*/
+interface InlineRankIndexOptions<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  /** Columns that scope each ranking; omitted ⇒ one global rank. */
+  partitionBy?: ReadonlyArray<keyof Shape & string>;
+  /** Ordered sort keys driving the rank. Required. */
+  sortBy: ReadonlyArray<{
+    direction?: "asc" | "desc";
+    field: keyof Shape & string;
+  }>;
+  /** Static predicate baked into the index; only matching rows enter. */
+  where?: Record<string, unknown>;
+}
+interface TableBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> extends TableDefinition<Shape> {
+  /** Declare an aggregate (counter/sum/…) maintained by triggers for O(1) reads. */
+  aggregateIndex: (name: string, options?: InlineAggregateIndexOptions<Shape>) => TableBuilder<Shape>;
+  /**
+  * Mark this table as written outside Lunora's discoverable insert path —
+  * by an adapter, a migration, or framework middleware (e.g. `@lunora/auth`'s
+  * better-auth tables, `@lunora/ratelimit`'s store). Advisor insert-path lints
+  * (`table_without_insert`) then skip it instead of flagging the absent
+  * `ctx.db.insert(...)`.
+  */
+  externallyManaged: () => TableBuilder<Shape>;
+  /**
+  * Mark this table as global (cross-shard). Backed by **D1** by default;
+  * pass `{ backend: "hyperdrive" }` to store it in a Postgres/MySQL database
+  * via Cloudflare Hyperdrive (PlanetScale, Neon, …) instead. Either way the
+  * table stays reactive — live queries re-run on write.
+  */
+  global: (options?: {
+    backend?: GlobalBackend;
+  }) => TableBuilder<Shape>;
+  /** Add a secondary index. */
+  index: (name: string, fields: ReadonlyArray<string>, options?: {
+    unique?: boolean;
+  }) => TableBuilder<Shape>;
+  /**
+  * Opt this table OUT of secure-by-default RLS. Under a schema marked
+  * `.rls("required")`, every table is protected (the write path denies raw,
+  * non-RLS `ctx.db` access); calling `.public()` exempts this one table so a
+  * plain `query`/`mutation` may read/write it without an RLS policy. No effect
+  * when the schema does not require RLS.
+  */
+  public: () => TableBuilder<Shape>;
+  /**
+  * Declare a rank index (sorted companion table, btree-backed) for
+  * `rank(row)` / `rankPage()` reads in O(log n). See {@link RankIndexDefinition}.
+  */
+  rankIndex: (name: string, options: InlineRankIndexOptions<Shape>) => TableBuilder<Shape>;
+  /** Declare relations to other tables, loaded via `findMany({ with })`. */
+  relations: (build: (r: RelationBuilder) => Record<string, RelationDefinition>) => TableBuilder<Shape>;
+  /** Add a search index over a field with optional filter fields. */
+  searchIndex: (name: string, options: {
+    field: string;
+    filterFields?: ReadonlyArray<string>;
+  }) => TableBuilder<Shape>;
+  /** Route storage by the named field — one DO per distinct value. */
+  shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+  * 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 vector index over a single text field on this table. */
+  vectorize: (field: keyof Shape & string, options: VectorizeOptions<Shape>) => TableBuilder<Shape>;
+}
+/** Options for `defineVectorIndex(...)` (DSL Shape B). */
+interface VectorIndexOptions {
+  dimensions: number;
+  embed: VectorEmbedder;
+  /** Optional projection of the source row into Vectorize metadata. */
+  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  metric: VectorMetric;
+  /** The vector source: which table, and how to derive the embedded text. */
+  source: {
+    select: (row: Record<string, unknown>) => string;
+    table: string;
+  };
+}
+/**
+* Build a table definition. Returned object is both the table definition (for
+* `defineSchema`) and a fluent builder for indexes + sharding metadata.
+*/
+declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
+/**
+* Declare a standalone vector index (DSL Shape B). Pass the returned value in
+* the `vectorIndexes` map of {@link defineSchema} when the source is derived
+* from multiple fields or a computation rather than a single column.
+*/
+declare const defineVectorIndex: (options: VectorIndexOptions) => VectorIndexDefinition;
+/**
+* Options for the standalone `defineAggregateIndex(name, opts)` helper (DSL
+* Shape B). Unlike the inline `.aggregateIndex(...)` builder, this form takes
+* the owning table explicitly via `on` — handy when a single counter wants to
+* live next to the schema map rather than inside a table chain.
+*/
+interface AggregateIndexOptions {
+  by?: ReadonlyArray<string>;
+  field?: string;
+  on: string;
+  op?: AggregateOp;
+  where?: Record<string, unknown>;
+}
+/**
+* Declare a standalone aggregate index. Pass the returned value to
+* `defineSchema(tables, vectorIndexes, aggregateIndexes)` keyed by index name —
+* the schema attaches it to `tables[on].aggregateIndexes` so runtime consumers
+* (DO + D1) read every index uniformly off the table definition.
+*/
+declare const defineAggregateIndex: (name: string, options: AggregateIndexOptions) => AggregateIndexDefinition;
+/**
+* Options for the standalone `defineRankIndex(name, opts)` helper (DSL Shape B).
+* Mirrors the inline `.rankIndex(...)` builder but takes the owning table via
+* `table` so it can sit next to the schema map.
+*/
+interface RankIndexOptions {
+  partitionBy?: ReadonlyArray<string>;
+  sortBy: ReadonlyArray<{
+    direction?: "asc" | "desc";
+    field: string;
+  }>;
+  table: string;
+  where?: Record<string, unknown>;
+}
+/**
+* Declare a standalone rank index. Pass the returned value to
+* `defineSchema(tables, vectorIndexes, aggregateIndexes, rankIndexes)` keyed
+* by index name — the schema attaches it to `tables[on].rankIndexes`.
+*/
+declare const defineRankIndex: (name: string, options: RankIndexOptions) => RankIndexDefinition;
+/**
+* Build the application schema. The first argument is the table map; the
+* optional second argument registers standalone `defineVectorIndex(...)`
+* declarations (DSL Shape B) keyed by index name. The optional third argument
+* registers standalone `defineAggregateIndex(...)` declarations (DSL Shape B);
+* the optional fourth argument registers standalone `defineRankIndex(...)`
+* declarations. Both are folded into the matching `tables[on].*Indexes` array
+* so runtime backends read every index uniformly off the table definition.
+*/
+/**
+* Schema with an in-place `.extend(plugin.extension)` method. Used so apps
+* can compose plugin schemas: `defineSchema({...}).extend(authPlugin.extension)`.
+*
+* `extend` is non-mutating — returns a fresh `ExtendableSchema` containing
+* the merged tables. Extension tables are auto-namespaced by the extension
+* `key` (`buckets` → `ratelimit_buckets`), so the merged type carries the
+* prefixed names via {@link PrefixedTables}. Chains:
+* `defineSchema(...).extend(a).extend(b)` is the typed equivalent of merging
+* `a`'s prefixed tables then `b`'s.
+*/
+type ExtendableSchema<T extends Record<string, TableDefinition>> = {
+  extend: <X extends Record<string, TableDefinition>, Key extends string>(extension: SchemaExtension<X> & {
+    readonly key: Key;
+  }) => ExtendableSchema<PrefixedTables<X, Key> & T>;
+  /**
+  * Pin every Durable Object the app reaches — shards, fan-out, subscriptions,
+  * the scheduler, and `ctx.containers` — to a Cloudflare data-residency
+  * jurisdiction (`"eu"`, `"us"`, `"fedramp"`). Codegen reads this off the
+  * schema and emits it into the generated worker's `createWorker({ jurisdiction })`
+  * (and `ctx.scheduler` / `ctx.containers`). Non-mutating: returns a fresh
+  * `ExtendableSchema`, so it composes with `.rls(...)` / `.extend(...)` in any order.
+  *
+  * ⚠️ **Set this once, before your first deploy — changing or removing it
+  * strands data.** A Durable Object name maps to a *different* ID in each
+  * jurisdiction, so toggling this on an existing app makes every shard, scheduler
+  * job, and session DO resolve to a NEW, empty DO; the previous data stays in the
+  * old jurisdiction's DOs and is no longer reachable. There is no in-place
+  * migration — you would have to export from the old jurisdiction and import
+  * into the new one.
+  *
+  * Note: this pins **DO-backed** state only. D1-backed state — `.global()`
+  * tables and `@lunora/auth` sessions alike — is governed by D1's own location
+  * settings, not this option.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction: (jurisdiction: DurableObjectJurisdiction) => ExtendableSchema<T>;
+  /**
+  * Turn on secure-by-default RLS for the whole schema. Every table is then
+  * protected — the DO/D1 write path denies raw, non-RLS `ctx.db` access, so a
+  * procedure that forgets `.use(rls(...))` fails closed. Opt a table out with
+  * `.public()`. Non-mutating: returns a fresh `ExtendableSchema` carrying the
+  * mode, so `.rls("required")` composes with `.extend(...)` either order.
+  */
+  rls: (mode: "required") => ExtendableSchema<T>;
+} & Schema<T>;
+declare const defineSchema: <T extends Record<string, TableDefinition>>(tables: T, vectorIndexes?: Record<string, VectorIndexDefinition>, aggregateIndexes?: Record<string, AggregateIndexDefinition>, rankIndexes?: Record<string, RankIndexDefinition>) => ExtendableSchema<T>;
+/** Default 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.
+*/
+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).
+*/
+interface PresenceMember {
+  /** Opaque awareness blob (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** Last heartbeat time (epoch ms). */
+  lastSeen: number;
+  /** The room / channel / document this presence is scoped to. */
+  roomId: string;
+  /** Authenticated user id, when known. */
+  userId?: string;
+}
+/** 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`.
+  */
+  disconnectGraceMs?: number;
+  /**
+  * How long (ms) a heartbeat keeps a member present. `listPresent` excludes
+  * rows whose `lastSeen` is older than `now - ttlMs`. Defaults to 30s.
+  */
+  ttlMs?: number;
+}
+/** The registered functions a presence component ships. */
+interface PresenceFunctions {
+  /**
+  * Connection-lifecycle hook: the instant a client's WebSocket drops, hard-
+  * delete its presence row so it disappears from `listPresent` with no TTL
+  * lag. Targets the row by the `{ roomId, sessionId }` the client passed as
+  * the connection `context`, and only deletes it when the disconnecting
+  * VERIFIED identity owns the row (so a forged context can't evict another
+  * member). The TTL filter + `sweep` remain the fallback for ungraceful drops
+  * where no `context` was recorded.
+  */
+  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`.
+  */
+  heartbeat: RegisteredMutation<{
+    data: ReturnType<typeof v.optional>;
+    roomId: ReturnType<typeof v.string>;
+    sessionId: ReturnType<typeof v.string>;
+  }, {
+    lastSeen: number;
+  }>;
+  /**
+  * 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.
+  */
+  sweep: RegisteredMutation<{
+    roomId: ReturnType<typeof v.string>;
+  }, {
+    deleted: number;
+  }>;
+}
+/** The component shape `definePresence` returns: the presence extension + typed functions. */
+type PresenceComponent = Component<{
+  [PRESENCE_BARE_TABLE]: ReturnType<typeof defineTable>;
+}> & {
+  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`.
+*/
+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).
+*/
+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.
+  */
+  captcha?: Middleware<Context, Context>;
+  /**
+  * 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.
+*/
+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.
+*/
+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.
+*/
+declare const definePolicies: <Context = unknown>(policies: ReadonlyArray<Policy<Context>>) => ReadonlyArray<Policy<Context>>;
+declare const defineRole: (name: string, options?: Omit<Role, "name">) => Role;
+/**
+* Structural mirror of `@lunora/do`'s `QueryArgs` and `CountArgs`. The
+* runtime ORM in `@lunora/do`/`@lunora/d1` reads `baseWhere` /
+* `restrictsCounts` straight off these option objects, so as long as the
+* fields here stay name-compatible the wrapper is portable across the two
+* dialects without an inter-package dependency.
+*/
+interface QueryArgs {
+  baseWhere?: WhereInput;
+  cursor?: null | string;
+  limit?: number;
+  orderBy?: ReadonlyArray<unknown>;
+  /**
+  * Per-target-table read filter the RLS wrapper attaches so a `with` relation
+  * is policy-filtered on its own hop (see `@lunora/do`'s `QueryArgs`). Mirrors
+  * the top-level read: `(table) => readBase(table).baseWhere`.
+  */
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+  with?: Record<string, unknown>;
+}
+interface CountArgs {
+  baseWhere?: WhereInput;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `AggregateOptions` — only the fields the wrapper touches. */
+interface AggregateArgs {
+  baseWhere?: WhereInput;
+  field?: string;
+  op: string;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `GroupByOptions`. */
+interface GroupByArgs {
+  agg?: {
+    field?: string;
+    op: string;
+  };
+  baseWhere?: WhereInput;
+  by: ReadonlyArray<string>;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankOptions`. */
+interface RankArgs {
+  baseWhere?: WhereInput;
+  restrictsCounts?: boolean;
+  row: Record<string, unknown> | string;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankBeforeOptions`. */
+interface RankBeforeArgs {
+  partitionKey: string;
+  restrictsCounts?: boolean;
+  rowId: string;
+  sortValues: ReadonlyArray<unknown>;
+}
+/** Structural mirror of `@lunora/do`'s `RankPageOptions`. */
+interface RankPageArgs {
+  baseWhere?: WhereInput;
+  cursor?: null | string;
+  restrictsCounts?: boolean;
+  take?: number;
+  where?: WhereInput;
+}
+interface QueryPage {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
+}
+interface TableReaderLike {
+  collect: () => Promise<Record<string, unknown>[]>;
+  filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike;
+  first: () => Promise<Record<string, unknown> | null>;
+  paginate: (options: {
+    cursor?: null | string;
+    numItems: number;
+  }) => Promise<QueryPage>;
+  take: (limit: number) => Promise<Record<string, unknown>[]>;
+  withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike;
+}
+/**
+* Structural projection of the runtime ORM writer. The wrapper relies only
+* on these fields, so it's interchangeable between `@lunora/do`'s
+* `DatabaseWriterLike` and `@lunora/d1`'s `DatabaseWriterLike`.
+*/
+interface DatabaseWriterLike {
+  /**
+  * 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>;
+  deleteMany: (ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }, expectedTable?: string) => Promise<{
+    deleted: number;
+  }>;
+  findFirst: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown> | null>;
+  findFirstOrThrow: (tableName: string, args?: QueryArgs) => Promise<Record<string, unknown>>;
+  findMany: (tableName: string, args?: QueryArgs) => Promise<QueryPage>;
+  get: (id: string, expectedTable?: string) => Promise<Record<string, unknown> | null>;
+  /**
+  * Group + reduce. Same `baseWhere` injection as `aggregate`: the per-group
+  * reduction is scoped to policy-visible rows, so a group count tallies only
+  * rows the caller may read. Required for the same reason as `aggregate`.
+  */
+  groupBy: (tableName: string, options: GroupByArgs) => Promise<ReadonlyArray<{
+    key: Record<string, unknown>;
+    value: null | number;
+  }>>;
+  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
+  insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+  }) => Promise<string[]>;
+  insertManyUnsafe: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    allowExplicitId?: boolean;
+    limit?: number;
+  }) => Promise<string[]>;
+  /**
+  * Optional table-aware lookup. The underlying writer (e.g. `@lunora/do`)
+  * already knows the owning table of an id internally, so it can return
+  * `{ row, tableName }` in a single round-trip. When present, the RLS wrapper
+  * uses it to collapse the per-call membership-probe fan-out (1 `get` + N
+  * `findFirst` across every policy table) down to one lookup. Writers that
+  * don't implement it fall back to the probe path.
+  */
+  lookupById?: (id: string, expectedTable?: string) => Promise<null | {
+    row: Record<string, unknown>;
+    tableName: string;
+  }>;
+  patch: (id: string, patch: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  patchMany: (patches: ReadonlyArray<{
+    id: string;
+    patch: Record<string, unknown>;
+  }>, options?: {
+    limit?: number;
+  }, expectedTable?: string) => Promise<void>;
+  query: (tableName: string) => TableReaderLike;
+  /**
+  * Rank a row within its partition. A position is a count-of-rows-before, so
+  * — exactly like `count()` — it can't be trusted in an RLS-restricted
+  * reader: the wrapper fails it closed with `COUNT_RLS_UNSUPPORTED`. Required
+  * for the same reason as `aggregate`.
+  */
+  rank: (tableName: string, indexName: string, options: RankArgs) => Promise<null | {
+    position: number;
+    total: number;
+  }>;
+  /** Cross-shard rank primitive — same count-of-before RLS hazard as `rank`; failed closed under a read policy. */
+  rankBefore?: (tableName: string, indexName: string, options: RankBeforeArgs) => Promise<{
+    before: number;
+    total: number;
+  }>;
+  /**
+  * Sorted pagination over a rank companion. The companion stores only the
+  * partition + sort keys + id, so an arbitrary read `baseWhere` can't be
+  * enforced against it (and re-filtering the fetched rows would break page
+  * sizing). RLS therefore fails it closed rather than leak hidden rows.
+  * Required for the same reason as `aggregate`.
+  */
+  rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage>;
+  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
+}
+/**
+* What a procedure's `ctx.db` must structurally satisfy for the middleware
+* to wrap it. We deliberately mirror `@lunora/do`'s `DatabaseWriterLike`
+* rather than `@lunora/server`'s nominal `DatabaseWriter`/`DatabaseReader`:
+* the runtime adapter that flows in is the `DatabaseWriterLike`-shaped one,
+* and structural matching keeps this module free of an `@lunora/do`-typed
+* `ctx`.
+*/
+type RlsDatabase = DatabaseWriterLike;
+/** Roles list source on the context. Tolerant of older auth states. */
+type AuthLike = {
+  getIdentity?: () => Promise<Record<string, unknown> | null>;
+  roles?: ReadonlyArray<string>;
+  userId?: null | string;
+};
+/** Minimal shape the middleware needs on the incoming ctx. */
+interface RlsContextIn {
+  auth?: AuthLike;
+  db: RlsDatabase;
+}
+declare const rls: <Context extends RlsContextIn = RlsContextIn>(policies: ReadonlyArray<Policy<Context>>, options?: RlsOptions) => Middleware<Context, Context>;
+/**
+* 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>;
+  /** 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`).
+  */
+  readonly where: (context: Context, args: InferValidatorMap<Args>) => WhereInput;
+}
+/** 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 `where` 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.
+  */
+  readonly compileWhere: (context: unknown, rawArgs: Record<string, unknown>) => 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.
+*/
+interface StorageRuleContext<Context = unknown> {
+  readonly auth: {
+    readonly can: (permission: Permission | string) => boolean;
+    readonly identity?: Record<string, unknown> | null;
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
+  };
+  readonly ctx: Context;
+  /** The object key the operation targets (the listing prefix for `list`). */
+  readonly key: string;
+}
+/** 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.
+  */
+  readonly bucket: string;
+  readonly on: StorageOperation;
+  /** Optional key-prefix scope; the rule only governs keys under it. Absent ⇒ the whole bucket. */
+  readonly prefix?: string;
+  readonly when: (context: StorageRuleContext<Context>) => StorageRuleDecision;
+}
+/** Input accepted by `defineStorageRule`. The result is the same shape. */
+interface DefineStorageRuleInput<Context = unknown> {
+  bucket: string;
+  on: StorageOperation;
+  prefix?: string;
+  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.
+*/
+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.
+*/
+declare const defineStorageRules: <Context = unknown>(rules: ReadonlyArray<StorageRule<Context>>) => ReadonlyArray<StorageRule<Context>>;
+/** The minimal `ctx.auth` shape the middleware reads — a structural subset that the full AuthState satisfies. Tolerant of older auth states (mirrors RLS's `AuthLike`). */
+type StorageAuthLike = {
+  getIdentity?: () => Promise<Record<string, unknown> | null>;
+  roles?: ReadonlyArray<string>;
+  userId?: null | string;
+};
+interface StorageContextIn {
+  auth?: StorageAuthLike;
+  storage?: unknown;
+}
+declare const storageRules: <Context extends StorageContextIn = StorageContextIn>(rules: ReadonlyArray<StorageRule<Context>>, options?: StorageRulesOptions) => Middleware<Context, Context>;
+declare const VERSION = "0.0.0";
+export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, type DataModelInit, type DefineComponentOptions, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type 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 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, asBucketStorage, bindOrm, bindTableFacade, buildRlsReadRegistry, composePluginMiddleware, composeShapeReadWhere, createPolicyDsl, createSecrets, defineAggregateIndex, defineComponent, defineEnv, defineMigration, defineMutator, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineShape, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, httpAction, httpRoute, httpRouter, initLunora, installPlugins, mask, mergeSchemaExtension, onConnect, onDisconnect, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules };