@lunora/server 1.0.0-alpha.84 → 1.0.0-alpha.85

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Validator, Infer, ValidatorMap, InferValidatorMap, ColumnValidator, v } from '@lunora/values';
+import { Validator, Infer, v, ValidatorMap, InferValidatorMap, ColumnValidator } from '@lunora/values';
 export { type ColumnValidator, type GeoPoint, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
-import { ArgsValidator, InferArgs, RegisteredAction, ExposeConfig, X402ProcedureConfig, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, DurableStreamOptions, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, ShardInitEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, SearchLanguage, SearchStrategy, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
+import { ArgsValidator, InferArgs, RegisteredAction, ExposeConfig, X402ProcedureConfig, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, DurableStreamOptions, RegisteredStream, FunctionKind, Secrets, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, GlobalBackend, RelationDefinition, OnDeleteAction, SearchLanguage, SearchStrategy, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, DurableObjectJurisdiction, AggregateIndexDefinition, RankIndexDefinition, LifecycleEvent, ShardInitEvent, RegisteredLifecycleHook } from "./types.mjs";
 export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type GeoBoundingBox, type GeoFilterBuilder, type GeoIndexDefinition, type GeoPointInput, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type LunoraWideEvent, type MutationStorage, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type RestCacheConfig, type RunQueryOptions, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type SpanEvaluation, type SpanHandle, type SpanKind, type SpanLink, type SpanOptions, type Storage, type StorageMetadata, type StorageObjectHead, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type TtlDefinition, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowEventDefinition, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
 import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
 export type { LunoraErrorCode } from '@lunora/errors';
@@ -351,1657 +351,1763 @@ interface DeferredDeleteFlushResult {
  */
 declare const flushDeferredDeletes: (context: unknown) => Promise<DeferredDeleteFlushResult>;
 /**
- * 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.
+ * 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.
  */
-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;
-}
+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>;
 /**
- * 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.
+ * 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.
  */
-declare class LunoraEnvError extends LunoraError$1 {
-  readonly failures: ReadonlyArray<EnvKeyFailure>;
-  constructor(failures: ReadonlyArray<EnvKeyFailure>);
+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.<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>;
 }
-/** 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.
+ * Build a {@link SchemaExtension}. The `key` is a runtime tag (used for
+ * error messages on collision) and a type-level brand.
  */
-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]>; };
+declare const defineSchemaExtension: <T extends Record<string, TableDefinition>>(key: string, options: {
+  tables: T;
+  vectorIndexes?: Record<string, VectorIndexDefinition>;
+}) => SchemaExtension<T>;
 /**
- * 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);`.
+ * 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 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>;
+interface Plugin<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn> {
+  /**
+   * Optional schema extension. Apps install via
+   * `defineSchema(...).extend(plugin.extension)`.
+   */
+  readonly extension?: SchemaExtension<TExtension>;
+  /** Stable key identifying the plugin. Matches `extension.key` when set. */
+  readonly key: string;
+  /**
+   * Optional middleware. Users attach with `c.query.use(plugin.middleware)`.
+   * The middleware can extend `ctx`; convention is to attach helpers under
+   * `ctx.api.<key>`, e.g.
+   *
+   * ```ts
+   * middleware: ({ ctx, next }) =>
+   *     next({ ctx: { api: { ...ctx.api, ratelimit: api } } })
+   * ```
+   */
+  readonly middleware?: Middleware<TContextIn, TContextOut>;
+}
+/** Options to {@link definePlugin}. */
+interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut> {
+  extension?: SchemaExtension<TExtension>;
+  middleware?: Middleware<TContextIn, TContextOut>;
 }
 /**
- * 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.
+ * Call signatures for {@link definePlugin}. When `extension` is supplied the
+ * returned plugin's `extension` is typed as PRESENT (not `?`), so the
+ * canonical install pattern `defineSchema(...).extend(plugin.extension)`
+ * typechecks without a non-null assertion — the shape every scaffold template
+ * ships. The bare-options signature keeps `extension` optional for plugins
+ * that carry only middleware.
+ */
+interface DefinePluginFunction {
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut> & {
+    extension: SchemaExtension<TExtension>;
+  }): Plugin<TExtension, TContextIn, TContextOut> & {
+    readonly extension: SchemaExtension<TExtension>;
+  };
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>): Plugin<TExtension, TContextIn, TContextOut>;
+}
+/**
+ * Package a schema extension + middleware as a reusable plugin. Either
+ * field is optional — `definePlugin("foo", {})` is valid but degenerate.
+ */
+declare const definePlugin: DefinePluginFunction;
+/**
+ * Bundle of registered functions a {@link Component} ships. Keys are the
+ * function's local name (e.g. `check`, `reset`); the registered function
+ * value carries its own kind / args / handler.
+ *
+ * Users re-export from their own lunora module so codegen picks them up:
  *
  * ```ts
- * import { defineEnv, v } from "@lunora/server";
+ * // 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`.
+ * ```
  *
- * const config = defineEnv({
- *     STRIPE_KEY: v.string(),
- *     PORT: v.optional(v.number()),
- * });
+ * 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:
  *
- * export default {
- *     fetch(request, env) {
- *         const { STRIPE_KEY, PORT } = config(env); // STRIPE_KEY: string, PORT?: number
- *         // …
+ * ```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 }) => ...),
  *     },
- * };
+ * });
  * ```
  *
- * 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)`.
+ * 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 defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
-declare class LunoraError extends LunoraError$1 {
-  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
-}
+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>;
 /**
- * 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.
+ * 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.
  */
-interface FacadeWriterLike {
-  aggregate(tableName: string, options: unknown): Promise<unknown>;
-  count(tableName: string, where?: unknown): Promise<number>;
-  delete(id: string, expectedTable?: string, options?: {
-    hard?: boolean;
-  }): Promise<void>;
-  deleteMany?(ids: ReadonlyArray<string>, options?: {
-    limit?: number;
-  }, expectedTable?: string): Promise<{
-    deleted: number;
-  }>;
-  deleteWhere?(tableName: string, where: Record<string, unknown>, options?: {
-    limit?: number;
-  }): Promise<{
-    deleted: number;
-  }>;
-  findFirst(tableName: string, args?: unknown): Promise<unknown>;
-  findFirstOrThrow(tableName: string, args?: unknown): Promise<unknown>;
-  findMany(tableName: string, args?: unknown): Promise<unknown>;
-  get(id: string, expectedTable?: string): Promise<unknown>;
-  groupBy(tableName: string, options: unknown): Promise<unknown>;
-  insert(tableName: string, document: Record<string, unknown>): Promise<string>;
-  insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    limit?: number;
-    skipDuplicates?: boolean;
-  }): Promise<(string | null)[]>;
-  patch(id: string, patch: Record<string, unknown>, expectedTable?: string): Promise<void>;
-  patchMany?(patches: ReadonlyArray<{
-    id: string;
-    patch: Record<string, unknown>;
-  }>, options?: {
-    limit?: number;
-  }, expectedTable?: string): Promise<{
-    patched: number;
-  }>;
-  patchWhere?(tableName: string, args: {
-    patch: Record<string, unknown>;
-    where: Record<string, unknown>;
-  }, options?: {
-    limit?: number;
-  }): Promise<{
-    patched: number;
-  }>;
-  query(tableName: string): {
-    withGeoIndex(indexName: string, build: (q: unknown) => unknown): unknown;
-    withSearchIndex(indexName: string, search: (q: unknown) => unknown): unknown;
-  };
-  rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
-  rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
-  replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
-  restore?(id: string, expectedTable?: string): Promise<void>;
-}
-/** The per-table accessor object returned for the `ctx.db` table form. */
-interface FacadeEntry {
-  aggregate: (options: unknown) => Promise<unknown>;
-  count: (where?: unknown) => Promise<number>;
-  delete: (id: string) => Promise<void>;
-  deleteMany: {
-    (ids: ReadonlyArray<string>, options?: {
-      limit?: number;
-    }): Promise<{
-      deleted: number;
-    }>;
-    (args: {
-      limit?: number;
-      where: Record<string, unknown>;
-    }): Promise<{
-      deleted: number;
-    }>;
-  };
-  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
-  exists: (where?: unknown) => Promise<boolean>;
-  findFirst: (args?: unknown) => Promise<unknown>;
-  findFirstOrThrow: (args?: unknown) => Promise<unknown>;
-  findMany: (args?: unknown) => Promise<unknown>;
-  get: (id: string) => Promise<unknown>;
-  groupBy: (options: unknown) => Promise<unknown>;
-  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
-  hardDelete: (id: string) => Promise<void>;
-  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
-  /**
-   * Insert many documents into this table in one call. With
-   * `{ skipDuplicates: true }`, UNIQUE breaches resolve to `null` for that row
-   * instead of failing the batch. The typed facade narrows the return to
-   * `Id<T>[]` when skipDuplicates is not requested.
-   */
-  insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
-    limit?: number;
-    skipDuplicates?: boolean;
-  }) => Promise<(string | null)[]>;
-  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
-  patchMany: {
-    (patches: ReadonlyArray<{
-      id: string;
-      values: Record<string, unknown>;
-    }>, options?: {
-      limit?: number;
-    }): Promise<{
-      patched: number;
-    }>;
-    (args: {
-      limit?: number;
-      values: Record<string, unknown>;
-      where: Record<string, unknown>;
-    }): Promise<{
-      patched: number;
-    }>;
-  };
-  rank: (indexName: string, options: unknown) => Promise<unknown>;
-  rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
-  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
-  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
-  restore: (id: string) => Promise<void>;
-  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
-  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
-  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
-  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
-  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => unknown;
-  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
-}
-/** Options accepted by the per-table `insert` accessor. */
-interface FacadeInsertOptions {
-  /**
-   * When `true`, a UNIQUE-constraint breach is swallowed: the insert becomes a
-   * silent no-op and resolves to `null` instead of throwing a `CONFLICT`. Any
-   * other error still propagates. Mirrors better-drizzle's `create({ skipDuplicates })`.
-   */
-  skipDuplicates?: boolean;
-}
-/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
-type UpsertTarget = ReadonlyArray<string> | string;
-/** Argument to the per-table `upsert` accessor. */
-interface UpsertArgs {
-  /** Document inserted when no existing row matches the `target`. */
-  create: Record<string, unknown>;
-  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
-  target: UpsertTarget;
-  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
-  update?: Record<string, unknown>;
-}
-/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
-interface UpsertResult {
-  created: boolean;
-  id: string;
-}
-/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
-interface UpsertManyArgs {
-  rows: ReadonlyArray<{
-    create: Record<string, unknown>;
-    update?: Record<string, unknown>;
-  }>;
-  target: UpsertTarget;
-}
+type PrefixedTables<X extends Record<string, TableDefinition>, Key extends string> = { [K in keyof X as K extends string ? `${Key}_${K}` : K]: X[K]; };
 /**
- * Bind a structural writer to one table, producing its `ctx.db` table accessor.
+ * Merge a {@link SchemaExtension} into an existing schema. Returns a new
+ * schema object — never mutates the input.
  *
- * The by-id accessors (`get`/`delete`/`patch`/`replace`) forward the bound
- * `tableName` as `expectedTable` so the underlying writer scopes its id lookup
- * to this table. Without it, a branded `Id<"posts">` carrying another table's
- * id would resolve cross-table (the writer probes every table by id), letting
- * `ctx.db.posts.get(foreignId)` read — or `.delete`/`.patch`/`.replace`
- * mutate — a row in an unrelated table (IDOR). Writers that ignore the second
- * argument keep their previous global behaviour; the scoping is opt-in via this
- * forwarded name.
- */
-declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) => FacadeEntry;
-/** The kitcn-style `ctx.orm` namespace over a per-table facade map. */
-interface OrmLike {
-  delete: (table: string, id: string) => Promise<void>;
-  insert: (table: string) => {
-    values: (document: Record<string, unknown>) => Promise<null | string>;
-  };
-  query: Record<string, FacadeEntry>;
-  replace: (table: string, id: string) => {
-    with: (document: Record<string, unknown>) => Promise<void>;
-  };
-  update: (table: string, id: string) => {
-    set: (values: Record<string, unknown>) => Promise<void>;
-  };
-}
-/** Build `ctx.orm` over a per-table facade map (table name → FacadeEntry). */
-declare const bindOrm: (facade: Record<string, FacadeEntry>) => OrmLike;
-/** HTTP verbs the typed {@link httpRoute} builder can bind to. */
-type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
-/**
- * Context handed to an HTTP action handler. A narrower view of {@link ActionContext}:
- * HTTP actions run in the worker (the "action runtime"), separate from the
- * transactional store, so there is no direct `db` / `vectors` surface — reach the
- * data layer through `runQuery` / `runMutation` / `runAction`, which forward to
- * the owning shard. `db`'s absence is principled: an HTTP handler is not
- * transactional.
+ * 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.
  *
- * `scheduler` and `storage` ARE present, because neither needs the shard — the
- * scheduler talks to the scheduler DO, and R2 is a worker binding an HTTP
- * handler can reach where an action does. Both are optional: each exists only
- * when the app declared the matching capability (`.scheduler(...)` /
- * `.storage(...)`) on the generated app builder.
+ * 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.
  *
- * Omitting them was costly out of proportion to the gap. Without `scheduler`,
- * "receive webhook → enqueue the real work → return 200" — the shape HTTP
- * actions exist for — forced a hop through a mutation plus a closed allow-list
- * of target strings, because a function reference cannot cross the RPC boundary
- * and a free-form target on an unauthenticated endpoint is a "call any internal
- * function" primitive. Without `storage`, any helper the ctx was threaded into
- * had to be typed for its storage-touching branch, so a handler was barred from
- * the helper even on the branches that never went near storage.
- */
-type HttpActionCtx = Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery"> & {
-  readonly scheduler?: ActionCtx["scheduler"];
-  readonly storage?: ActionCtx["storage"];
-};
-/** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
-type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
-/**
- * The hono {@link https://hono.dev | Hono} environment used by {@link httpRouter}.
- * The runtime injects the per-request {@link HttpActionCtx} on the private
- * `__lunoraCtx` binding; the router's lifting middleware promotes it to
- * `c.var.lunora` so handlers can read it as a typed variable.
- */
-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`.
+ * Re-runs {@link validateIndexFields} against the merged table set before
+ * returning: `defineSchema` only validates the tables it was called with, so
+ * without this an extension-contributed index with a typo'd/out-of-shape
+ * field (or a duplicate name within one kind) would never be checked at all.
+ * Re-validating the whole merged set (base + prefixed extension tables) is
+ * cheap and idempotent for the base tables, which already passed this same
+ * check when the base schema was built. Both callers of this function —
+ * `withExtend.extend()` (`./schema`) and `installPlugins` (below) — get the
+ * re-validation for free from this single call site (plan 258 §4/§9 Q3).
  */
-declare const httpAction: (handler: HttpActionHandler) => LunoraRouteHandler;
+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>;
 /**
- * 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`:
+ * 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 app = httpRouter();
- * app.use("*", cors());
- * app.post("/webhook", httpAction(onWebhook));
- * app.get("/users/:id", getUser);
- * export default createWorker({ httpRouter: app, ... });
+ * const schema = installPlugins(defineSchema({ todos }), [ratelimit, audit]);
+ * // → todos + ratelimit_* + audit_*
  * ```
  *
- * 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.
+ * 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 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>;
-}
+declare const installPlugins: <T extends Record<string, TableDefinition>, const Plugins extends ReadonlyArray<Plugin<any, any, any>>>(base: Schema<T>, plugins: Plugins) => Schema<InstalledTables<T, Plugins>>;
 /**
- * The `{ ctx, searchParams, params, request, signal }` a streaming HTTP
- * handler receives. There is no parsed `body` — streams are typically GET, and
- * the raw `request` is exposed if a handler needs to read the body itself.
- * `signal` is tripped when the client disconnects.
- * @experimental Part of the HTTP-SSE stream surface; reconnect/POST-body design questions are still open.
- */
-interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
-  ctx: HttpActionCtx;
-  params: InferArgs<Params>;
-  request: Request;
-  searchParams: InferArgs<SearchParams>;
-  signal: AbortSignal;
-}
-/**
- * A typed REST route under construction. `.searchParams()` / `.body()` /
- * `.params()` accumulate validator maps (later calls merge, a colliding key
- * wins) that decode the URL query, JSON body, and hono path params into the
- * handler's typed `searchParams` / `body` / `params`. Like the procedure
- * builder, `.output(validator)` defaults to the `undefined` sentinel — while
- * unset the handler is generic over its own return; once set the handler must
- * return that type and the result is parsed through the validator before
- * serialization. `[Output] extends [undefined]` is tuple-wrapped so a union
- * `Output` doesn't distribute and the test is for the exact sentinel.
+ * Compose every plugin's middleware into a single middleware you attach with one
+ * `.use(...)`. Plugins without middleware (schema-only) are skipped; the rest run
+ * in array order, each seeing the context the previous one widened, so the final
+ * `next({ ctx })` the builder receives carries every plugin's `ctx.api.<key>`
+ * additions. Equivalent to `.use(a.middleware).use(b.middleware)…` but as one
+ * value, the middleware sibling of {@link installPlugins}.
  *
- * The terminal `.handler()` yields a {@link LunoraRouteHandler} — mount it
- * directly with `app.get(path, route)`.
+ * `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.
  */
-interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
-  body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
-  /**
-   * Attach a `Cache-Control` header to the response. Only meaningful when
-   * Workers Cache is enabled in `wrangler.jsonc` (`"cache": { "enabled": true }`).
-   */
-  cacheControl: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
-  /**
-   * Attach a `Cache-Tag` header to the response for tag-based purging via
-   * `ctx.cache.purge({ tags: [...] })`.
-   */
-  cacheTag: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
-  handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
-  output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
-  params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
-  searchParams: <S extends ArgsValidator>(validators: S) => HttpRouteBuilder<S & SearchParams, Body, Params, Output>;
-  /**
-   * Terminal: declare this route as a streaming Server-Sent Events endpoint.
-   * The handler is an async generator (or any function returning an
-   * `AsyncIterable<R>`) that yields one chunk per SSE `data:` frame; on
-   * iterator completion the route writes a final `event: complete` frame; on
-   * throw, an `event: error` frame is written with `{code, message}` before
-   * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
-   * handler's yielded type.
-   * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
-   */
-  stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
-  /**
-   * Attach a `Vary` header to the response so Cloudflare stores separate
-   * cached variants per distinct value of the listed request headers.
-   */
-  vary: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+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;
 }
-/** 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;
+/** 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";
 }
-/**
- * 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;
+/** 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";
 }
-/** Byte window forwarded to `download()` so R2 streams just the requested slice. */
-interface StorageRange {
-  length: number;
-  offset: number;
+/** 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>;
 }
 /**
- * The minimal storage surface {@link serveStorageObject} needs: a metadata-rich
- * `download`, plus the body-free `head` a range request resolves against.
- *
- * `head` is required rather than optional-with-a-fallback because the fallback
- * is the bug: without it a ranged request has to start a full-object `download`
- * just to learn the size, then throw that body away. `@lunora/storage`'s `head`
- * already degrades internally to a 0-length ranged `get()` on a binding with no
- * HEAD, so there is nothing a caller here could usefully do that it does not.
+ * 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 StorageHead {
-  /** Object metadata with no body. `size` is the FULL object size (mirrors R2). */
-  head: (key: string) => Promise<Omit<StorageObjectBody, "body"> | null>;
-}
-/** The storage surface {@link serveStorageObject} reads through. */
-interface StorageDownloader extends StorageHead {
-  download: (key: string, options?: {
-    range?: StorageRange;
-  }) => Promise<StorageObjectBody | null>;
-}
-/** Any ctx that carries a {@link StorageDownloader} on `.storage` (Query/Mutation/Action ctx all do). */
-interface ContextWithStorage {
-  storage: StorageDownloader;
+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>;
 }
 /**
- * True when `value` is safe to use as an HTTP header field-value: no CR, LF, or
- * NUL. Guards against response-header injection / `Headers`-construction throws
- * when reflecting attacker-influenced object metadata (e.g. a stored
- * `Content-Type`). Exported (see the `export {}` at the file end) so an `httpAction`
- * handler can guard a request-derived header value before writing it — the fix the
- * `http_action_response_header_injection` advisor lint points to.
- */
-declare const isSafeHeaderValue: (value: string) => boolean;
-/**
- * Stream a stored object as an HTTP {@link Response} from an `httpAction`
- * handler, with correct `Content-Type`, `ETag`, and `Accept-Ranges: bytes`.
- * Honors a single-range `Range` request → **206 Partial Content** with
- * `Content-Range` + `Content-Length`; otherwise **200**. A missing object is a
- * **404**; an out-of-bounds range is a **416** with a `Content-Range` of
- * `bytes` star-slash-size.
- *
- * A range request resolves its window against a body-free `head()`, then issues
- * ONE `download()` with the resolved `{ offset, length }` so R2 streams just
- * those bytes — the slice is never buffered in the isolate, and no full-object
- * body transfer is started only to be cancelled. A request that cannot produce a
- * 206 at all (no `Range`, multi-range, malformed) skips the `head()` entirely and
- * streams straight from a single `download()`. For very
- * large objects a signed URL (`ctx.storage.getSignedUrl`) is still cheaper since
- * the client then ranges against R2/CDN directly with no Worker hop.
- */
-declare const serveStorageObject: (context: ContextWithStorage, key: string, request: Request) => Promise<Response>;
-/**
- * What the worker does with a resolver's identity when it fails contract
- * validation (a forged / malformed claim set arriving from an untrusted token).
- * `"anonymous"` (default, safe) treats the request as anonymous, so the bad
- * identity never reaches a policy as a valid identity (`ctx.auth.userId`
- * becomes `undefined`). `"reject"` fails the request closed (a `401`) — use
- * when a malformed credential should be a hard error, not a silent downgrade.
+ * 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.
  */
-type IdentityRejectMode = "anonymous" | "reject";
-/** Options for {@link defineIdentity}. */
-interface DefineIdentityOptions {
-  /**
-   * How to handle a resolver identity that violates the contract at the trust
-   * boundary. Defaults to `"anonymous"` (a forged claim set is downgraded to
-   * anonymous rather than flowing in as an unchecked cast).
-   */
-  readonly onInvalid?: IdentityRejectMode;
+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>;
 }
-/** Result of validating a candidate identity against the contract. */
-type IdentityValidation = {
-  ok: true;
-} | {
-  error: string;
-  ok: false;
-};
-/**
- * A declared identity claim contract. Carries the codegen discovery brand, the
- * declared claim validators, the reject policy, and a runtime `validate`. The
- * `TClaims` type parameter is the inferred claim shape (always extending
- * `{ userId: string }`); it is phantom (no runtime field) and exists so
- * `@lunora/codegen` and {@link InferIdentity} can recover the type.
- */
-interface IdentityContract<TClaims extends {
-  userId: string;
-} = {
-  userId: string;
-}> {
-  /**
-   * Phantom carrier for the inferred claim type. Never populated at runtime
-   * (`undefined`); present only so the type flows to codegen / {@link InferIdentity}.
+interface TableBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> extends TableDefinition<Shape> {
+  /** Declare an aggregate (counter/sum/…) maintained by triggers for O(1) reads. */
+  aggregateIndex: (name: string, options?: InlineAggregateIndexOptions<Shape>) => TableBuilder<Shape>;
+  /**
+   * Stamp every row with `_commitSeq` — a per-shard integer, allocated once
+   * per mutation and strictly increasing in **commit order**, refreshed on
+   * every write to the row (insert, patch, replace, and the marker flip a
+   * `.softDelete()` performs).
+   *
+   * `_creationTime` is wall-clock and therefore cannot order commits: the
+   * clock is read when the handler runs, the write lands when the transaction
+   * commits, and nothing ties those instants together. A changefeed paging on
+   * `_creationTime` can skip a row permanently. Paging on `_commitSeq`
+   * (`where: { _commitSeq: { gt: cursor } }, orderBy: ["_commitSeq"]`) cannot.
+   *
+   * It orders COMMITS, not rows: one mutation's rows share a value. A bounded
+   * page can therefore end mid-group, so a consumer must checkpoint at a
+   * sequence it has seen the whole of, never at the last row of a full page.
+   * An action's writes are the exception to the grouping — they commit
+   * independently, so each gets its own sequence.
+   *
+   * Ordered, not contiguous — read a gap as "nothing to see", never as loss.
+   * Per-shard, not global: two shards allocate independently, so a cursor is
+   * only meaningful against the shard it came from. Rejected on `.global()`
+   * tables, which have no shard-local transaction to allocate inside.
+   *
+   * **A hard delete is invisible to the feed.** The sequence lives on the row,
+   * so a physically removed row takes it along: the row stops appearing, but
+   * no event says it went away. Pair `.commitOrdered()` with `.softDelete()`
+   * when the feed must observe deletes — the tombstone flip is an UPDATE, so
+   * it advances the sequence and pages through like any other change.
    */
-  readonly __claimType?: TClaims;
-  readonly __lunoraIdentity: true;
-  /** The declared claim validators (a `@lunora/values` validator map). */
-  readonly claims: ValidatorMap;
-  /** Reject policy applied at the trust boundary. See {@link IdentityRejectMode}. */
-  readonly onInvalid: IdentityRejectMode;
+  commitOrdered: () => TableBuilder<Shape>;
   /**
-   * Validate a resolver's returned identity against the declared claims. On
-   * success the caller keeps the original identity untouched (so undeclared
-   * claims are forwarded verbatim, preserving today's behaviour); on failure
-   * the worker applies the `onInvalid` policy.
+   * 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(...)`.
    */
-  validate: (identity: Record<string, unknown>) => IdentityValidation;
+  externallyManaged: () => TableBuilder<Shape>;
+  /**
+   * Declare a geospatial index over a `v.geoPoint()` column. The runtime keeps
+   * a geohash companion so `withGeoIndex(name, q => q.near(point, radius))` and
+   * `.within(bbox)` resolve as a geohash-prefix range scan + Haversine
+   * refine/sort. `options.precision` tunes the geohash length (default 9).
+   */
+  geoIndex: (name: string, options: {
+    field: keyof Shape & string;
+    precision?: number;
+  }) => TableBuilder<Shape>;
+  /**
+   * Mark this table as global (cross-shard). Backed by **D1** by default;
+   * pass `{ backend: "hyperdrive" }` to store it in a Postgres/MySQL database
+   * via Cloudflare Hyperdrive (PlanetScale, Neon, …) instead. Either way the
+   * table stays reactive — live queries re-run on write.
+   */
+  global: (options?: {
+    backend?: GlobalBackend;
+  }) => TableBuilder<Shape>;
+  /** Add a secondary index. */
+  index: (name: string, fields: ReadonlyArray<(keyof Shape & string) | (typeof SYSTEM_INDEX_FIELDS)[number]>, options?: {
+    unique?: boolean;
+  }) => TableBuilder<Shape>;
+  /**
+   * Declare this table EPHEMERAL — state the shard rebuilds rather than
+   * remembers.
+   *
+   * A memory table is a full `ctx.db` table: indexes, `where`, `orderBy`,
+   * pagination, relations, live queries. What it is not is durable. Its rows
+   * are wiped the moment the Durable Object is reconstructed — which happens
+   * on every eviction, and a WebSocket-hibernating shard is evicted often — so
+   * a memory table holds only what can be derived again: presence and cursors,
+   * a live participant list, a rate-limit window, an actor's scratch state.
+   *
+   * Pair it with `onShardInit` to rebuild whatever the app needs present.
+   * The framework guarantees the ordering: every memory table is cleared, and
+   * every init hook has run, before any handler can read one. Without a hook a
+   * memory table simply comes back empty, which is a correct state for
+   * presence and a wrong one for a cache someone is treating as authoritative.
+   *
+   * **On Cloudflare the rows still transit the DO's SQLite.** workerd exposes
+   * exactly one SQL handle and no memory-backed database, so `.memory()` buys
+   * the LIFETIME (and skips the CDC changelog, so an append-heavy presence
+   * table does not grow the op-log), not the write. Treat it as "state I am
+   * happy to lose", not as "state that is free to write" — see
+   * `PlatformCapabilities.memoryTables`, rated `emulated` for exactly this
+   * reason.
+   *
+   * Rejected alongside `.global()` (a D1 table is not this shard's to clear),
+   * `.commitOrdered()` (a sequence that resets is not a sequence), and
+   * `.source()` (an externally-materialized table is not ours to wipe).
+   */
+  memory: () => TableBuilder<Shape>;
+  /**
+   * Name the column holding the owning user's id, so "only the owner sees these
+   * rows" is declared once here rather than restated in every shape.
+   *
+   * A `defineShape({ table, owner: true })` over this table derives its predicate
+   * from the field: the subscriber's verified `ctx.auth.userId` must match, and an
+   * anonymous subscriber is denied. Pairs naturally with `.shardBy(field)` on the
+   * same column — the shard key routes the storage, `ownedBy` states who the rows
+   * belong to — but the two are independent and either can be used alone.
+   *
+   * This is a *shape* declaration, not an RLS policy: it narrows what a shape
+   * replicates. Guarding procedure reads/writes is still `rls(...)`'s job.
+   */
+  ownedBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+   * Opt this table OUT of secure-by-default RLS. Under a schema marked
+   * `.rls("required")`, every table is protected (the write path denies raw,
+   * non-RLS `ctx.db` access); calling `.public()` exempts this one table so a
+   * plain `query`/`mutation` may read/write it without an RLS policy. No effect
+   * when the schema does not require RLS.
+   */
+  public: () => TableBuilder<Shape>;
+  /**
+   * Declare a rank index (sorted companion table, btree-backed) for
+   * `rank(row)` / `rankPage()` reads in O(log n). See {@link RankIndexDefinition}.
+   */
+  rankIndex: (name: string, options: InlineRankIndexOptions<Shape>) => TableBuilder<Shape>;
+  /** Declare relations to other tables, loaded via `findMany({ with })`. */
+  relations: (build: (r: RelationBuilder) => Record<string, RelationDefinition>) => TableBuilder<Shape>;
+  /**
+   * Add a full-text search index over `field`, queried with
+   * `.withSearchIndex(name, q => q.search(field, term))`. `field` may be a
+   * dot-separated path into a nested object (`"properties.name"`).
+   * `filterFields` (at most 16) lists the columns `.eq()` may narrow by inside
+   * the search. `language` selects the text analysis (accent folding always,
+   * plus that language's stopwords). `staged: true` skips the migration-time
+   * backfill on a large existing table — pre-existing rows stay unsearchable
+   * until `__lunora_admin__:backfillSearch` is run against the deployment. `strategy: "native"` uses the engine's
+   * own full-text index where it has one (Postgres) — faster on large corpora,
+   * at the cost of the engine ranking rather than the shared scorer.
+   */
+  searchIndex: (name: string, options: {
+    field: string;
+    filterFields?: ReadonlyArray<string>;
+    language?: SearchLanguage;
+    staged?: boolean;
+    strategy?: SearchStrategy;
+  }) => TableBuilder<Shape>;
+  /** Route storage by the named field — one DO per distinct value. */
+  shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+   * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
+   * default `deletedAt`) and changes `ctx.db.<table>.delete()` to **set** it
+   * instead of removing the row; `onDelete: "cascade"` children are recursively
+   * soft-deleted too. **List reads** (`findMany`/`findFirst`/`query()`/`count`/
+   * `aggregate`/relation loads) then hide soft-deleted rows unless they pass
+   * `includeDeleted: true`; by-id `get`/`patch`/`replace` and the new
+   * `restore()` still address the row directly. `hardDelete()` physically
+   * removes it (cascading as a real delete). Note: `includeDeleted` is a read
+   * scope, not access control — anyone who can run the read can set it; a unique
+   * index still rejects a new row that collides with a soft-deleted one (the row
+   * physically persists).
+   */
+  softDelete: (options?: {
+    field?: string;
+  }) => TableBuilder<Shape>;
+  /**
+   * Materialize this table from an external Postgres/MySQL behind Cloudflare
+   * Hyperdrive (plan 077). A system-driven poll loop reads the tenant slice
+   * (`query`, with params bound from `tenantBy`) and lands it in the DO's SQLite,
+   * after which `defineShape` carries it to clients unchanged. Implies
+   * `.externallyManaged()` (rows come from the ingest loop, not user mutations).
+   *
+   * Orthogonal to `.shardBy()` — combine them for per-tenant DOs. **Under
+   * `.shardBy()` `tenantBy` is mandatory** (the tenant-isolation boundary); the
+   * `external_source_unscoped` advisor lint fails the build when it is absent, and
+   * `external_source_on_global` rejects combining `.source()` with `.global()`.
+   */
+  source: (definition: ExternalSourceDefinition) => TableBuilder<Shape>;
+  /** Declare named lifecycle triggers fired inline within the write path. */
+  triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
+  /**
+   * Declare a table-level TTL: a DO alarm-driven sweep auto-deletes rows whose
+   * expiry has passed (or soft-deletes them when the table also
+   * `.softDelete()`s). `field` is an epoch-millisecond column; without
+   * `options.after` its value is the absolute expiry instant, with `after` the
+   * row expires `after` ms past `field` (`field + after`). Coarse, cheap,
+   * table-level — for per-row schedules use `@lunora/scheduler`.
+   */
+  ttl: (field: keyof Shape & string, options?: {
+    after?: number;
+  }) => TableBuilder<Shape>;
+  /** Declare a vector index over a single text field on this table. */
+  vectorize: (field: keyof Shape & string, options: VectorizeOptions<Shape>) => TableBuilder<Shape>;
+}
+/** Options for `defineVectorIndex(...)` (DSL Shape B). */
+interface VectorIndexOptions {
+  dimensions: number;
+  embed: VectorEmbedder;
+  /** Optional projection of the source row into Vectorize metadata. */
+  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  metric: VectorMetric;
+  /** The vector source: which table, and how to derive the embedded text. */
+  source: {
+    select: (row: Record<string, unknown>) => string;
+    table: string;
+  };
 }
-/** Recover the declared claim type from a {@link defineIdentity} contract. */
-type InferIdentity<T> = T extends IdentityContract<infer TClaims> ? TClaims : never;
 /**
- * Declare the identity claim contract. `claims` is a `@lunora/values` validator
- * map whose inferred type must extend `{ userId: string }` — if it does not
- * (e.g. `userId` is missing or not a required string), the argument type
- * collapses to `never` and the call fails to typecheck.
- * @example
- * export const identity = defineIdentity({ userId: v.string(), tenantId: v.optional(v.string()), scopes: v.optional(v.array(v.string())) });
+ * Build a table definition. Returned object is both the table definition (for
+ * `defineSchema`) and a fluent builder for indexes + sharding metadata.
  */
-declare const defineIdentity: <A extends ValidatorMap>(claims: InferValidatorMap<A> extends {
-  userId: string;
-} ? A : never, options?: DefineIdentityOptions) => IdentityContract<InferValidatorMap<A> & {
-  userId: string;
-}>;
-/** Handler for a connection-lifecycle hook. */
-type LifecycleHandler = (context: MutationCtx, event: LifecycleEvent) => Promise<void> | void;
-/** Handler for a shard-init hook. */
-type ShardInitHandler = (context: MutationCtx, event: ShardInitEvent) => Promise<void> | void;
-/** Register a hook that fires once when a client's WebSocket connects. */
-declare const onConnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
-/** Register a hook that fires once when a client's WebSocket disconnects. */
-declare const onDisconnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
+declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
 /**
- * Register a hook that fires ONCE per Durable Object instance, before any
- * handler on that instance can run — the re-init half of `.memory()` tables.
- *
- * A shard is not a process that stays up. Cloudflare reconstructs the Durable
- * Object after every eviction, and a shard whose sockets are hibernating is
- * evicted routinely, so "cold start" is a steady-state event rather than a rare
- * one. Everything the shard held in memory is gone at that moment: the JS heap,
- * and every `.memory()` table, which the framework has already cleared by the
- * time this hook runs.
- *
- * ```ts
- * // lunora/init.ts
- * import { onShardInit } from "@lunora/server";
- *
- * export const warm = onShardInit(async (ctx, event) => {
- *     // Rebuild ephemeral state from the durable tables that outlived us.
- *     for await (const member of ctx.db.roomMembers.iterate({ where: { roomId: event.shardKey } })) {
- *         await ctx.db.presence.insert({ userId: member.userId, status: "away" });
- *     }
- * });
- * ```
- *
- * **Ordering is the guarantee.** Memory tables are cleared, then every init hook
- * runs to completion, and only then does the dispatch that triggered the cold
- * start proceed. No handler, subscription refresh, alarm, or shape poke can
- * observe a memory table in the gap. Hooks run sequentially in manifest order,
- * so one may depend on state an earlier one wrote.
- *
- * **It is a mutation, and it runs on every cold start.** Keep it cheap and keep
- * it idempotent: it is on the latency path of the request that woke the shard,
- * and it will run again — many times — over the shard's life. Writing to durable
- * tables from here is legal and occasionally right, but remember it is a
- * rebuild, not a migration; use `defineMigration` for anything that should
- * happen once.
- *
- * **No caller identity.** The hook dispatches as a trusted system call with no
- * request identity — `ctx.auth` is anonymous and RLS does not apply even under
- * `.rls("required")`, exactly as for a cron tick or a migration. RLS scopes rows
- * to a user and an init hook has none, so `ctx.db` here sees every row: scope
- * your reads yourself. (`onConnect`/`onDisconnect` are the opposite case — they
- * carry the socket's verified identity and stay RLS-guarded.)
+ * 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)`.
  *
- * A throw is logged and does NOT fail the dispatch that woke the shard — an init
- * hook that cannot rebuild presence must not take the whole shard down with it.
- * The table is then cleared but not refilled, so reads see nothing. A failure
- * EARLIER, before the framework's clear runs, instead leaves the previous
- * instance's rows in place: a memory table's rows live in SQLite until they are
- * deleted, so an eviction on its own does not remove them.
+ * `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.
  */
-declare const onShardInit: (handler: ShardInitHandler) => RegisteredLifecycleHook;
-/** Default `limit` when the caller doesn't ask for one. */
-declare const DEFAULT_LIMIT = 25;
-/** Default ceiling on `limit`, so one request can't ask for an unbounded page. */
-declare const DEFAULT_MAX_LIMIT = 100;
+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>;
 /**
- * Per-field predicate accepted for a declared filter column. An alias of the
- * `ctx.db` `where` DSL's own operator type rather than a copy, so the two cannot
- * drift as operators are added.
+ * Columns every row carries implicitly (never part of a table's declared
+ * `shape`), so `.index()` may legitimately name them. The single source for
+ * both the compile-time allow-list (`TableBuilder["index"]`'s `fields` type,
+ * via `(typeof SYSTEM_INDEX_FIELDS)[number]`) and the runtime cross-check
+ * below (via `SYSTEM_INDEX_FIELDS_SET`) — declared once so the two can't
+ * drift apart.
  */
-type ListFilterOperators<T> = WhereOperators<T>;
+declare const SYSTEM_INDEX_FIELDS: readonly ["_commitSeq", "_creationTime", "_id"];
 /**
- * The filter allow-list a caller may declare: a subset of the document's own
- * columns, each with a validator for that column's type. Constraining the KEYS to
- * `keyof Doc` is what turns a typo'd or renamed column into a compile error
- * instead of a predicate that silently never matches.
+ * Per-table, per-KIND index→declared-fields map: for each table, each index
+ * KIND (`index` | `rank` | `geo`) that has at least one declared index maps
+ * to a name→fields record for that kind only. Distilled by
+ * {@link indexFieldsFromSchema}; this is the shape `mask()`'s
+ * `MaskOptions.indexFields` expects (see `./mask/types`), so a table not
+ * present here (no declared indexes of any kind) is simply absent from the
+ * map rather than mapped to `{}`, and a kind with no declared indexes on a
+ * table that HAS other kinds is simply absent from that table's entry.
+ *
+ * Kept per kind (rather than one flat name→fields record) because the engine
+ * resolves `withIndex`/`withGeoIndex`/rank reads in THREE separate
+ * namespaces (`tableDefinition.indexes` / `.geoIndexes` / `.rankIndexes` —
+ * see `@lunora/shard-engine`'s `ctx-db.ts`), so the same name can legally and
+ * unambiguously denote a different index per kind. A flat map would let one
+ * kind's fields silently shadow another's for a colliding name, producing a
+ * wrong-namespace answer from the mask guard (checking the wrong index's
+ * fields) instead of the documented fail-open (missing lookup) — see plan 258.
+ */
+type IndexFieldsByTable = Readonly<Record<string, {
+  readonly geo?: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly index?: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly rank?: Readonly<Record<string, ReadonlyArray<string>>>;
+}>>;
+declare const indexFieldsFromSchema: (schema: Schema) => IndexFieldsByTable;
+declare const defineSchema: <T extends Record<string, TableDefinition>>(tables: T, vectorIndexes?: Record<string, VectorIndexDefinition>, aggregateIndexes?: Record<string, AggregateIndexDefinition>, rankIndexes?: Record<string, RankIndexDefinition>) => ExtendableSchema<T>;
+/**
+ * Fields never written into a snapshot, whatever table they appear on.
+ *
+ * Names rather than types, because that is the only signal available here: a
+ * trigger sees values, not the column metadata that would say "this one is a
+ * secret". Extend it per app rather than relying on this list being complete.
  */
-type ListFilterShape<TDocument> = { [K in keyof TDocument & string]?: Validator<TDocument[K]>; };
-/** The `where` argument: each declared filter column, optionally, as a bare value or an operator object. */
-type ListWhere<F> = { [K in keyof F]?: Infer<NonNullable<F[K]>> | ListFilterOperators<Infer<NonNullable<F[K]>>>; };
-/** One `orderBy` entry. `direction` defaults to `"asc"`. */
-interface ListOrderByEntry<O extends string> {
-  direction?: "asc" | "desc";
-  field: O;
-}
-/** The decoded arguments a {@link defineListArgs} endpoint receives. */
-interface ListArgsValue<F, O extends string> {
-  cursor?: null | number | string;
-  limit?: number;
-  orderBy?: ListOrderByEntry<O>[];
-  where?: ListWhere<F>;
+declare const DEFAULT_REDACTED_FIELDS: ReadonlyArray<string>;
+declare const DOCUMENT_HISTORY_BARE_TABLE = "versions";
+/** The prefixed table name the extension produces at merge time. */
+declare const DOCUMENT_HISTORY_TABLE: "documentHistory_versions";
+/** One recorded version, as {@link DocumentHistoryFunctions.listForDocument} returns it. */
+interface DocumentHistoryEntry {
+  /** The row as it stood after the write, redacted. Absent for a delete, and when `truncated`. */
+  doc?: Record<string, unknown>;
+  /** The row this version belongs to. */
+  documentId: string;
+  /** Which write produced this version. */
+  op: "delete" | "insert" | "update";
+  /** The row as it stood before the write, redacted. Absent for an insert, and when `truncated`. */
+  previous?: Record<string, unknown>;
+  /** When the write happened (epoch ms). */
+  recordedAt: number;
+  /** The table the row lives in. */
+  tableName: string;
+  /** `true` when the snapshots were dropped for exceeding `maxSnapshotBytes`. */
+  truncated?: boolean;
 }
-interface DefineListArgsConfig<F, O extends string> {
-  /** `limit` applied when the caller omits one. Defaults to 25. */
-  readonly defaultLimit?: number;
+/** Options for {@link defineDocumentHistory}. */
+interface DefineDocumentHistoryOptions {
   /**
-   * Allow-list of filterable columns. Publish only columns an index can serve;
-   * anything absent here is unreachable from the client.
+   * Cap on one serialized snapshot (bytes). Past it the entry is written
+   * without its snapshots and marked `truncated`. Defaults to 64 KB.
    */
-  readonly filter: F;
-  /** Ceiling on `in` / `notIn` array length — one bound parameter each. Defaults to 100. */
-  readonly maxInValues?: number;
-  /** Ceiling on `limit`; a larger request is clamped down, not rejected. Defaults to 100. */
-  readonly maxLimit?: number;
-  /** Ceiling on how many `orderBy` entries a request may ask for. Defaults to 8. */
-  readonly maxOrderBy?: number;
-  /** Allow-list of sortable columns. Pass `[]` to fix the order server-side. */
-  readonly orderBy: ReadonlyArray<O>;
-}
-/** The validator map handed to `.input()`. Typed precisely so `args` infers end-to-end. */
-interface ListArgsValidators<F, O extends string> {
-  cursor: ColumnValidator<null | number | string | undefined, null | number | string | undefined>;
-  limit: ColumnValidator<number | undefined, number | undefined>;
-  orderBy: ColumnValidator<ListOrderByEntry<O>[] | undefined, ListOrderByEntry<O>[] | undefined>;
-  where: ColumnValidator<ListWhere<F> | undefined, ListWhere<F> | undefined>;
+  maxSnapshotBytes?: number;
+  /**
+   * Extra field names to drop from every snapshot, on top of the built-in
+   * secret-shaped defaults.
+   */
+  redact?: ReadonlyArray<string>;
+  /**
+   * How long (ms) an entry is kept. `vacuum` deletes entries older than this.
+   * Defaults to 90 days.
+   */
+  retentionMs?: number;
 }
-interface ListArgsSpec<TDocument, F, O extends string> {
-  /** Spread into `.input(...)` — `{ cursor, limit, orderBy, where }`. */
-  readonly args: ListArgsValidators<F, O>;
+/** The registered functions a document-history component ships. */
+interface DocumentHistoryFunctions {
   /**
-   * Translate the decoded arguments into the `findMany` options object:
-   * `limit` clamped into `[1, maxLimit]`, `orderBy` reshaped from
-   * `{ field, direction }[]` into `ctx.db`'s `{ column: direction }[]`.
+   * **Internal** query: the recorded versions of one row, newest first.
    *
-   * Returns `QueryArgs<Doc>` — bound to the table, not free — so a mismatch
-   * between what this helper declares and what the table actually holds is a
-   * compile error at the `findMany` call site.
+   * Internal because an entry is a full row snapshot, including columns the
+   * table's own RLS hides — wrap it in a procedure of your own that applies
+   * whatever authorization the surface needs.
+   *
+   * Pass `before` to read the history as of an instant: the first entry back is
+   * the last version at or before it, which is what a point-in-time
+   * reconstruction needs.
+   */
+  listForDocument: RegisteredQuery<{
+    before: ReturnType<typeof v.optional>;
+    documentId: ReturnType<typeof v.string>;
+    limit: ReturnType<typeof v.optional>;
+  }, DocumentHistoryEntry[]>;
+  /**
+   * Internal mutation that deletes entries older than the retention window,
+   * oldest first, and reports how many it removed. Schedule it on a cron.
+   *
+   * Compare `deleted` against `limit` to decide whether to run again rather
+   * than assuming one pass drained the backlog.
    */
-  readonly toQueryArgs: (args: ListArgsValue<F, O>) => QueryArgs$2<TDocument>;
+  vacuum: RegisteredMutation<{
+    limit: ReturnType<typeof v.optional>;
+  }, {
+    deleted: number;
+  }>;
 }
-/** Clamp a caller-supplied `limit` into `[1, maxLimit]`; a non-finite value falls back to `fallback`. */
-declare const clampLimit: (limit: number | undefined, fallback: number, maxLimit: number) => number;
+/** The component shape {@link defineDocumentHistory} returns. */
+type DocumentHistoryComponent = {
+  functions: DocumentHistoryFunctions;
+  /**
+   * The `.triggers(...)` argument that records this table's versions —
+   * `.triggers(history.record)`.
+   *
+   * `after*` on all three ops: a `before*` handler runs while the write can
+   * still be aborted, and a history entry for a write that never happened is a
+   * lie the reader has no way to detect.
+   */
+  record: (t: TriggerBuilder) => Record<string, TriggerDefinition>;
+} & Component<{
+  [DOCUMENT_HISTORY_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
 /**
- * Declare the filter / sort / page arguments for a list endpoint, plus the
- * translation into `ctx.db.<table>.findMany(...)` options. See the module docs
- * for the shape and the reasoning behind it.
- *
- * Curried on the document type: `defineListArgs<Doc<"messages">>()({ … })`. The
- * extra `()` buys the thing that matters — with `Doc` bound, `filter` keys and
- * `orderBy` entries are checked against the table's real columns, so a typo or a
- * column renamed out from under the endpoint is a COMPILE error instead of a
- * predicate that silently matches nothing. TypeScript has no partial type-argument
- * inference, so binding `Doc` explicitly while still inferring `F` and `O` from
- * the config requires the second call.
+ * The document-history schema extension: one `versions` table, auto-namespaced
+ * to `documentHistory_versions` at merge time.
  */
-declare const defineListArgs: <TDocument>() => <F extends ListFilterShape<TDocument>, O extends keyof TDocument & string>(config: DefineListArgsConfig<F, O>) => ListArgsSpec<TDocument, F, O>;
+declare const documentHistoryExtension: SchemaExtension<{
+  [DOCUMENT_HISTORY_BARE_TABLE]: ReturnType<typeof defineTable>;
+}>;
 /**
- * Structural mirrors of `@lunora/shard-engine`'s rank-page-row shapes
- * (`RankPageRowKey` / `RankPageRow` / `ShardRankPageResult`) — the return type
- * of the writer's `rankPageRows` seam, the cross-shard companion to
- * `rankPage`.
+ * Build a document-history {@link Component} — schema extension, the
+ * `.triggers()` recorder, and the `listForDocument` / `vacuum` functions.
+ * @param options history configuration (retention, redaction, snapshot cap).
+ * @returns a component bundling the extension, the functions, and the recorder.
+ */
+declare const defineDocumentHistory: (options?: DefineDocumentHistoryOptions) => DocumentHistoryComponent;
+/**
+ * Redact secrets from a free-form message. Masks, in order: any quoted value
+ * whose contents look like a credential (so a value surfaced as `received string
+ * "sk_live_…"` is masked even though the surrounding text is not a token); a
+ * `scheme://user:password@host` URL credential (the password segment); any
+ * known-prefix credential token wherever it appears, at any length; any value
+ * following a secret-named key in `KEY=value` / `KEY: value` form; and any
+ * remaining bare high-entropy ≥24-char token run anywhere in the message.
  *
- * Shared by `../rls/middleware` and `../mask/middleware`: both wrap
- * `rankPageRows` structurally (no `@lunora/shard-engine` import, mirroring how
- * every other method on their `DatabaseWriterLike`/`MaskDatabase` projections
- * is hand-mirrored rather than imported) and both need the exact same result
- * shape to type their overrides. A single copy here means the two wrappers
- * can't drift out of lockstep with each other — see AGENTS.md's platform
- * parity note on `ShardSqlExec` and the canonical binding `*Like` projections
- * shipping wrong for exactly this reason (two hand-maintained mirrors of one
- * upstream type).
+ * 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.
  */
-/** Structural mirror of `@lunora/shard-engine`'s `RankPageRowKey`. */
-interface RankPageRowKeyLike {
-  partitionKey: string;
-  rowId: string;
-  sortValues: ReadonlyArray<unknown>;
-}
-/** Structural mirror of `@lunora/shard-engine`'s `RankPageRow`. */
-interface RankPageRowLike {
-  doc: Record<string, unknown>;
-  key: RankPageRowKeyLike;
-}
-/** Structural mirror of `@lunora/shard-engine`'s `ShardRankPageResult` — the `rankPageRows` return shape. */
-interface ShardRankPageResultLike {
-  directions: ReadonlyArray<"asc" | "desc">;
-  hasMore: boolean;
-  rows: ReadonlyArray<RankPageRowLike>;
+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;
 }
 /**
- * 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.
+ * 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.
  */
-interface QueryArgs$1 {
-  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$1 {
-  baseWhere?: WhereInput;
-  field?: string;
-  op: string;
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `GroupByOptions`. */
-interface GroupByArgs$1 {
-  agg?: {
-    field?: string;
-    op: string;
-  };
-  baseWhere?: WhereInput;
-  by: ReadonlyArray<string>;
-  relationBaseWhere?: (table: string) => undefined | WhereInput;
-  restrictsCounts?: boolean;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `RankOptions`. */
-interface RankArgs {
-  baseWhere?: WhereInput;
-  restrictsCounts?: boolean;
-  row: Record<string, unknown> | string;
-  where?: WhereInput;
-}
-/** Structural mirror of `@lunora/do`'s `RankBeforeOptions`. */
-interface RankBeforeArgs {
-  partitionKey: string;
-  restrictsCounts?: boolean;
-  rowId: string;
-  sortValues: ReadonlyArray<unknown>;
-}
-/** Structural mirror of `@lunora/do`'s `RankPageOptions`. */
-interface RankPageArgs {
-  baseWhere?: WhereInput;
-  cursor?: null | string;
-  restrictsCounts?: boolean;
-  take?: number;
-  where?: WhereInput;
+declare class LunoraEnvError extends LunoraError$1 {
+  readonly failures: ReadonlyArray<EnvKeyFailure>;
+  constructor(failures: ReadonlyArray<EnvKeyFailure>);
 }
-interface QueryPage$1 {
-  continueCursor: null | string;
-  isDone: boolean;
-  page: Record<string, unknown>[];
+/** 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>;
 }
-interface TableReaderLike$1 {
-  collect: () => Promise<Record<string, unknown>[]>;
-  filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike$1;
-  first: () => Promise<Record<string, unknown> | null>;
-  paginate: (options: {
-    cursor?: null | string;
-    numItems: number;
-  }) => Promise<QueryPage$1>;
-  take: (limit: number) => Promise<Record<string, unknown>[]>;
-  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => TableReaderLike$1;
-  withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike$1;
-  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike$1;
+/**
+ * Define a typed, validated accessor over a Worker's `env`. Pass a record of
+ * `v.*` validators; receive an accessor that validates lazily per key (cached
+ * per `env` identity) and infers its output type from the validators.
+ *
+ * ```ts
+ * import { defineEnv, v } from "@lunora/server";
+ *
+ * const config = defineEnv({
+ *     STRIPE_KEY: v.string(),
+ *     PORT: v.optional(v.number()),
+ * });
+ *
+ * export default {
+ *     fetch(request, env) {
+ *         const { STRIPE_KEY, PORT } = config(env); // STRIPE_KEY: string, PORT?: number
+ *         // …
+ *     },
+ * };
+ * ```
+ *
+ * Throws {@link LunoraEnvError} (secrets redacted) when a key is missing or
+ * invalid — lazily on first access of that key, or eagerly via `config.parse(env)`.
+ */
+declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
+declare class LunoraError extends LunoraError$1 {
+  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
 }
 /**
- * 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`.
+ * 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 DatabaseWriterLike {
-  /**
-   * Reduce matching rows to a scalar. The RLS wrapper AND-merges the read
-   * `baseWhere` into `options` so the reduction only sees policy-visible rows
-   * (safe: an aggregate scoped to `where` never reveals a hidden row — see
-   * `@lunora/do`'s `RestrictableQueryOptions`). Required: the only writer ever
-   * wrapped is `@lunora/do`'s `createShardCtxDb`, which always implements it.
-   */
-  aggregate: (tableName: string, options: AggregateArgs$1) => Promise<null | number>;
-  count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
-  delete: (id: string, expectedTable?: string, options?: {
-    hard?: boolean;
-  }) => Promise<void>;
-  /** Uncapped, chunked erase of a whole table. The RLS wrapper gates each row like a single delete. */
-  deleteAll?: (tableName: string, options?: {
-    chunkSize?: number;
+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<{
-    deleted: number;
-  }>;
-  deleteMany: (ids: ReadonlyArray<string>, options?: {
+  }): Promise<void>;
+  deleteMany?(ids: ReadonlyArray<string>, options?: {
     limit?: number;
-  }, expectedTable?: string) => Promise<{
+  }, expectedTable?: string): Promise<{
     deleted: number;
   }>;
-  deleteWhere?: (tableName: string, where: WhereInput, options?: {
+  deleteWhere?(tableName: string, where: Record<string, unknown>, options?: {
     limit?: number;
-  }) => Promise<{
+  }): 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>;
-  /**
-   * Group + reduce. Same `baseWhere` injection as `aggregate`: the per-group
-   * reduction is scoped to policy-visible rows, so a group count tallies only
-   * rows the caller may read. Required for the same reason as `aggregate`.
-   */
-  groupBy: (tableName: string, options: GroupByArgs$1) => Promise<ReadonlyArray<{
-    key: Record<string, unknown>;
-    value: null | number;
-  }>>;
-  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
-  insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+  findFirst(tableName: string, args?: unknown): Promise<unknown>;
+  findFirstOrThrow(tableName: string, args?: unknown): Promise<unknown>;
+  findMany(tableName: string, args?: unknown): Promise<unknown>;
+  get(id: string, expectedTable?: string): Promise<unknown>;
+  groupBy(tableName: string, options: unknown): Promise<unknown>;
+  insert(tableName: string, document: Record<string, unknown>): Promise<string>;
+  insertMany?(tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
     skipDuplicates?: boolean;
-  }) => Promise<(string | null)[]>;
-  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<{
+  }): Promise<(string | null)[]>;
+  patch(id: string, patch: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  patchMany?(patches: ReadonlyArray<{
     id: string;
     patch: Record<string, unknown>;
   }>, options?: {
     limit?: number;
-  }, expectedTable?: string) => Promise<{
+  }, expectedTable?: string): Promise<{
     patched: number;
   }>;
-  patchWhere?: (tableName: string, args: {
+  patchWhere?(tableName: string, args: {
     patch: Record<string, unknown>;
-    where: WhereInput;
+    where: Record<string, unknown>;
   }, options?: {
     limit?: number;
-  }) => Promise<{
+  }): Promise<{
     patched: number;
   }>;
-  query: (tableName: string) => TableReaderLike$1;
-  /**
-   * 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$1>;
+  query(tableName: string): {
+    withGeoIndex(indexName: string, build: (q: unknown) => unknown): unknown;
+    withSearchIndex(indexName: string, search: (q: unknown) => unknown): unknown;
+  };
+  rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
+  rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
+  replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  restore?(id: string, expectedTable?: string): Promise<void>;
+}
+/** The per-table accessor object returned for the `ctx.db` table form. */
+interface FacadeEntry {
+  aggregate: (options: unknown) => Promise<unknown>;
+  count: (where?: unknown) => Promise<number>;
+  delete: (id: string) => Promise<void>;
+  deleteMany: {
+    (ids: ReadonlyArray<string>, options?: {
+      limit?: number;
+    }): Promise<{
+      deleted: number;
+    }>;
+    (args: {
+      limit?: number;
+      where: Record<string, unknown>;
+    }): Promise<{
+      deleted: number;
+    }>;
+  };
+  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
+  exists: (where?: unknown) => Promise<boolean>;
+  findFirst: (args?: unknown) => Promise<unknown>;
+  findFirstOrThrow: (args?: unknown) => Promise<unknown>;
+  findMany: (args?: unknown) => Promise<unknown>;
+  get: (id: string) => Promise<unknown>;
+  groupBy: (options: unknown) => Promise<unknown>;
+  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
+  hardDelete: (id: string) => Promise<void>;
+  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
   /**
-   * Cross-shard companion to `rankPage`: same ranked slice, but each row
-   * keeps its rank-key tuple for the query coordinator's k-way merge. Same
-   * count-of-partition RLS hazard as `rankPage` — failed closed under a read
-   * policy for the identical reason (see `rankPage` above).
+   * Insert many documents into this table in one call. With
+   * `{ skipDuplicates: true }`, UNIQUE breaches resolve to `null` for that row
+   * instead of failing the batch. The typed facade narrows the return to
+   * `Id<T>[]` when skipDuplicates is not requested.
    */
-  rankPageRows?: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<ShardRankPageResultLike>;
-  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
-  restore?: (id: string, expectedTable?: string) => Promise<void>;
+  insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+    skipDuplicates?: boolean;
+  }) => Promise<(string | null)[]>;
+  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
+  patchMany: {
+    (patches: ReadonlyArray<{
+      id: string;
+      values: Record<string, unknown>;
+    }>, options?: {
+      limit?: number;
+    }): Promise<{
+      patched: number;
+    }>;
+    (args: {
+      limit?: number;
+      values: Record<string, unknown>;
+      where: Record<string, unknown>;
+    }): Promise<{
+      patched: number;
+    }>;
+  };
+  rank: (indexName: string, options: unknown) => Promise<unknown>;
+  rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
+  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
+  restore: (id: string) => Promise<void>;
+  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
+  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
+  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
+  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => unknown;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
+}
+/** Options accepted by the per-table `insert` accessor. */
+interface FacadeInsertOptions {
   /**
-   * Whole-shard erase. The RLS wrapper deliberately **fails this closed** rather
-   * than wrapping it — see the wrapper's `wipeShard`.
+   * 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 })`.
    */
-  wipeShard?: (options?: {
-    chunkSize?: number;
-    exclude?: ReadonlyArray<string>;
-    tables?: ReadonlyArray<string>;
-  }) => Promise<{
-    deleted: number;
-    tables: Record<string, number>;
+  skipDuplicates?: boolean;
+}
+/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
+type UpsertTarget = ReadonlyArray<string> | string;
+/** Argument to the per-table `upsert` accessor. */
+interface UpsertArgs {
+  /** Document inserted when no existing row matches the `target`. */
+  create: Record<string, unknown>;
+  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
+  target: UpsertTarget;
+  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
+  update?: Record<string, unknown>;
+}
+/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
+interface UpsertResult {
+  created: boolean;
+  id: string;
+}
+/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
+interface UpsertManyArgs {
+  rows: ReadonlyArray<{
+    create: Record<string, unknown>;
+    update?: Record<string, unknown>;
   }>;
+  target: UpsertTarget;
+}
+/**
+ * Bind a structural writer to one table, producing its `ctx.db` table accessor.
+ *
+ * The by-id accessors (`get`/`delete`/`patch`/`replace`) forward the bound
+ * `tableName` as `expectedTable` so the underlying writer scopes its id lookup
+ * to this table. Without it, a branded `Id<"posts">` carrying another table's
+ * id would resolve cross-table (the writer probes every table by id), letting
+ * `ctx.db.posts.get(foreignId)` read — or `.delete`/`.patch`/`.replace`
+ * mutate — a row in an unrelated table (IDOR). Writers that ignore the second
+ * argument keep their previous global behaviour; the scoping is opt-in via this
+ * forwarded name.
+ */
+declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) => FacadeEntry;
+/** The kitcn-style `ctx.orm` namespace over a per-table facade map. */
+interface OrmLike {
+  delete: (table: string, id: string) => Promise<void>;
+  insert: (table: string) => {
+    values: (document: Record<string, unknown>) => Promise<null | string>;
+  };
+  query: Record<string, FacadeEntry>;
+  replace: (table: string, id: string) => {
+    with: (document: Record<string, unknown>) => Promise<void>;
+  };
+  update: (table: string, id: string) => {
+    set: (values: Record<string, unknown>) => Promise<void>;
+  };
 }
+/** Build `ctx.orm` over a per-table facade map (table name → FacadeEntry). */
+declare const bindOrm: (facade: Record<string, FacadeEntry>) => OrmLike;
+/** HTTP verbs the typed {@link httpRoute} builder can bind to. */
+type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
 /**
- * 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`.
+ * Context handed to an HTTP action handler. A narrower view of {@link ActionContext}:
+ * HTTP actions run in the worker (the "action runtime"), separate from the
+ * transactional store, so there is no direct `db` / `vectors` surface — reach the
+ * data layer through `runQuery` / `runMutation` / `runAction`, which forward to
+ * the owning shard. `db`'s absence is principled: an HTTP handler is not
+ * transactional.
+ *
+ * `scheduler` and `storage` ARE present, because neither needs the shard — the
+ * scheduler talks to the scheduler DO, and R2 is a worker binding an HTTP
+ * handler can reach where an action does. Both are optional: each exists only
+ * when the app declared the matching capability (`.scheduler(...)` /
+ * `.storage(...)`) on the generated app builder.
+ *
+ * Omitting them was costly out of proportion to the gap. Without `scheduler`,
+ * "receive webhook → enqueue the real work → return 200" — the shape HTTP
+ * actions exist for — forced a hop through a mutation plus a closed allow-list
+ * of target strings, because a function reference cannot cross the RPC boundary
+ * and a free-form target on an unauthenticated endpoint is a "call any internal
+ * function" primitive. Without `storage`, any helper the ctx was threaded into
+ * had to be typed for its storage-touching branch, so a handler was barred from
+ * the helper even on the branches that never went near storage.
  */
-type 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;
+type HttpActionCtx = Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery"> & {
+  readonly scheduler?: ActionCtx["scheduler"];
+  readonly storage?: ActionCtx["storage"];
 };
-/** 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>;
+/** 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 prefixed tables a single plugin `P` contributes, or an empty map when it
- * ships no schema extension. Mirrors {@link PrefixedTables} at the plugin level
- * so {@link InstalledTables} can fold a tuple of plugins.
+ * The 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.
  */
-type ExtensionTablesOf<P> = P extends {
-  readonly extension: SchemaExtension<infer X> & {
-    readonly key: infer K;
+interface LunoraHttpEnv {
+  Bindings: Record<string, unknown> & {
+    __lunoraCtx?: HttpActionCtx;
   };
-} ? K extends string ? PrefixedTables<X, K> : Record<never, never> : Record<never, never>;
+  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>;
 /**
- * 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.
+ * 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`.
  */
-type InstalledTables<T extends Record<string, TableDefinition>, Plugins extends ReadonlyArray<unknown>> = Plugins extends readonly [infer Head, ...infer Rest] ? InstalledTables<ExtensionTablesOf<Head> & T, Rest> : T;
+declare const httpAction: (handler: HttpActionHandler) => LunoraRouteHandler;
 /**
- * Union every plugin's `ContextOut` in a tuple — the type-level mirror of the
- * `ctx.api.<key>` additions {@link composePluginMiddleware} accumulates as each
- * plugin middleware runs. Independent of the incoming context, which the builder
- * infers at the `.use(...)` site.
+ * 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.
  */
-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;
+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>;
+}
 /**
- * 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.
+ * The `{ ctx, searchParams, params, request, signal }` a streaming HTTP
+ * handler receives. There is no parsed `body` — streams are typically GET, and
+ * the raw `request` is exposed if a handler needs to read the body itself.
+ * `signal` is tripped when the client disconnects.
+ * @experimental Part of the HTTP-SSE stream surface; reconnect/POST-body design questions are still open.
  */
-interface SchemaExtension<T extends Record<string, TableDefinition> = Record<string, TableDefinition>> {
-  /** Stable key identifying the plugin that owns this extension. */
-  readonly key: string;
+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>;
   /**
-   * 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.
+   * Attach a `Cache-Control` header to the response. Only meaningful when
+   * Workers Cache is enabled in `wrangler.jsonc` (`"cache": { "enabled": true }`).
    */
-  readonly tables: T;
+  cacheControl: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
   /**
-   * 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).
+   * Attach a `Cache-Tag` header to the response for tag-based purging via
+   * `ctx.cache.purge({ tags: [...] })`.
    */
-  readonly vectorIndexes?: Record<string, VectorIndexDefinition>;
+  cacheTag: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+  handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
+  output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
+  params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
+  searchParams: <S extends ArgsValidator>(validators: S) => HttpRouteBuilder<S & SearchParams, Body, Params, Output>;
+  /**
+   * Terminal: declare this route as a streaming Server-Sent Events endpoint.
+   * The handler is an async generator (or any function returning an
+   * `AsyncIterable<R>`) that yields one chunk per SSE `data:` frame; on
+   * iterator completion the route writes a final `event: complete` frame; on
+   * throw, an `event: error` frame is written with `{code, message}` before
+   * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
+   * handler's yielded type.
+   * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+   */
+  stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+  /**
+   * Attach a `Vary` header to the response so Cloudflare stores separate
+   * cached variants per distinct value of the listed request headers.
+   */
+  vary: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+}
+/** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
+type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;
+/** The verb-keyed entry point: `httpRoute.get("/api/todos")…`. */
+interface HttpRoute {
+  delete: HttpRouteFactory;
+  get: HttpRouteFactory;
+  head: HttpRouteFactory;
+  options: HttpRouteFactory;
+  patch: HttpRouteFactory;
+  post: HttpRouteFactory;
+  put: HttpRouteFactory;
+}
+/**
+ * Typed REST route builder. Compiles down to a {@link LunoraRouteHandler}, so a
+ * typed route and a hand-written {@link httpAction} are interchangeable when
+ * mounted on {@link httpRouter}:
+ *
+ * ```ts
+ * export const listTodos = httpRoute
+ *     .get("/api/todos")
+ *     .searchParams({ limit: v.number(), q: v.optional(v.string()) })
+ *     .output(v.array(v.object({ id: v.string(), text: v.string() })))
+ *     .handler(async ({ ctx, searchParams }) => ctx.runQuery(api.todos.list, searchParams));
+ *
+ * export const getTodo = httpRoute
+ *     .get("/api/todos/:id")
+ *     .params({ id: v.string() })
+ *     .handler(async ({ ctx, params }) => ctx.runQuery(api.todos.get, params));
+ *
+ * const app = httpRouter();
+ * app.get("/api/todos", listTodos);
+ * app.get("/api/todos/:id", getTodo);
+ * ```
+ */
+declare const httpRoute: HttpRoute;
+/**
+ * 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;
 }
 /**
- * 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).
+ * The minimal storage surface {@link serveStorageObject} needs: a metadata-rich
+ * `download`, plus the body-free `head` a range request resolves against.
+ *
+ * `head` is required rather than optional-with-a-fallback because the fallback
+ * is the bug: without it a ranged request has to start a full-object `download`
+ * just to learn the size, then throw that body away. `@lunora/storage`'s `head`
+ * already degrades internally to a 0-length ranged `get()` on a binding with no
+ * HEAD, so there is nothing a caller here could usefully do that it does not.
  */
-interface Plugin<TExtension extends Record<string, TableDefinition> = Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn> {
-  /**
-   * Optional schema extension. Apps install via
-   * `defineSchema(...).extend(plugin.extension)`.
-   */
-  readonly extension?: SchemaExtension<TExtension>;
-  /** Stable key identifying the plugin. Matches `extension.key` when set. */
-  readonly key: string;
-  /**
-   * Optional middleware. Users attach with `c.query.use(plugin.middleware)`.
-   * The middleware can extend `ctx`; convention is to attach helpers under
-   * `ctx.api.<key>`, e.g.
-   *
-   * ```ts
-   * middleware: ({ ctx, next }) =>
-   *     next({ ctx: { api: { ...ctx.api, ratelimit: api } } })
-   * ```
-   */
-  readonly middleware?: Middleware<TContextIn, TContextOut>;
+interface StorageHead {
+  /** Object metadata with no body. `size` is the FULL object size (mirrors R2). */
+  head: (key: string) => Promise<Omit<StorageObjectBody, "body"> | null>;
 }
-/** Options to {@link definePlugin}. */
-interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>, TContextIn, TContextOut> {
-  extension?: SchemaExtension<TExtension>;
-  middleware?: Middleware<TContextIn, TContextOut>;
+/** The storage surface {@link serveStorageObject} reads through. */
+interface StorageDownloader extends StorageHead {
+  download: (key: string, options?: {
+    range?: StorageRange;
+  }) => Promise<StorageObjectBody | null>;
 }
-/**
- * Call signatures for {@link definePlugin}. When `extension` is supplied the
- * returned plugin's `extension` is typed as PRESENT (not `?`), so the
- * canonical install pattern `defineSchema(...).extend(plugin.extension)`
- * typechecks without a non-null assertion — the shape every scaffold template
- * ships. The bare-options signature keeps `extension` optional for plugins
- * that carry only middleware.
- */
-interface DefinePluginFunction {
-  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut> & {
-    extension: SchemaExtension<TExtension>;
-  }): Plugin<TExtension, TContextIn, TContextOut> & {
-    readonly extension: SchemaExtension<TExtension>;
-  };
-  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>): Plugin<TExtension, TContextIn, TContextOut>;
+/** Any ctx that carries a {@link StorageDownloader} on `.storage` (Query/Mutation/Action ctx all do). */
+interface ContextWithStorage {
+  storage: StorageDownloader;
 }
 /**
- * Package a schema extension + middleware as a reusable plugin. Either
- * field is optional — `definePlugin("foo", {})` is valid but degenerate.
+ * True when `value` is safe to use as an HTTP header field-value: no CR, LF, or
+ * NUL. Guards against response-header injection / `Headers`-construction throws
+ * when reflecting attacker-influenced object metadata (e.g. a stored
+ * `Content-Type`). Exported (see the `export {}` at the file end) so an `httpAction`
+ * handler can guard a request-derived header value before writing it — the fix the
+ * `http_action_response_header_injection` advisor lint points to.
  */
-declare const definePlugin: DefinePluginFunction;
+declare const isSafeHeaderValue: (value: string) => boolean;
 /**
- * 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`.
- * ```
+ * 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.
  *
- * 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.
+ * A range request resolves its window against a body-free `head()`, then issues
+ * ONE `download()` with the resolved `{ offset, length }` so R2 streams just
+ * those bytes — the slice is never buffered in the isolate, and no full-object
+ * body transfer is started only to be cancelled. A request that cannot produce a
+ * 206 at all (no `Range`, multi-range, malformed) skips the `head()` entirely and
+ * streams straight from a single `download()`. For very
+ * large objects a signed URL (`ctx.storage.getSignedUrl`) is still cheaper since
+ * the client then ranges against R2/CDN directly with no Worker hop.
  */
-type ComponentFunctions = Readonly<Record<string, RegisteredFunction<any, any, FunctionKind>>>;
+declare const serveStorageObject: (context: ContextWithStorage, key: string, request: Request) => Promise<Response>;
 /**
- * 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.
+ * What the worker does with a resolver's identity when it fails contract
+ * validation (a forged / malformed claim set arriving from an untrusted token).
+ * `"anonymous"` (default, safe) treats the request as anonymous, so the bad
+ * identity never reaches a policy as a valid identity (`ctx.auth.userId`
+ * becomes `undefined`). `"reject"` fails the request closed (a `401`) — use
+ * when a malformed credential should be a hard error, not a silent downgrade.
  */
-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;
+type IdentityRejectMode = "anonymous" | "reject";
+/** Options for {@link defineIdentity}. */
+interface DefineIdentityOptions {
+  /**
+   * How to handle a resolver identity that violates the contract at the trust
+   * boundary. Defaults to `"anonymous"` (a forged claim set is downgraded to
+   * anonymous rather than flowing in as an unchecked cast).
+   */
+  readonly onInvalid?: IdentityRejectMode;
 }
+/** Result of validating a candidate identity against the contract. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
 /**
- * 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.
+ * A declared identity claim contract. Carries the codegen discovery brand, the
+ * declared claim validators, the reject policy, and a runtime `validate`. The
+ * `TClaims` type parameter is the inferred claim shape (always extending
+ * `{ userId: string }`); it is phantom (no runtime field) and exists so
+ * `@lunora/codegen` and {@link InferIdentity} can recover the type.
  */
-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>;
+interface IdentityContract<TClaims extends {
+  userId: string;
+} = {
+  userId: string;
+}> {
+  /**
+   * Phantom carrier for the inferred claim type. Never populated at runtime
+   * (`undefined`); present only so the type flows to codegen / {@link InferIdentity}.
+   */
+  readonly __claimType?: TClaims;
+  readonly __lunoraIdentity: true;
+  /** The declared claim validators (a `@lunora/values` validator map). */
+  readonly claims: ValidatorMap;
+  /** Reject policy applied at the trust boundary. See {@link IdentityRejectMode}. */
+  readonly onInvalid: IdentityRejectMode;
+  /**
+   * Validate a resolver's returned identity against the declared claims. On
+   * success the caller keeps the original identity untouched (so undeclared
+   * claims are forwarded verbatim, preserving today's behaviour); on failure
+   * the worker applies the `onInvalid` policy.
+   */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/** Recover the declared claim type from a {@link defineIdentity} contract. */
+type InferIdentity<T> = T extends IdentityContract<infer TClaims> ? TClaims : never;
 /**
- * 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.
+ * Declare the identity claim contract. `claims` is a `@lunora/values` validator
+ * map whose inferred type must extend `{ userId: string }` — if it does not
+ * (e.g. `userId` is missing or not a required string), the argument type
+ * collapses to `never` and the call fails to typecheck.
+ * @example
+ * export const identity = defineIdentity({ userId: v.string(), tenantId: v.optional(v.string()), scopes: v.optional(v.array(v.string())) });
  */
-type PrefixedTables<X extends Record<string, TableDefinition>, Key extends string> = { [K in keyof X as K extends string ? `${Key}_${K}` : K]: X[K]; };
+declare const defineIdentity: <A extends ValidatorMap>(claims: InferValidatorMap<A> extends {
+  userId: string;
+} ? A : never, options?: DefineIdentityOptions) => IdentityContract<InferValidatorMap<A> & {
+  userId: string;
+}>;
+/** Handler for a connection-lifecycle hook. */
+type LifecycleHandler = (context: MutationCtx, event: LifecycleEvent) => Promise<void> | void;
+/** Handler for a shard-init hook. */
+type ShardInitHandler = (context: MutationCtx, event: ShardInitEvent) => Promise<void> | void;
+/** Register a hook that fires once when a client's WebSocket connects. */
+declare const onConnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
+/** Register a hook that fires once when a client's WebSocket disconnects. */
+declare const onDisconnect: (handler: LifecycleHandler) => RegisteredLifecycleHook;
 /**
- * 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.
+ * Register a hook that fires ONCE per Durable Object instance, before any
+ * handler on that instance can run — the re-init half of `.memory()` tables.
  *
- * Re-runs {@link validateIndexFields} against the merged table set before
- * returning: `defineSchema` only validates the tables it was called with, so
- * without this an extension-contributed index with a typo'd/out-of-shape
- * field (or a duplicate name within one kind) would never be checked at all.
- * Re-validating the whole merged set (base + prefixed extension tables) is
- * cheap and idempotent for the base tables, which already passed this same
- * check when the base schema was built. Both callers of this function —
- * `withExtend.extend()` (`./schema`) and `installPlugins` (below) — get the
- * re-validation for free from this single call site (plan 258 §4/§9 Q3).
- */
-declare const mergeSchemaExtension: <T extends Record<string, TableDefinition>, X extends Record<string, TableDefinition>, Key extends string = string>(base: Schema<T>, extension: SchemaExtension<X> & {
-  readonly key: Key;
-}) => Schema<PrefixedTables<X, Key> & T>;
-/**
- * Install several plugins' schema extensions in one call — the one-shot
- * counterpart to chaining `defineSchema(...).extend(a).extend(b)`. Plugins
- * without an `extension` (middleware-only) are skipped; tables from those that
- * do are auto-prefixed and reference-rewritten exactly as
- * {@link mergeSchemaExtension} does for a single `.extend(...)`.
+ * A shard is not a process that stays up. Cloudflare reconstructs the Durable
+ * Object after every eviction, and a shard whose sockets are hibernating is
+ * evicted routinely, so "cold start" is a steady-state event rather than a rare
+ * one. Everything the shard held in memory is gone at that moment: the JS heap,
+ * and every `.memory()` table, which the framework has already cleared by the
+ * time this hook runs.
  *
  * ```ts
- * const schema = installPlugins(defineSchema({ todos }), [ratelimit, audit]);
- * // → todos + ratelimit_* + audit_*
+ * // lunora/init.ts
+ * import { onShardInit } from "@lunora/server";
+ *
+ * export const warm = onShardInit(async (ctx, event) => {
+ *     // Rebuild ephemeral state from the durable tables that outlived us.
+ *     for await (const member of ctx.db.roomMembers.iterate({ where: { roomId: event.shardKey } })) {
+ *         await ctx.db.presence.insert({ userId: member.userId, status: "away" });
+ *     }
+ * });
  * ```
  *
- * 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.<key>`
- * additions. Equivalent to `.use(a.middleware).use(b.middleware)…` but as one
- * value, the middleware sibling of {@link installPlugins}.
+ * **Ordering is the guarantee.** Memory tables are cleared, then every init hook
+ * runs to completion, and only then does the dispatch that triggered the cold
+ * start proceed. No handler, subscription refresh, alarm, or shape poke can
+ * observe a memory table in the gap. Hooks run sequentially in manifest order,
+ * so one may depend on state an earlier one wrote.
  *
- * `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.
+ * **It is a mutation, and it runs on every cold start.** Keep it cheap and keep
+ * it idempotent: it is on the latency path of the request that woke the shard,
+ * and it will run again — many times — over the shard's life. Writing to durable
+ * tables from here is legal and occasionally right, but remember it is a
+ * rebuild, not a migration; use `defineMigration` for anything that should
+ * happen once.
+ *
+ * **No caller identity.** The hook dispatches as a trusted system call with no
+ * request identity — `ctx.auth` is anonymous and RLS does not apply even under
+ * `.rls("required")`, exactly as for a cron tick or a migration. RLS scopes rows
+ * to a user and an init hook has none, so `ctx.db` here sees every row: scope
+ * your reads yourself. (`onConnect`/`onDisconnect` are the opposite case — they
+ * carry the socket's verified identity and stay RLS-guarded.)
+ *
+ * A throw is logged and does NOT fail the dispatch that woke the shard — an init
+ * hook that cannot rebuild presence must not take the whole shard down with it.
+ * The table is then cleared but not refilled, so reads see nothing. A failure
+ * EARLIER, before the framework's clear runs, instead leaves the previous
+ * instance's rows in place: a memory table's rows live in SQLite until they are
+ * deleted, so an eviction on its own does not remove them.
  */
-declare const 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>;
-}
+declare const onShardInit: (handler: ShardInitHandler) => RegisteredLifecycleHook;
+/** Default `limit` when the caller doesn't ask for one. */
+declare const DEFAULT_LIMIT = 25;
+/** Default ceiling on `limit`, so one request can't ask for an unbounded page. */
+declare const DEFAULT_MAX_LIMIT = 100;
 /**
- * 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.
+ * Per-field predicate accepted for a declared filter column. An alias of the
+ * `ctx.db` `where` DSL's own operator type rather than a copy, so the two cannot
+ * drift as operators are added.
  */
-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>;
-}
+type ListFilterOperators<T> = WhereOperators<T>;
 /**
- * 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.
+ * The filter allow-list a caller may declare: a subset of the document's own
+ * columns, each with a validator for that column's type. Constraining the KEYS to
+ * `keyof Doc` is what turns a typo'd or renamed column into a compile error
+ * instead of a predicate that silently never matches.
  */
-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>;
+type ListFilterShape<TDocument> = { [K in keyof TDocument & string]?: Validator<TDocument[K]>; };
+/** The `where` argument: each declared filter column, optionally, as a bare value or an operator object. */
+type ListWhere<F> = { [K in keyof F]?: Infer<NonNullable<F[K]>> | ListFilterOperators<Infer<NonNullable<F[K]>>>; };
+/** One `orderBy` entry. `direction` defaults to `"asc"`. */
+interface ListOrderByEntry<O extends string> {
+  direction?: "asc" | "desc";
+  field: O;
 }
-interface TableBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> extends TableDefinition<Shape> {
-  /** Declare an aggregate (counter/sum/…) maintained by triggers for O(1) reads. */
-  aggregateIndex: (name: string, options?: InlineAggregateIndexOptions<Shape>) => TableBuilder<Shape>;
-  /**
-   * Stamp every row with `_commitSeq` — a per-shard integer, allocated once
-   * per mutation and strictly increasing in **commit order**, refreshed on
-   * every write to the row (insert, patch, replace, and the marker flip a
-   * `.softDelete()` performs).
-   *
-   * `_creationTime` is wall-clock and therefore cannot order commits: the
-   * clock is read when the handler runs, the write lands when the transaction
-   * commits, and nothing ties those instants together. A changefeed paging on
-   * `_creationTime` can skip a row permanently. Paging on `_commitSeq`
-   * (`where: { _commitSeq: { gt: cursor } }, orderBy: ["_commitSeq"]`) cannot.
-   *
-   * It orders COMMITS, not rows: one mutation's rows share a value. A bounded
-   * page can therefore end mid-group, so a consumer must checkpoint at a
-   * sequence it has seen the whole of, never at the last row of a full page.
-   * An action's writes are the exception to the grouping — they commit
-   * independently, so each gets its own sequence.
-   *
-   * Ordered, not contiguous — read a gap as "nothing to see", never as loss.
-   * Per-shard, not global: two shards allocate independently, so a cursor is
-   * only meaningful against the shard it came from. Rejected on `.global()`
-   * tables, which have no shard-local transaction to allocate inside.
-   *
-   * **A hard delete is invisible to the feed.** The sequence lives on the row,
-   * so a physically removed row takes it along: the row stops appearing, but
-   * no event says it went away. Pair `.commitOrdered()` with `.softDelete()`
-   * when the feed must observe deletes — the tombstone flip is an UPDATE, so
-   * it advances the sequence and pages through like any other change.
-   */
-  commitOrdered: () => TableBuilder<Shape>;
-  /**
-   * Mark this table as written outside Lunora's discoverable insert path —
-   * by an adapter, a migration, or framework middleware (e.g. `@lunora/auth`'s
-   * better-auth tables, `@lunora/ratelimit`'s store). Advisor insert-path lints
-   * (`table_without_insert`) then skip it instead of flagging the absent
-   * `ctx.db.insert(...)`.
-   */
-  externallyManaged: () => TableBuilder<Shape>;
-  /**
-   * Declare a geospatial index over a `v.geoPoint()` column. The runtime keeps
-   * a geohash companion so `withGeoIndex(name, q => q.near(point, radius))` and
-   * `.within(bbox)` resolve as a geohash-prefix range scan + Haversine
-   * refine/sort. `options.precision` tunes the geohash length (default 9).
-   */
-  geoIndex: (name: string, options: {
-    field: keyof Shape & string;
-    precision?: number;
-  }) => TableBuilder<Shape>;
-  /**
-   * Mark this table as global (cross-shard). Backed by **D1** by default;
-   * pass `{ backend: "hyperdrive" }` to store it in a Postgres/MySQL database
-   * via Cloudflare Hyperdrive (PlanetScale, Neon, …) instead. Either way the
-   * table stays reactive — live queries re-run on write.
-   */
-  global: (options?: {
-    backend?: GlobalBackend;
-  }) => TableBuilder<Shape>;
-  /** Add a secondary index. */
-  index: (name: string, fields: ReadonlyArray<(keyof Shape & string) | (typeof SYSTEM_INDEX_FIELDS)[number]>, options?: {
-    unique?: boolean;
-  }) => TableBuilder<Shape>;
+/** The decoded arguments a {@link defineListArgs} endpoint receives. */
+interface ListArgsValue<F, O extends string> {
+  cursor?: null | number | string;
+  limit?: number;
+  orderBy?: ListOrderByEntry<O>[];
+  where?: ListWhere<F>;
+}
+interface DefineListArgsConfig<F, O extends string> {
+  /** `limit` applied when the caller omits one. Defaults to 25. */
+  readonly defaultLimit?: number;
   /**
-   * Declare this table EPHEMERAL — state the shard rebuilds rather than
-   * remembers.
-   *
-   * A memory table is a full `ctx.db` table: indexes, `where`, `orderBy`,
-   * pagination, relations, live queries. What it is not is durable. Its rows
-   * are wiped the moment the Durable Object is reconstructed — which happens
-   * on every eviction, and a WebSocket-hibernating shard is evicted often — so
-   * a memory table holds only what can be derived again: presence and cursors,
-   * a live participant list, a rate-limit window, an actor's scratch state.
-   *
-   * Pair it with `onShardInit` to rebuild whatever the app needs present.
-   * The framework guarantees the ordering: every memory table is cleared, and
-   * every init hook has run, before any handler can read one. Without a hook a
-   * memory table simply comes back empty, which is a correct state for
-   * presence and a wrong one for a cache someone is treating as authoritative.
-   *
-   * **On Cloudflare the rows still transit the DO's SQLite.** workerd exposes
-   * exactly one SQL handle and no memory-backed database, so `.memory()` buys
-   * the LIFETIME (and skips the CDC changelog, so an append-heavy presence
-   * table does not grow the op-log), not the write. Treat it as "state I am
-   * happy to lose", not as "state that is free to write" — see
-   * `PlatformCapabilities.memoryTables`, rated `emulated` for exactly this
-   * reason.
-   *
-   * Rejected alongside `.global()` (a D1 table is not this shard's to clear),
-   * `.commitOrdered()` (a sequence that resets is not a sequence), and
-   * `.source()` (an externally-materialized table is not ours to wipe).
+   * Allow-list of filterable columns. Publish only columns an index can serve;
+   * anything absent here is unreachable from the client.
    */
-  memory: () => TableBuilder<Shape>;
+  readonly filter: F;
+  /** Ceiling on `in` / `notIn` array length — one bound parameter each. Defaults to 100. */
+  readonly maxInValues?: number;
+  /** Ceiling on `limit`; a larger request is clamped down, not rejected. Defaults to 100. */
+  readonly maxLimit?: number;
+  /** Ceiling on how many `orderBy` entries a request may ask for. Defaults to 8. */
+  readonly maxOrderBy?: number;
+  /** Allow-list of sortable columns. Pass `[]` to fix the order server-side. */
+  readonly orderBy: ReadonlyArray<O>;
+}
+/** The validator map handed to `.input()`. Typed precisely so `args` infers end-to-end. */
+interface ListArgsValidators<F, O extends string> {
+  cursor: ColumnValidator<null | number | string | undefined, null | number | string | undefined>;
+  limit: ColumnValidator<number | undefined, number | undefined>;
+  orderBy: ColumnValidator<ListOrderByEntry<O>[] | undefined, ListOrderByEntry<O>[] | undefined>;
+  where: ColumnValidator<ListWhere<F> | undefined, ListWhere<F> | undefined>;
+}
+interface ListArgsSpec<TDocument, F, O extends string> {
+  /** Spread into `.input(...)` — `{ cursor, limit, orderBy, where }`. */
+  readonly args: ListArgsValidators<F, O>;
   /**
-   * Name the column holding the owning user's id, so "only the owner sees these
-   * rows" is declared once here rather than restated in every shape.
-   *
-   * A `defineShape({ table, owner: true })` over this table derives its predicate
-   * from the field: the subscriber's verified `ctx.auth.userId` must match, and an
-   * anonymous subscriber is denied. Pairs naturally with `.shardBy(field)` on the
-   * same column — the shard key routes the storage, `ownedBy` states who the rows
-   * belong to — but the two are independent and either can be used alone.
+   * Translate the decoded arguments into the `findMany` options object:
+   * `limit` clamped into `[1, maxLimit]`, `orderBy` reshaped from
+   * `{ field, direction }[]` into `ctx.db`'s `{ column: direction }[]`.
    *
-   * This is a *shape* declaration, not an RLS policy: it narrows what a shape
-   * replicates. Guarding procedure reads/writes is still `rls(...)`'s job.
+   * Returns `QueryArgs<Doc>` — bound to the table, not free — so a mismatch
+   * between what this helper declares and what the table actually holds is a
+   * compile error at the `findMany` call site.
    */
-  ownedBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  readonly toQueryArgs: (args: ListArgsValue<F, O>) => QueryArgs$2<TDocument>;
+}
+/** Clamp a caller-supplied `limit` into `[1, maxLimit]`; a non-finite value falls back to `fallback`. */
+declare const clampLimit: (limit: number | undefined, fallback: number, maxLimit: number) => number;
+/**
+ * Declare the filter / sort / page arguments for a list endpoint, plus the
+ * translation into `ctx.db.<table>.findMany(...)` options. See the module docs
+ * for the shape and the reasoning behind it.
+ *
+ * Curried on the document type: `defineListArgs<Doc<"messages">>()({ … })`. The
+ * extra `()` buys the thing that matters — with `Doc` bound, `filter` keys and
+ * `orderBy` entries are checked against the table's real columns, so a typo or a
+ * column renamed out from under the endpoint is a COMPILE error instead of a
+ * predicate that silently matches nothing. TypeScript has no partial type-argument
+ * inference, so binding `Doc` explicitly while still inferring `F` and `O` from
+ * the config requires the second call.
+ */
+declare const defineListArgs: <TDocument>() => <F extends ListFilterShape<TDocument>, O extends keyof TDocument & string>(config: DefineListArgsConfig<F, O>) => ListArgsSpec<TDocument, F, O>;
+/**
+ * Structural mirrors of `@lunora/shard-engine`'s rank-page-row shapes
+ * (`RankPageRowKey` / `RankPageRow` / `ShardRankPageResult`) — the return type
+ * of the writer's `rankPageRows` seam, the cross-shard companion to
+ * `rankPage`.
+ *
+ * Shared by `../rls/middleware` and `../mask/middleware`: both wrap
+ * `rankPageRows` structurally (no `@lunora/shard-engine` import, mirroring how
+ * every other method on their `DatabaseWriterLike`/`MaskDatabase` projections
+ * is hand-mirrored rather than imported) and both need the exact same result
+ * shape to type their overrides. A single copy here means the two wrappers
+ * can't drift out of lockstep with each other — see AGENTS.md's platform
+ * parity note on `ShardSqlExec` and the canonical binding `*Like` projections
+ * shipping wrong for exactly this reason (two hand-maintained mirrors of one
+ * upstream type).
+ */
+/** Structural mirror of `@lunora/shard-engine`'s `RankPageRowKey`. */
+interface RankPageRowKeyLike {
+  partitionKey: string;
+  rowId: string;
+  sortValues: ReadonlyArray<unknown>;
+}
+/** Structural mirror of `@lunora/shard-engine`'s `RankPageRow`. */
+interface RankPageRowLike {
+  doc: Record<string, unknown>;
+  key: RankPageRowKeyLike;
+}
+/** Structural mirror of `@lunora/shard-engine`'s `ShardRankPageResult` — the `rankPageRows` return shape. */
+interface ShardRankPageResultLike {
+  directions: ReadonlyArray<"asc" | "desc">;
+  hasMore: boolean;
+  rows: ReadonlyArray<RankPageRowLike>;
+}
+/**
+ * Structural mirror of `@lunora/do`'s `QueryArgs` and `CountArgs`. The
+ * runtime ORM in `@lunora/do`/`@lunora/d1` reads `baseWhere` /
+ * `restrictsCounts` straight off these option objects, so as long as the
+ * fields here stay name-compatible the wrapper is portable across the two
+ * dialects without an inter-package dependency.
+ */
+interface QueryArgs$1 {
+  baseWhere?: WhereInput;
+  cursor?: null | string;
+  limit?: number;
+  orderBy?: ReadonlyArray<unknown>;
   /**
-   * 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.
+   * 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`.
    */
-  public: () => TableBuilder<Shape>;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+  with?: Record<string, unknown>;
+}
+interface CountArgs {
+  baseWhere?: WhereInput;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `AggregateOptions` — only the fields the wrapper touches. */
+interface AggregateArgs$1 {
+  baseWhere?: WhereInput;
+  field?: string;
+  op: string;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `GroupByOptions`. */
+interface GroupByArgs$1 {
+  agg?: {
+    field?: string;
+    op: string;
+  };
+  baseWhere?: WhereInput;
+  by: ReadonlyArray<string>;
+  relationBaseWhere?: (table: string) => undefined | WhereInput;
+  restrictsCounts?: boolean;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankOptions`. */
+interface RankArgs {
+  baseWhere?: WhereInput;
+  restrictsCounts?: boolean;
+  row: Record<string, unknown> | string;
+  where?: WhereInput;
+}
+/** Structural mirror of `@lunora/do`'s `RankBeforeOptions`. */
+interface RankBeforeArgs {
+  partitionKey: string;
+  restrictsCounts?: boolean;
+  rowId: string;
+  sortValues: ReadonlyArray<unknown>;
+}
+/** Structural mirror of `@lunora/do`'s `RankPageOptions`. */
+interface RankPageArgs {
+  baseWhere?: WhereInput;
+  cursor?: null | string;
+  restrictsCounts?: boolean;
+  take?: number;
+  where?: WhereInput;
+}
+interface QueryPage$1 {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
+}
+interface TableReaderLike$1 {
+  collect: () => Promise<Record<string, unknown>[]>;
+  filter: (predicate: (document: Record<string, unknown>) => boolean) => TableReaderLike$1;
+  first: () => Promise<Record<string, unknown> | null>;
+  paginate: (options: {
+    cursor?: null | string;
+    numItems: number;
+  }) => Promise<QueryPage$1>;
+  take: (limit: number) => Promise<Record<string, unknown>[]>;
+  withGeoIndex: (indexName: string, build: (q: unknown) => unknown) => TableReaderLike$1;
+  withIndex: (indexName: string, range?: (q: unknown) => unknown) => TableReaderLike$1;
+  withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => TableReaderLike$1;
+}
+/**
+ * Structural projection of the runtime ORM writer. The wrapper relies only
+ * on these fields, so it's interchangeable between `@lunora/do`'s
+ * `DatabaseWriterLike` and `@lunora/d1`'s `DatabaseWriterLike`.
+ */
+interface DatabaseWriterLike {
   /**
-   * Declare a rank index (sorted companion table, btree-backed) for
-   * `rank(row)` / `rankPage()` reads in O(log n). See {@link RankIndexDefinition}.
+   * 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.
    */
-  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>;
+  aggregate: (tableName: string, options: AggregateArgs$1) => Promise<null | number>;
+  count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
+  delete: (id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }) => Promise<void>;
+  /** Uncapped, chunked erase of a whole table. The RLS wrapper gates each row like a single delete. */
+  deleteAll?: (tableName: string, options?: {
+    chunkSize?: number;
+    hard?: boolean;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  deleteMany: (ids: ReadonlyArray<string>, options?: {
+    limit?: number;
+  }, expectedTable?: string) => Promise<{
+    deleted: number;
+  }>;
+  deleteWhere?: (tableName: string, where: WhereInput, options?: {
+    limit?: number;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  findFirst: (tableName: string, args?: QueryArgs$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>;
   /**
-   * Add a full-text search index over `field`, queried with
-   * `.withSearchIndex(name, q => q.search(field, term))`. `field` may be a
-   * dot-separated path into a nested object (`"properties.name"`).
-   * `filterFields` (at most 16) lists the columns `.eq()` may narrow by inside
-   * the search. `language` selects the text analysis (accent folding always,
-   * plus that language's stopwords). `staged: true` skips the migration-time
-   * backfill on a large existing table — pre-existing rows stay unsearchable
-   * until `__lunora_admin__:backfillSearch` is run against the deployment. `strategy: "native"` uses the engine's
-   * own full-text index where it has one (Postgres) — faster on large corpora,
-   * at the cost of the engine ranking rather than the shared scorer.
+   * 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`.
    */
-  searchIndex: (name: string, options: {
-    field: string;
-    filterFields?: ReadonlyArray<string>;
-    language?: SearchLanguage;
-    staged?: boolean;
-    strategy?: SearchStrategy;
-  }) => TableBuilder<Shape>;
-  /** Route storage by the named field — one DO per distinct value. */
-  shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  groupBy: (tableName: string, options: GroupByArgs$1) => Promise<ReadonlyArray<{
+    key: Record<string, unknown>;
+    value: null | number;
+  }>>;
+  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
+  insertMany: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    limit?: number;
+    skipDuplicates?: boolean;
+  }) => Promise<(string | null)[]>;
+  insertManyUnsafe: (tableName: string, documents: ReadonlyArray<Record<string, unknown>>, options?: {
+    allowExplicitId?: boolean;
+    limit?: number;
+  }) => Promise<string[]>;
   /**
-   * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
-   * default `deletedAt`) and changes `ctx.db.<table>.delete()` to **set** it
-   * instead of removing the row; `onDelete: "cascade"` children are recursively
-   * soft-deleted too. **List reads** (`findMany`/`findFirst`/`query()`/`count`/
-   * `aggregate`/relation loads) then hide soft-deleted rows unless they pass
-   * `includeDeleted: true`; by-id `get`/`patch`/`replace` and the new
-   * `restore()` still address the row directly. `hardDelete()` physically
-   * removes it (cascading as a real delete). Note: `includeDeleted` is a read
-   * scope, not access control — anyone who can run the read can set it; a unique
-   * index still rejects a new row that collides with a soft-deleted one (the row
-   * physically persists).
+   * 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.
    */
-  softDelete: (options?: {
-    field?: string;
-  }) => TableBuilder<Shape>;
+  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<{
+    patched: number;
+  }>;
+  patchWhere?: (tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: WhereInput;
+  }, options?: {
+    limit?: number;
+  }) => Promise<{
+    patched: number;
+  }>;
+  query: (tableName: string) => TableReaderLike$1;
   /**
-   * 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()`.
+   * 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`.
    */
-  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>;
+  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;
+  }>;
   /**
-   * Declare a table-level TTL: a DO alarm-driven sweep auto-deletes rows whose
-   * expiry has passed (or soft-deletes them when the table also
-   * `.softDelete()`s). `field` is an epoch-millisecond column; without
-   * `options.after` its value is the absolute expiry instant, with `after` the
-   * row expires `after` ms past `field` (`field + after`). Coarse, cheap,
-   * table-level — for per-row schedules use `@lunora/scheduler`.
+   * 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`.
    */
-  ttl: (field: keyof Shape & string, options?: {
-    after?: number;
-  }) => TableBuilder<Shape>;
-  /** Declare a vector index over a single text field on this table. */
-  vectorize: (field: keyof Shape & string, options: VectorizeOptions<Shape>) => TableBuilder<Shape>;
-}
-/** Options for `defineVectorIndex(...)` (DSL Shape B). */
-interface VectorIndexOptions {
-  dimensions: number;
-  embed: VectorEmbedder;
-  /** Optional projection of the source row into Vectorize metadata. */
-  metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
-  metric: VectorMetric;
-  /** The vector source: which table, and how to derive the embedded text. */
-  source: {
-    select: (row: Record<string, unknown>) => string;
-    table: string;
-  };
-}
-/**
- * Build a table definition. Returned object is both the table definition (for
- * `defineSchema`) and a fluent builder for indexes + sharding metadata.
- */
-declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
-/**
- * Declare a standalone vector index (DSL Shape B). Pass the returned value in
- * the `vectorIndexes` map of {@link defineSchema} when the source is derived
- * from multiple fields or a computation rather than a single column.
- */
-declare const defineVectorIndex: (options: VectorIndexOptions) => VectorIndexDefinition;
-/**
- * Options for the standalone `defineAggregateIndex(name, opts)` helper (DSL
- * Shape B). Unlike the inline `.aggregateIndex(...)` builder, this form takes
- * the owning table explicitly via `on` — handy when a single counter wants to
- * live next to the schema map rather than inside a table chain.
- */
-interface AggregateIndexOptions {
-  by?: ReadonlyArray<string>;
-  field?: string;
-  on: string;
-  op?: AggregateOp;
-  where?: Record<string, unknown>;
-}
-/**
- * Declare a standalone aggregate index. Pass the returned value to
- * `defineSchema(tables, vectorIndexes, aggregateIndexes)` keyed by index name —
- * the schema attaches it to `tables[on].aggregateIndexes` so runtime consumers
- * (DO + D1) read every index uniformly off the table definition.
- */
-declare const defineAggregateIndex: (name: string, options: AggregateIndexOptions) => AggregateIndexDefinition;
-/**
- * Options for the standalone `defineRankIndex(name, opts)` helper (DSL Shape B).
- * Mirrors the inline `.rankIndex(...)` builder but takes the owning table via
- * `table` so it can sit next to the schema map.
- */
-interface RankIndexOptions {
-  partitionBy?: ReadonlyArray<string>;
-  sortBy: ReadonlyArray<{
-    direction?: "asc" | "desc";
-    field: string;
-  }>;
-  table: string;
-  where?: Record<string, unknown>;
-}
-/**
- * Declare a standalone rank index. Pass the returned value to
- * `defineSchema(tables, vectorIndexes, aggregateIndexes, rankIndexes)` keyed
- * by index name — the schema attaches it to `tables[on].rankIndexes`.
- */
-declare const defineRankIndex: (name: string, options: RankIndexOptions) => RankIndexDefinition;
-/**
- * Build the application schema. The first argument is the table map; the
- * optional second argument registers standalone `defineVectorIndex(...)`
- * declarations (DSL Shape B) keyed by index name. The optional third argument
- * registers standalone `defineAggregateIndex(...)` declarations (DSL Shape B);
- * the optional fourth argument registers standalone `defineRankIndex(...)`
- * declarations. Both are folded into the matching `tables[on].*Indexes` array
- * so runtime backends read every index uniformly off the table definition.
- */
-/**
- * Schema with an in-place `.extend(plugin.extension)` method. Used so apps
- * can compose plugin schemas: `defineSchema({...}).extend(authPlugin.extension)`.
- *
- * `extend` is non-mutating — returns a fresh `ExtendableSchema` containing
- * the merged tables. Extension tables are auto-namespaced by the extension
- * `key` (`buckets` → `ratelimit_buckets`), so the merged type carries the
- * prefixed names via {@link PrefixedTables}. Chains:
- * `defineSchema(...).extend(a).extend(b)` is the typed equivalent of merging
- * `a`'s prefixed tables then `b`'s.
- */
-type ExtendableSchema<T extends Record<string, TableDefinition>> = {
-  extend: <X extends Record<string, TableDefinition>, Key extends string>(extension: SchemaExtension<X> & {
-    readonly key: Key;
-  }) => ExtendableSchema<PrefixedTables<X, Key> & T>;
+  rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage$1>;
   /**
-   * 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/
+   * Cross-shard companion to `rankPage`: same ranked slice, but each row
+   * keeps its rank-key tuple for the query coordinator's k-way merge. Same
+   * count-of-partition RLS hazard as `rankPage` — failed closed under a read
+   * policy for the identical reason (see `rankPage` above).
    */
-  jurisdiction: (jurisdiction: DurableObjectJurisdiction) => ExtendableSchema<T>;
+  rankPageRows?: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<ShardRankPageResultLike>;
+  replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
   /**
-   * 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.
+   * Whole-shard erase. The RLS wrapper deliberately **fails this closed** rather
+   * than wrapping it — see the wrapper's `wipeShard`.
    */
-  rls: (mode: "required") => ExtendableSchema<T>;
-} & Schema<T>;
-/**
- * Columns every row carries implicitly (never part of a table's declared
- * `shape`), so `.index()` may legitimately name them. The single source for
- * both the compile-time allow-list (`TableBuilder["index"]`'s `fields` type,
- * via `(typeof SYSTEM_INDEX_FIELDS)[number]`) and the runtime cross-check
- * below (via `SYSTEM_INDEX_FIELDS_SET`) — declared once so the two can't
- * drift apart.
- */
-declare const SYSTEM_INDEX_FIELDS: readonly ["_commitSeq", "_creationTime", "_id"];
+  wipeShard?: (options?: {
+    chunkSize?: number;
+    exclude?: ReadonlyArray<string>;
+    tables?: ReadonlyArray<string>;
+  }) => Promise<{
+    deleted: number;
+    tables: Record<string, number>;
+  }>;
+}
 /**
- * Per-table, per-KIND index→declared-fields map: for each table, each index
- * KIND (`index` | `rank` | `geo`) that has at least one declared index maps
- * to a name→fields record for that kind only. Distilled by
- * {@link indexFieldsFromSchema}; this is the shape `mask()`'s
- * `MaskOptions.indexFields` expects (see `./mask/types`), so a table not
- * present here (no declared indexes of any kind) is simply absent from the
- * map rather than mapped to `{}`, and a kind with no declared indexes on a
- * table that HAS other kinds is simply absent from that table's entry.
- *
- * Kept per kind (rather than one flat name→fields record) because the engine
- * resolves `withIndex`/`withGeoIndex`/rank reads in THREE separate
- * namespaces (`tableDefinition.indexes` / `.geoIndexes` / `.rankIndexes` —
- * see `@lunora/shard-engine`'s `ctx-db.ts`), so the same name can legally and
- * unambiguously denote a different index per kind. A flat map would let one
- * kind's fields silently shadow another's for a colliding name, producing a
- * wrong-namespace answer from the mask guard (checking the wrong index's
- * fields) instead of the documented fail-open (missing lookup) — see plan 258.
+ * 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 IndexFieldsByTable = Readonly<Record<string, {
-  readonly geo?: Readonly<Record<string, ReadonlyArray<string>>>;
-  readonly index?: Readonly<Record<string, ReadonlyArray<string>>>;
-  readonly rank?: Readonly<Record<string, ReadonlyArray<string>>>;
-}>>;
-declare const indexFieldsFromSchema: (schema: Schema) => IndexFieldsByTable;
-declare const defineSchema: <T extends Record<string, TableDefinition>>(tables: T, vectorIndexes?: Record<string, VectorIndexDefinition>, aggregateIndexes?: Record<string, AggregateIndexDefinition>, rankIndexes?: Record<string, RankIndexDefinition>) => ExtendableSchema<T>;
+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>;
 /**
  * Context handed to a {@link MaskFn} (and to {@link MaskOptions.bypass}). The
  * `auth` shape mirrors RLS's `PolicyContext.auth` one-for-one — same identity
@@ -2858,4 +2964,4 @@ interface StorageContextIn {
 }
 declare const storageRules: <Context extends StorageContextIn = StorageContextIn>(rules: ReadonlyArray<StorageRule<Context>>, options?: StorageRulesOptions) => Middleware<Context, Context>;
 declare const VERSION = "0.0.0";
-export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, type DataModelInit, type DeferredDeleteFlushResult, type DefineComponentOptions, type DefineIdentityOptions, type DefineListArgsConfig, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type DurableObjectJurisdiction, type DurableStreamOptions, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExposeConfig, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type IdentityContract, type IdentityRejectMode, type IdentityValidation, type IndexFieldsByTable, type InferArgs, type InferEnv, type InferIdentity, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type ListArgsSpec, type ListArgsValidators, type ListArgsValue, type ListFilterOperators, type ListOrderByEntry, type ListWhere, type LunoraBuilders, LunoraEnvError, LunoraError, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskRegistry, type MaskStrategy, type Middleware, type MiddlewareNext, type MigrationCtx, type MigrationDefinition, type MigrationDocument, type MigrationReader, type MigrationTransform, type MutationBuilder, type MutationCtx, type MutatorDefinition, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type ReactorHandler, type ReactorOutcome, type ReactorSelect, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredMutator, type RegisteredQuery, type RegisteredReactor, type RegisteredShape, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type RlsReadRegistry, type Role, type Schema, type SchemaExtension, type ShapeDefinition, type ShapeReadWhereRequest, type ShardInitEvent, type ShardInitHandler, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, allowAll, asBucketStorage, bindOrm, bindTableFacade, buildMaskRegistry, buildRlsReadRegistry, clampLimit, composePluginMiddleware, composeShapeReadWhere, createPolicyDsl, createSecrets, defineAggregateIndex, defineComponent, defineEnv, defineIdentity, defineListArgs, defineMigration, defineMutator, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineShape, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, deny, flushDeferredDeletes, httpAction, httpRoute, httpRouter, indexFieldsFromSchema, initLunora, installPlugins, isDeny, isSafeHeaderValue, mask, mergeSchemaExtension, onConnect, onDisconnect, onQueryChange, onShardInit, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules, toWhereInput, withDeferredDeletes };
+export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_REDACTED_FIELDS as DOCUMENT_HISTORY_REDACTED_FIELDS, DOCUMENT_HISTORY_TABLE, type DataModelInit, type DeferredDeleteFlushResult, type DefineComponentOptions, type DefineDocumentHistoryOptions, type DefineIdentityOptions, type DefineListArgsConfig, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type DocumentHistoryComponent, type DocumentHistoryEntry, type DocumentHistoryFunctions, type DurableObjectJurisdiction, type DurableStreamOptions, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExposeConfig, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type IdentityContract, type IdentityRejectMode, type IdentityValidation, type IndexFieldsByTable, type InferArgs, type InferEnv, type InferIdentity, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type ListArgsSpec, type ListArgsValidators, type ListArgsValue, type ListFilterOperators, type ListOrderByEntry, type ListWhere, type LunoraBuilders, LunoraEnvError, LunoraError, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskRegistry, type MaskStrategy, type Middleware, type MiddlewareNext, type MigrationCtx, type MigrationDefinition, type MigrationDocument, type MigrationReader, type MigrationTransform, type MutationBuilder, type MutationCtx, type MutatorDefinition, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type ReactorHandler, type ReactorOutcome, type ReactorSelect, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredMutator, type RegisteredQuery, type RegisteredReactor, type RegisteredShape, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type RlsReadRegistry, type Role, type Schema, type SchemaExtension, type ShapeDefinition, type ShapeReadWhereRequest, type ShardInitEvent, type ShardInitHandler, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, allowAll, asBucketStorage, bindOrm, bindTableFacade, buildMaskRegistry, buildRlsReadRegistry, clampLimit, composePluginMiddleware, composeShapeReadWhere, createPolicyDsl, createSecrets, defineAggregateIndex, defineComponent, defineDocumentHistory, defineEnv, defineIdentity, defineListArgs, defineMigration, defineMutator, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineShape, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, deny, documentHistoryExtension, flushDeferredDeletes, httpAction, httpRoute, httpRouter, indexFieldsFromSchema, initLunora, installPlugins, isDeny, isSafeHeaderValue, mask, mergeSchemaExtension, onConnect, onDisconnect, onQueryChange, onShardInit, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules, toWhereInput, withDeferredDeletes };