@lunora/server 0.0.0 → 1.0.0-alpha.10

package/dist/types.d.mts

@@ -0,0 +1,1157 @@
+import { ValidatorMap, InferValidatorMap, Id, Validator, Infer } from '@lunora/values';
+/** Map of validators describing a function's args record. Alias of `@lunora/values`' shared {@link ValidatorMap}. */
+type ArgsValidator = ValidatorMap;
+/** Infer the args object type from an {@link ArgsValidator}. Alias of `@lunora/values`' shared {@link InferValidatorMap}. */
+type InferArgs<A extends ArgsValidator> = InferValidatorMap<A>;
+/** Storage backend for a `.global()` table: D1 (default) or a Postgres/MySQL database via Cloudflare Hyperdrive (PlanetScale, Neon, …). */
+type GlobalBackend = "d1" | "hyperdrive";
+/**
+* Cloudflare Durable Object data-residency jurisdiction declared via
+* `defineSchema(...).jurisdiction("…")`. Restricts where every DO the app
+* reaches runs and persists data (GDPR, FedRAMP, US data residency). Widening
+* union — Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/** How a table is routed at runtime. */
+type ShardMode = {
+  backend?: GlobalBackend;
+  kind: "global";
+} | {
+  field: string;
+  kind: "shardBy";
+} | {
+  kind: "root";
+};
+/** Poll cadence for a sourced table — `"manual"` (pull only on an explicit trigger) or a fixed interval. */
+type ExternalSourceRefresh = "manual" | {
+  everyMs: number;
+};
+/**
+* Delete-detection mode for external-source ingest. `"full-pull"` (default) reads
+* the whole tenant membership each tick and diffs it, so it observes upstream
+* deletes; `"incremental"` pulls only changed rows (cheap) and is blind to deletes
+* unless paired with a soft-delete column or a `reconcileEveryMs` full-pull sweep.
+*/
+type ExternalSourceMode = "full-pull" | "incremental";
+/**
+* Config for `.source(...)` (plan 077): declares a table as **materialized from an
+* external Postgres/MySQL behind Cloudflare Hyperdrive**, not written by user
+* mutations. A system-driven poll loop reads the tenant slice and lands it in the
+* DO's SQLite (via the validated CDC writer), after which `defineShape` carries it
+* to clients unchanged. Orthogonal to `shardMode` — a sourced table almost always
+* also `.shardBy()`s, in which case `tenantBy` is the mandatory tenant-isolation
+* boundary (enforced by the `external_source_unscoped` advisor lint).
+*/
+interface ExternalSourceDefinition {
+  /** The wrangler Hyperdrive binding name the poll loop reads from. */
+  binding: string;
+  /** Project the materialized rows to these columns (passed to the membership diff). Omit ⇒ the full mapped document. */
+  columns?: ReadonlyArray<string>;
+  /** Column whose value becomes the Lunora `_id`. Defaults to `"id"`. */
+  idColumn?: string;
+  /** Transform an external row into the stored document body. Omit ⇒ every selected column except `idColumn` is copied. */
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
+  /** Delete-detection mode. Defaults to `"full-pull"`. */
+  mode?: ExternalSourceMode;
+  /** The full tenant-membership query, with driver-native placeholders (`$1` / `?`). `tenantBy` binds its params. */
+  query: string;
+  /** `"incremental"` only: run a full-pull reconcile this often to garbage-collect tombstones the incremental path can't see. */
+  reconcileEveryMs?: number;
+  /** Poll cadence, or `"manual"`. Omit ⇒ the runtime's size-scaled default. */
+  refresh?: ExternalSourceRefresh;
+  /**
+  * **Mandatory under `.shardBy()`**: map this DO's shard key → the query's bound
+  * params, so a tenant DO can only ever pull its own rows. An unscoped sourced +
+  * sharded table replicates the whole multitenant table into every shard — the
+  * `external_source_unscoped` advisor lint fails the build when this is absent.
+  */
+  tenantBy?: (shardKey: string) => ReadonlyArray<unknown>;
+}
+interface IndexDefinition {
+  fields: ReadonlyArray<string>;
+  name: string;
+  unique?: boolean;
+}
+interface SearchIndexDefinition {
+  field: string;
+  filterFields?: ReadonlyArray<string>;
+  name: string;
+}
+/** Reducer applied by an aggregate index. */
+type AggregateOp = "avg" | "count" | "max" | "min" | "sum";
+/**
+* Declared aggregate index — the schema-level seam that lets the runtime keep
+* O(1) counters/sums in step with row writes (via the trigger runner) and
+* route matching reads through them.
+*
+* - `on` — the table whose rows feed the aggregate.
+* - `op` — the reducer. `count` is field-less; the others take `field`.
+* - `field` — the column the reducer applies to (required for non-count ops).
+* - `by` — group keys. When all `where` keys in a read participate in `by`, the
+* reader can answer from the counter table without scanning rows.
+* - `where` — optional static predicate baked into the counter (only the rows
+* matching it ever land in the counter).
+*/
+interface AggregateIndexDefinition {
+  by?: ReadonlyArray<string>;
+  field?: string;
+  name: string;
+  on: string;
+  op: AggregateOp;
+  where?: Record<string, unknown>;
+}
+/**
+* One ordering key on a `rankIndex.sortBy`: which column to sort by, and the
+* direction. The runtime breaks ties on the row's `_id` ASC so the order is
+* total and `rank()` always returns a deterministic 1-based position.
+*/
+interface RankSortKey {
+  direction: "asc" | "desc";
+  field: string;
+}
+/**
+* Declared rank index — a sorted companion table per `(partition tuple, sortBy)`
+* maintained by triggers, so:
+*
+* - `rank(row)` returns the row's 1-based position within its partition under
+* the declared `sortBy` order, plus the partition's total row count, in
+* O(log n) lookups against the SQLite btree on the companion table.
+* - `rankPage({ where, take, from })` walks the same companion table to return
+* rows in the declared order — a sorted-pagination accelerator.
+*
+* Fields mirror `AggregateIndexDefinition`:
+*
+* - `on` — the source table whose rows feed the rank.
+* - `sortBy` — ordered keys driving the rank. Required.
+* - `partitionBy` — columns that scope each rank context (e.g. `["channelId"]`
+* to rank within a channel). Omitted ⇒ one global rank across the table.
+* - `where` — static predicate baked into the index; only matching rows enter.
+*/
+interface RankIndexDefinition {
+  name: string;
+  on: string;
+  partitionBy?: ReadonlyArray<string>;
+  sortBy: ReadonlyArray<RankSortKey>;
+  where?: Record<string, unknown>;
+}
+/** FK behavior when a referenced parent row is deleted (mirrors SQL `ON DELETE`). */
+type OnDeleteAction = "cascade" | "restrict" | "set null";
+/**
+* A declared relation between two tables, recorded by `.relations((r) => …)`.
+*
+* - `one` (many-to-one): the FK column `field` lives on **this** table and
+* points at `table`.`references` (default `_id`). Loads a single doc.
+* - `many` (one-to-many): the FK column `field` lives on the **target** table
+* and points back at this table's `references` (default `_id`). Loads an array.
+*
+* `onDelete` is meaningful only on `one`: it is the action applied to the
+* holder rows when the referenced parent row is deleted.
+*/
+interface RelationDefinition {
+  field: string;
+  kind: "many" | "one";
+  onDelete?: OnDeleteAction;
+  references: string;
+  table: string;
+}
+/** Distance metric used by a Vectorize index. */
+type VectorMetric = "cosine" | "dot-product" | "euclidean";
+/**
+* Bring-your-own-embedder: a user-supplied fn turning a source string into a
+* numeric vector. The runtime calls it at upsert/query time so the framework
+* never couples to a single embedding provider.
+*/
+type VectorEmbedder = (input: string) => Promise<ReadonlyArray<number>> | ReadonlyArray<number>;
+/**
+* Vector index declared inline on a table via `.vectorize(field, opts)`
+* (DSL Shape A). The source is always a single column on the owning table.
+*/
+interface TableVectorIndex {
+  dimensions: number;
+  embed: VectorEmbedder;
+  field: string;
+  metadata?: ReadonlyArray<string>;
+  metric: VectorMetric;
+  name: string;
+}
+interface TableDefinition<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  /**
+  * Aggregate indexes declared via `.aggregateIndex(name, opts)`. The runtime
+  * maintains a counter row per `by` group via the trigger seam, so reads
+  * whose `where` keys all participate in the index's `by` set are answered
+  * without scanning the underlying table.
+  */
+  aggregateIndexes: ReadonlyArray<AggregateIndexDefinition>;
+  /**
+  * Set by `.source(...)` (named `externalSource`, not `source`, so the data
+  * field doesn't collide with the fluent `.source()` builder method — same
+  * convention as `shardBy()`/`shardMode`). When present, the table is
+  * materialized from an external Hyperdrive-backed database by a system poll
+  * loop rather than user mutations. Implies `isExternallyManaged`.
+  */
+  externalSource?: ExternalSourceDefinition;
+  indexes: ReadonlyArray<IndexDefinition>;
+  /**
+  * `true` when `.externallyManaged()` was called — the table's rows are
+  * written outside Lunora's discoverable insert path (an adapter, a
+  * migration, or framework middleware), e.g. `@lunora/auth`'s better-auth
+  * tables or `@lunora/ratelimit`'s store. Advisor insert-path lints
+  * (`table_without_insert`) skip such tables instead of flagging the absent
+  * `ctx.db.insert(...)`.
+  */
+  isExternallyManaged?: boolean;
+  /**
+  * `true` when `.public()` was called — the table opts OUT of secure-by-default
+  * RLS. Under a schema marked `.rls("required")`, every table is protected (the
+  * DO/D1 write path denies raw, non-RLS `ctx.db` access) UNLESS it is `isPublic`.
+  * Has no effect when the schema does not require RLS.
+  */
+  isPublic?: boolean;
+  /**
+  * Rank indexes declared via `.rankIndex(name, opts)`. The runtime maintains
+  * a sorted companion table per declared rank with a btree on
+  * `(partition, sortBy)` so `rank(row)` returns the row's 1-based position
+  * within its partition in O(log n), and `rankPage()` walks the index for
+  * sorted pagination.
+  */
+  rankIndexes: ReadonlyArray<RankIndexDefinition>;
+  /**
+  * Declared relations keyed by accessor name; empty unless `.relations()`
+  * was called. Named `relationMap` (not `relations`) so the fluent
+  * `.relations((r) => …)` builder method doesn't collide with this field.
+  */
+  relationMap: Record<string, RelationDefinition>;
+  searchIndexes: ReadonlyArray<SearchIndexDefinition>;
+  shape: Shape;
+  shardMode: ShardMode;
+  /**
+  * Set by `.softDelete()` (named `softDeleteMode`, not `softDelete`, so the
+  * data field doesn't collide with the fluent `.softDelete()` builder method —
+  * same convention as `shardBy()`/`shardMode`). When present, the table carries
+  * a nullable timestamp column (`field`, default `deletedAt`):
+  * `ctx.db.&lt;table>.delete()` flips it instead of physically removing the row,
+  * and **list reads** (`findMany`/`findFirst`/`query()`/`count`/`aggregate`/
+  * relation loads) hide rows whose `field` is set unless
+  * `includeDeleted: true` is passed. By-id `get`/`patch`/`replace` and
+  * `restore` are unaffected. Absent ⇒ deletes are physical, as before.
+  */
+  softDeleteMode?: {
+    field: string;
+  };
+  /**
+  * Declared lifecycle triggers keyed by accessor name; empty unless
+  * `.triggers()` was called. Named `triggerMap` (not `triggers`) so the
+  * fluent `.triggers((t) => …)` builder method doesn't collide with this
+  * field — same reasoning as {@link TableDefinition.relationMap}.
+  */
+  triggerMap: Record<string, TriggerDefinition>;
+  vectorIndexes: ReadonlyArray<TableVectorIndex>;
+}
+/**
+* Standalone vector index declared via `defineVectorIndex(...)` (DSL Shape B).
+* Unlike {@link TableVectorIndex}, the source is a `select` function so it can
+* derive the embedded text from any computation (e.g. `title + body`).
+*/
+interface VectorIndexDefinition {
+  readonly dimensions: number;
+  readonly embed: VectorEmbedder;
+  readonly kind: "vectorIndex";
+  readonly metadata?: (row: Record<string, unknown>) => Record<string, unknown>;
+  readonly metric: VectorMetric;
+  readonly select: (row: Record<string, unknown>) => string;
+  readonly table: string;
+}
+interface Schema<T extends Record<string, TableDefinition> = Record<string, TableDefinition>> {
+  /**
+  * Secure-by-default RLS mode declared via `.rls("required")`. When
+  * `"required"`, every table is protected: the DO/D1 write path denies raw
+  * (non-RLS-wrapped) `ctx.db` access at runtime, so a procedure that forgets
+  * `.use(rls(...))` fails closed instead of silently exposing the table. A
+  * table opts out with `.public()` (→ {@link TableDefinition.isPublic}).
+  * Absent ⇒ legacy opt-in behavior (RLS only where a policy is applied).
+  */
+  readonly rlsMode?: "required";
+  readonly tables: T;
+  readonly vectorIndexes: Record<string, VectorIndexDefinition>;
+}
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+* Call surface a function is exposed on. `public` functions are reachable from
+* clients via the generated `api`; `internal` functions are reachable only
+* server-to-server (`ctx.runQuery`/`runMutation`/`runAction`) and are rejected
+* by the DO's external RPC path. Absence is treated as `public` for
+* back-compat with functions registered before visibility existed.
+*/
+type FunctionVisibility = "internal" | "public";
+interface RegisteredFunction<A extends ArgsValidator, R, Kind extends FunctionKind> {
+  readonly args: A;
+  readonly handler: (context: unknown, args: InferArgs<A>) => Promise<R> | R;
+  readonly kind: Kind;
+  /**
+  * Set on connection-lifecycle hooks (`onConnect` / `onDisconnect`).
+  * Marks the function for the generated `LUNORA_LIFECYCLE_HOOKS` manifest so the
+  * DO dispatches it on socket connect/disconnect rather than via a client RPC.
+  * Absent on ordinary registrations.
+  */
+  readonly lifecycle?: LifecycleEventKind;
+  readonly visibility?: FunctionVisibility;
+}
+type RegisteredQuery<A extends ArgsValidator, R> = RegisteredFunction<A, R, "query">;
+type RegisteredMutation<A extends ArgsValidator, R> = RegisteredFunction<A, R, "mutation">;
+type RegisteredAction<A extends ArgsValidator, R> = RegisteredFunction<A, R, "action">;
+/** Which side of the WebSocket lifecycle a hook fires on. */
+type LifecycleEventKind = "connect" | "disconnect";
+/**
+* The event a connection-lifecycle hook receives as its second argument. It is
+* the JSON-serializable payload the DO forwards on socket connect/disconnect;
+* the verified caller identity is also reflected on `ctx.auth` (the hook runs
+* under the connecting user via `resolveIdentity`).
+*/
+interface LifecycleEvent {
+  /** Stable per-socket id, minted at upgrade and replayed verbatim on disconnect. */
+  readonly connectionId: string;
+  /** App-supplied connection context from the client `connect` envelope (e.g. `{ roomId, sessionId }`). */
+  readonly context?: Record<string, unknown>;
+  /** The shard this socket is bound to. */
+  readonly shardKey: string;
+  /** Verified user id resolved at upgrade, or `null` for an anonymous socket. */
+  readonly userId: string | null;
+}
+/**
+* A registered connection-lifecycle hook — an internal mutation tagged with the
+* lifecycle side it fires on. Produced by `onConnect` / `onDisconnect`.
+*/
+type RegisteredLifecycleHook = RegisteredFunction<Record<string, never>, void, "mutation"> & {
+  readonly lifecycle: LifecycleEventKind;
+};
+/**
+* A streaming query registration. Unlike {@link RegisteredFunction} the handler
+* returns an `AsyncIterable&lt;R>` synchronously (it does NOT `Promise&lt;R>`); the
+* runtime drives it frame by frame and forwards each chunk to the caller. The
+* third `signal` argument is wired to the caller's cancel signal so the handler
+* can stop early — break out of the loop or check `signal.aborted` between
+* yields.
+*/
+interface RegisteredStream<A extends ArgsValidator, R> {
+  readonly args: A;
+  readonly handler: (context: unknown, args: InferArgs<A>, signal: AbortSignal) => AsyncIterable<R>;
+  readonly kind: "stream";
+  readonly visibility?: FunctionVisibility;
+}
+/** The system tables `ctx.db.system` can read. */
+type SystemTableName = "_scheduled_functions" | "_storage";
+/**
+* A pending scheduled invocation as surfaced by the `_scheduled_functions`
+* system table. Mirrors {@link ScheduledJob} (the `ctx.scheduler` view); the
+* separate name keeps the system-table read surface self-describing.
+*/
+interface ScheduledFunctionDoc {
+  /** Function arguments the job will be dispatched with. */
+  args: Record<string, unknown>;
+  /** Number of dispatch attempts already made (absent until the first retry). */
+  attempts?: number;
+  /** When the job was enqueued (epoch ms). */
+  enqueuedAt: number;
+  /** Fully-qualified path of the function to invoke. */
+  functionPath: string;
+  /** The job's id (the `_scheduled_functions` row id). */
+  id: string;
+  /** When the job is scheduled to fire (epoch ms). */
+  scheduledFor: number;
+  /** Routing hint forwarded so dispatch lands on the right shard. */
+  shardKey?: string;
+}
+/** Maps each system table name to the document shape its reads return. */
+interface SystemDocMap {
+  _scheduled_functions: ScheduledFunctionDoc;
+  _storage: StorageMetadata;
+}
+/** Document type for a given system table name. */
+type SystemDoc<T extends SystemTableName> = SystemDocMap[T];
+/** Terminal returned by {@link SystemDatabaseReader.query}; only `.collect()` is supported. */
+interface SystemQuery<T extends SystemTableName> {
+  /** Resolve the full list of rows in the backing source. */
+  collect: () => Promise<SystemDoc<T>[]>;
+}
+/**
+* Read-only reader over Lunora's system tables (`_scheduled_functions`,
+* `_storage`), exposed as `ctx.db.system`. Mirrors Convex's `ctx.db.system`.
+*
+* **Best-effort and eventually consistent.** Unlike `ctx.db.&lt;table>` — which
+* reads the shard's transactional SQLite snapshot — the data behind these tables
+* lives OUTSIDE the shard (scheduled functions in the `SchedulerDO`, storage
+* objects in R2). Every `collect()` / `get()` reaches across to that source.
+*
+* It is **not part of the mutation transaction snapshot** (no OCC guard, no
+* subscription dependency recorded — reading it inside a mutation does not pin
+* it), and results are **eventually consistent** with writes a mutation just
+* made (e.g. a freshly scheduled job may not appear yet).
+*
+* Read-only by design: mutate scheduled jobs via `ctx.scheduler`, storage
+* objects via `ctx.storage`.
+*/
+interface SystemDatabaseReader {
+  /**
+  * Resolve a single system-table row by id, or `null` when absent.
+  * (`_scheduled_functions` → job id; `_storage` → object key.)
+  */
+  get: <T extends SystemTableName>(table: T, id: string) => Promise<SystemDoc<T> | null>;
+  /**
+  * Begin a read over a system table; call `.collect()` to resolve the full
+  * list. No filtering, indexing, or pagination — the backing source is remote
+  * and the surface stays deliberately minimal.
+  */
+  query: <T extends SystemTableName>(table: T) => SystemQuery<T>;
+}
+/**
+* Read-only handle bound to a table. Used by `query`/`mutation`/`action`. The
+* actual SQL implementation lives in `@lunora/do`; these are signatures only.
+*/
+interface DatabaseReader {
+  get: <T extends string>(id: Id<T>) => Promise<Record<string, unknown> | null>;
+  /**
+  * Validate an untrusted `id` string against the structural shape of an id
+  * for `tableName`, returning the branded {@link Id} when it is well-formed
+  * and `null` otherwise. Pure structural validation — it never reads the
+  * database, so a structurally valid id for a row that doesn't exist still
+  * returns the branded id (mirrors Convex's `db.normalizeId`).
+  */
+  normalizeId: <T extends string>(tableName: T, id: string) => Id<T> | null;
+  query: (tableName: string) => TableReader;
+  /**
+  * Best-effort, read-only reader over Lunora's system tables
+  * (`_scheduled_functions`, `_storage`). Eventually consistent and **not**
+  * part of the transaction snapshot — see {@link SystemDatabaseReader}.
+  */
+  readonly system: SystemDatabaseReader;
+}
+/** Options for {@link TableReader.paginate} — Convex-compatible page request. */
+interface PaginationOptions {
+  /** Opaque cursor from the prior page's `continueCursor`; `null`/omitted starts at the first page. */
+  cursor?: null | string;
+  /**
+  * Optional inclusive upper bound for reactive pagination. When supplied the
+  * page covers the fixed half-open range `(cursor, endCursor]` (ignoring
+  * `numItems`): every row strictly after `cursor` up to and including the
+  * boundary row `endCursor` encodes. The page's `isDone` is `true` and its
+  * `continueCursor` echoes `endCursor`, so the next page keeps starting where
+  * this one ends even as rows are inserted/deleted inside the range. Omit (or
+  * pass `null`) for the legacy "first `numItems` after `cursor`" behaviour.
+  */
+  endCursor?: null | string;
+  /** Maximum rows to return for this page. */
+  numItems: number;
+}
+/** One page of a keyset-paginated query. */
+interface PaginationResult<T = Record<string, unknown>> {
+  /** Cursor to pass back for the next page, or `null` once `isDone`. */
+  continueCursor: null | string;
+  /** `true` when this page is the last one. */
+  isDone: boolean;
+  page: T[];
+  /**
+  * Reactive-pagination only: the midpoint cursor of a bounded
+  * `(cursor, endCursor]` page, used by the client to split an over-grown page
+  * into two adjacent ranges. Absent on legacy (open-ended) pages.
+  */
+  splitCursor?: null | string;
+}
+/**
+* The fluent `ctx.db.query(table)` reader. Generic over the document type
+* `Row` so the generated `ctx.db` can bind it to `Doc&lt;table>` (the chain and
+* every terminal then resolve typed rows — no `as unknown as Doc&lt;...>` casts).
+* Defaults to the untyped `Record&lt;string, unknown>` shape for the base
+* (schema-agnostic) `@lunora/server` reader.
+*/
+interface TableReader<Row = Record<string, unknown>> {
+  collect: () => Promise<Row[]>;
+  filter: (predicate: (document: Row) => boolean) => TableReader<Row>;
+  first: () => Promise<Row | null>;
+  /**
+  * Set the result order. Orders by the active `.withIndex()` (or by
+  * `_creationTime` when none is staged), `"asc"` by default; `"desc"`
+  * reverses it. Composes with `.withIndex()`, `.filter()`, and every
+  * terminal (`collect`/`first`/`take`/`paginate`/`unique`). Mirrors Convex's
+  * `.order("asc" | "desc")`.
+  */
+  order: (direction: "asc" | "desc") => TableReader<Row>;
+  paginate: (options: PaginationOptions) => Promise<PaginationResult<Row>>;
+  take: (limit: number) => Promise<Row[]>;
+  /**
+  * Return the single matching document. Returns `null` when nothing matches
+  * and throws when more than one row matches. Mirrors Convex's `.unique()`.
+  */
+  unique: () => Promise<Row | null>;
+  withIndex: (indexName: string, range?: (q: IndexRangeBuilder) => IndexRangeBuilder) => TableReader<Row>;
+  /**
+  * Restrict the query to a declared `.searchIndex()`. The builder's
+  * `.search(field, query)` runs a full-text match against the index's
+  * searchable field; `.eq(field, value)` narrows by a declared filter
+  * field. Results come back ordered by relevance — pair with `.take(n)`
+  * (`.paginate()` is not supported on a search query).
+  */
+  withSearchIndex: (indexName: string, search: (q: SearchFilterBuilder) => SearchFilterBuilder) => TableReader<Row>;
+}
+interface IndexRangeBuilder {
+  eq: (field: string, value: unknown) => IndexRangeBuilder;
+  gt: (field: string, value: unknown) => IndexRangeBuilder;
+  gte: (field: string, value: unknown) => IndexRangeBuilder;
+  lt: (field: string, value: unknown) => IndexRangeBuilder;
+  lte: (field: string, value: unknown) => IndexRangeBuilder;
+}
+/** Builder passed to {@link TableReader.withSearchIndex}; mirrors Convex's search query. */
+interface SearchFilterBuilder {
+  /** Narrow by a declared filter field (exact match). */
+  eq: (field: string, value: unknown) => SearchFilterBuilder;
+  /** Full-text match `query` against the index's searchable `field`. Call exactly once. */
+  search: (field: string, query: string) => SearchFilterBuilder;
+}
+/**
+* Options shared by the batch-write methods (`insertMany`/`deleteMany`/
+* `patchMany`) — a per-call payload cap. The default cap (500) rejects an
+* oversized call up front so an accidental O(n²) or a payload past the Durable
+* Object request limit fails loudly instead of degrading the mutation. Callers
+* with larger sets should chunk their own loop or raise `limit`.
+*/
+interface BatchWriteOptions {
+  /** Reject the call when the batch size exceeds this value (default 500). */
+  limit?: number;
+}
+interface DatabaseWriter extends DatabaseReader {
+  delete: <T extends string>(id: Id<T>) => Promise<void>;
+  /**
+  * Delete many rows by id in one call. Each id is deleted through the full
+  * single-row pipeline (triggers + per-row RLS). The returned `deleted` is the
+  * number of ids **requested**, not the rows actually removed — an unknown or
+  * duplicated id is a silent no-op.
+  *
+  * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
+  * BEGIN/COMMIT span, so a mid-batch failure (a later RLS denial or handler
+  * error) rolls back the whole mutation. (In an action there is no transaction
+  * span, so the prior deletes persist; the in-memory test harness mirrors the span.)
+  */
+  deleteMany: <T extends string>(ids: ReadonlyArray<Id<T>>, options?: BatchWriteOptions) => Promise<{
+    deleted: number;
+  }>;
+  /**
+  * Insert a document, returning its server id.
+  *
+  * Pass `options.clientId` (a UUID) to key the row yourself — for an
+  * optimistic client that needs the persisted row to match the key it
+  * already rendered. It's validated for shape and still subject to the
+  * primary-key uniqueness constraint; omit it and the server mints the id.
+  */
+  insert: <T extends string>(tableName: T, document: Record<string, unknown>, options?: {
+    clientId?: string;
+  }) => Promise<Id<T>>;
+  /**
+  * Insert many documents into one table in a single call, returning the
+  * minted ids in input order. Equivalent to a per-row `insert()` loop — each
+  * row gets defaults, validators, triggers, and a per-row RLS check — but the
+  * caller pays one round-trip instead of N.
+  *
+  * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
+  * BEGIN/COMMIT span, so a mid-batch failure (an invalid or RLS-denied row)
+  * rolls back the whole mutation. (In an action there is no transaction span,
+  * so the prior inserts persist; the in-memory test harness mirrors the span.)
+  */
+  insertMany: <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options?: BatchWriteOptions) => Promise<Id<T>[]>;
+  /**
+  * **Trusted** bulk insert: one multi-row `INSERT` that **skips per-row
+  * `.check()` validators and before/after triggers** for throughput on data you
+  * control (seed, migration, admin import). Defaults, ids, and every companion
+  * (search/aggregate/rank/CDC + live subscriptions) are still applied, so reads
+  * stay correct.
+  *
+  * It is **"unsafe" only in that it bypasses the validation/trigger pipeline** —
+  * RLS is **not** bypassed: secure-by-default and the table's insert policy still
+  * apply (the framework ships no RLS-bypassing writer). Pass `allowExplicitId` to
+  * preserve a supplied `_id` (import). Use only for data you trust; prefer
+  * `insertMany` for anything user-supplied.
+  */
+  insertManyUnsafe: <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options?: BatchWriteOptions & {
+    allowExplicitId?: boolean;
+  }) => Promise<Id<T>[]>;
+  patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
+  /**
+  * Patch many rows by id in one call. Each `{ id, patch }` is applied like a
+  * single `patch()` (per-row triggers + RLS).
+  *
+  * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
+  * BEGIN/COMMIT span, so a mid-batch failure rolls back the whole mutation.
+  * (In an action there is no transaction span, so the prior patches persist;
+  * the in-memory test harness mirrors the span.)
+  */
+  patchMany: <T extends string>(patches: ReadonlyArray<{
+    id: Id<T>;
+    patch: Record<string, unknown>;
+  }>, options?: BatchWriteOptions) => Promise<void>;
+  replace: <T extends string>(id: Id<T>, document: Record<string, unknown>) => Promise<void>;
+}
+/** Authenticated identity surfaced into every context. */
+interface AuthState {
+  getIdentity: () => Promise<Record<string, unknown> | null>;
+  readonly userId: string | null;
+}
+/**
+* A pending scheduled invocation as surfaced by {@link Scheduler.list} /
+* {@link Scheduler.get}. A clean public mirror of `@lunora/scheduler`'s internal
+* `ScheduleRecord` — re-declared here so the public ctx surface carries no
+* dependency on the scheduler package's internal types.
+*/
+interface ScheduledJob {
+  args: Record<string, unknown>;
+  /** Number of dispatch attempts already made (absent until the first retry). */
+  attempts?: number;
+  /** When the job was enqueued (epoch ms). */
+  enqueuedAt: number;
+  functionPath: string;
+  id: string;
+  /** When the job is scheduled to fire (epoch ms). */
+  scheduledFor: number;
+  /** Routing hint forwarded so dispatch lands on the right shard. */
+  shardKey?: string;
+}
+interface Scheduler {
+  /** Cancel a pending job by id. `cancelled` is `false` when no such job exists. */
+  cancel: (id: string) => Promise<{
+    cancelled: boolean;
+  }>;
+  /** Resolve a single pending job by id, or `null` when absent. */
+  get: (id: string) => Promise<ScheduledJob | null>;
+  /** List all pending scheduled jobs. */
+  list: () => Promise<ScheduledJob[]>;
+  runAfter: (delayMs: number, functionPath: string, args?: Record<string, unknown>) => Promise<string>;
+  runAt: (timestampMs: number, functionPath: string, args?: Record<string, unknown>) => Promise<string>;
+}
+/**
+* A workflow instance's lifecycle status. Clean public mirror of
+* `@lunora/workflow`'s `WorkflowInstanceStatus` (itself a mirror of Cloudflare's
+* `WorkflowInstanceStatus`) — re-declared here so the ctx surface carries no
+* dependency on the workflow package, exactly as {@link Scheduler} avoids a
+* dependency on `@lunora/scheduler`.
+*/
+type WorkflowInstanceStatus = "complete" | "errored" | "paused" | "queued" | "running" | "terminated" | "unknown" | "waiting" | "waitingForPause";
+/** Result of {@link WorkflowInstance.status}. Mirrors `@lunora/workflow`'s `WorkflowStatusResult`. */
+interface WorkflowStatusResult {
+  error?: {
+    message: string;
+    name: string;
+  };
+  output?: unknown;
+  status: WorkflowInstanceStatus;
+}
+/** Options accepted by {@link WorkflowHandle.create}. Mirrors `@lunora/workflow`'s `WorkflowCreateOptions`. */
+interface WorkflowCreateOptions<Params = Record<string, unknown>> {
+  /** Unique-within-the-workflow instance id. Generated by Cloudflare when omitted. */
+  id?: string;
+  /** The event payload the instance is triggered with — surfaced as `event.payload`. */
+  params?: Params;
+  /** Instance retention policy (defaults to the account maximum). */
+  retention?: {
+    errorRetention?: string;
+    successRetention?: string;
+  };
+}
+/** A live handle to a single workflow instance. Mirrors `@lunora/workflow`'s `WorkflowInstanceLike`. */
+interface WorkflowInstance {
+  readonly id: string;
+  pause: () => Promise<void>;
+  restart: () => Promise<void>;
+  resume: () => Promise<void>;
+  sendEvent: (event: {
+    payload: unknown;
+    type: string;
+  }) => Promise<void>;
+  status: () => Promise<WorkflowStatusResult>;
+  terminate: () => Promise<void>;
+}
+/**
+* A typed handle to one declared workflow, addressable from `ctx.workflows`.
+* Mirrors `@lunora/workflow`'s `WorkflowHandle`.
+*/
+interface WorkflowHandle<Params = Record<string, unknown>> {
+  /** Start a new instance (optionally with an id + params). */
+  create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstance>;
+  /** Start many instances in one batched RPC. */
+  createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstance[]>;
+  /** Get a handle to an existing instance by id. */
+  get: (id: string) => Promise<WorkflowInstance>;
+}
+/**
+* The `ctx.workflows` surface on {@link MutationCtx} / {@link ActionCtx}. Each
+* workflow declared in `lunora/workflows.ts` is reachable by its export name;
+* codegen narrows the `get(name)` overloads to the known workflow names + their
+* inferred param types. Mirrors `@lunora/workflow`'s `Workflows`.
+*/
+interface Workflows {
+  /** Resolve the handle for a declared workflow by export name. */
+  get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
+}
+/**
+* Structural projection of workers-types' `SecretsStoreSecret` binding — the
+* per-secret `secrets_store_secrets[]` binding whose `.get()` resolves the
+* secret value (or throws if it does not exist). Mirrored structurally so the
+* runtime resolves it without a workerd type dependency.
+*/
+interface SecretsStoreSecretLike {
+  get: () => Promise<string>;
+}
+/**
+* `ctx.secrets` — read account-level secrets bound via Cloudflare Secrets Store.
+* A core built-in (always present on every context, like `ctx.log`): a binding
+* named in wrangler's `secrets_store_secrets[]` is read by its binding name.
+*
+* ```ts
+* const apiKey = await ctx.secrets.get("STRIPE_KEY");
+* ```
+*
+* The lookup is async (the platform fetches and decrypts on first read);
+* reading an undeclared name throws a directed error naming the bound secrets.
+*/
+interface Secrets {
+  /** Resolve a Secrets Store secret by its wrangler binding name. */
+  get: (name: string) => Promise<string>;
+}
+/** Lifecycle phase relative to the SQL write. */
+type TriggerTiming = "after" | "before";
+/** The CRUD operation a trigger reacts to. `patch` and `replace` both map to `update`. */
+type TriggerOp = "delete" | "insert" | "update";
+/**
+* A row as observed by a trigger handler: the table's `Shape` (with the same
+* optionality rules as {@link InferArgs}) plus the system columns every stored
+* doc carries.
+*/
+type TriggerRow<Shape extends Record<string, Validator>> = { [K in keyof Shape as undefined extends Infer<Shape[K]> ? K : never]?: Infer<Shape[K]> } & { [K in keyof Shape as undefined extends Infer<Shape[K]> ? never : K]: Infer<Shape[K]> } & {
+  readonly _creationTime: number;
+  readonly _id: string;
+};
+/** What an `insert` trigger observes: the freshly written row. */
+interface TriggerInsertEvent<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  readonly doc: TriggerRow<Shape>;
+  readonly id: string;
+  readonly op: "insert";
+  readonly table: string;
+}
+/**
+* What an `update` trigger observes: the merged row plus the pre-write row.
+* `previous` is typed as always present (the row must exist to be updated); the
+* runtime supplies it best-effort and only omits it in the unreachable
+* row-vanished-mid-write case.
+*/
+interface TriggerUpdateEvent<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  readonly doc: TriggerRow<Shape>;
+  readonly id: string;
+  readonly op: "update";
+  readonly previous: TriggerRow<Shape>;
+  readonly table: string;
+}
+/**
+* What a `delete` trigger observes: the row about to be (or just) removed.
+* `previous` is typed as always present; the runtime supplies it best-effort
+* and only omits it in the unreachable row-vanished-mid-write case.
+*/
+interface TriggerDeleteEvent<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  readonly id: string;
+  readonly op: "delete";
+  readonly previous: TriggerRow<Shape>;
+  readonly table: string;
+}
+/** Union of every trigger event, with the table `Shape` erased (as stored in `triggerMap`). */
+type TriggerEvent = TriggerDeleteEvent | TriggerInsertEvent | TriggerUpdateEvent;
+/** Page returned by {@link TriggerDatabase.findMany}; mirrors `@lunora/do`'s `QueryPage`. */
+interface TriggerQueryPage {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: Record<string, unknown>[];
+}
+/** Args accepted by {@link TriggerDatabase} reads; mirrors `@lunora/do`'s `QueryArgs`. */
+interface TriggerQueryArgs {
+  cursor?: null | string;
+  limit?: number;
+  orderBy?: ReadonlyArray<unknown>;
+  where?: Record<string, unknown>;
+  with?: Record<string, unknown>;
+}
+/**
+* Args accepted by {@link TriggerDatabase.aggregate} — structural mirror of
+* `@lunora/do`'s `AggregateOptions`, kept local so trigger handlers in
+* `@lunora/server` don't take a hard dep on the DO runtime.
+*/
+interface TriggerAggregateOptions {
+  baseWhere?: Record<string, unknown>;
+  field?: string;
+  op: AggregateOp;
+  restrictsCounts?: boolean;
+  where?: Record<string, unknown>;
+}
+/** Args accepted by {@link TriggerDatabase.groupBy}. */
+interface TriggerGroupByOptions {
+  agg?: {
+    field?: string;
+    op: AggregateOp;
+  };
+  baseWhere?: Record<string, unknown>;
+  by: ReadonlyArray<string>;
+  restrictsCounts?: boolean;
+  where?: Record<string, unknown>;
+}
+/** One entry returned by {@link TriggerDatabase.groupBy}. */
+interface TriggerGroupByEntry {
+  key: Record<string, unknown>;
+  value: null | number;
+}
+/** Args accepted by {@link TriggerDatabase.rank}. */
+interface TriggerRankOptions {
+  baseWhere?: Record<string, unknown>;
+  restrictsCounts?: boolean;
+  /** Either the row id or the full row document. */
+  row: Record<string, unknown> | string;
+  where?: Record<string, unknown>;
+}
+/** Result of {@link TriggerDatabase.rank} — 1-based position + partition total. */
+interface TriggerRankResult {
+  position: number;
+  total: number;
+}
+/** Args accepted by {@link TriggerDatabase.rankPage}. */
+interface TriggerRankPageOptions {
+  baseWhere?: Record<string, unknown>;
+  cursor?: null | string;
+  take?: number;
+  where?: Record<string, unknown>;
+}
+/**
+* Portable, table/id-addressed ORM writer handed to trigger handlers via
+* `ctx.db`. Mirrors `@lunora/do`'s runtime `DatabaseWriterLike` surface — it is
+* **not** the generated per-table `ctx.db.&lt;table>` facade (which can't be typed
+* from inside `defineTable`, where the full schema isn't known).
+*
+* `aggregate`/`groupBy`/`count`/`rank`/`rankPage` route through the same
+* trigger-maintained counter and rank tables the user-facing reader uses, so
+* a handler's `ctx.db.&lt;table>.aggregate(...)` observes the just-staged write
+* within the same DO transaction (the counter step happens before the trigger
+* fires).
+*/
+interface TriggerDatabase {
+  aggregate: (tableName: string, options: TriggerAggregateOptions) => Promise<null | number>;
+  count: (tableName: string, where?: Record<string, unknown>) => Promise<number>;
+  delete: (id: string) => Promise<void>;
+  findFirst: (tableName: string, args?: TriggerQueryArgs) => Promise<Record<string, unknown> | null>;
+  findMany: (tableName: string, args?: TriggerQueryArgs) => Promise<TriggerQueryPage>;
+  get: (id: string) => Promise<Record<string, unknown> | null>;
+  groupBy: (tableName: string, options: TriggerGroupByOptions) => Promise<ReadonlyArray<TriggerGroupByEntry>>;
+  insert: (tableName: string, document: Record<string, unknown>) => Promise<string>;
+  patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
+  rank: (tableName: string, indexName: string, options: TriggerRankOptions) => Promise<null | TriggerRankResult>;
+  rankPage: (tableName: string, indexName: string, options?: TriggerRankPageOptions) => Promise<TriggerQueryPage>;
+  replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+}
+/**
+* Handle injected into every trigger handler. `db` is the portable ORM writer;
+* `scheduler` enqueues async / cross-shard follow-up work (cross-shard work is
+* **not** transactional with the firing write).
+*/
+interface TriggerCtx {
+  readonly db: TriggerDatabase;
+  readonly scheduler: Scheduler;
+}
+/** A user-declared trigger handler. Throwing from a `before*` handler aborts the write. */
+type TriggerHandler<Event> = (context: TriggerCtx, event: Event) => Promise<void> | void;
+/**
+* A single declared trigger, as stored in {@link TableDefinition.triggerMap}.
+* The handler's event type is erased to the {@link TriggerEvent} union here; the
+* per-op {@link TriggerBuilder} methods recover the precise event type for
+* authors.
+*/
+interface TriggerDefinition {
+  readonly handler: TriggerHandler<TriggerEvent>;
+  readonly op: TriggerOp;
+  readonly timing: TriggerTiming;
+}
+/**
+* The `t` argument passed to `.triggers((t) => …)`. Each method binds a handler
+* to one `timing`+`op` pair, typing the event against the table's `Shape`.
+*/
+interface TriggerBuilder<Shape extends Record<string, Validator> = Record<string, Validator>> {
+  afterDelete: (handler: TriggerHandler<TriggerDeleteEvent<Shape>>) => TriggerDefinition;
+  afterInsert: (handler: TriggerHandler<TriggerInsertEvent<Shape>>) => TriggerDefinition;
+  afterUpdate: (handler: TriggerHandler<TriggerUpdateEvent<Shape>>) => TriggerDefinition;
+  beforeDelete: (handler: TriggerHandler<TriggerDeleteEvent<Shape>>) => TriggerDefinition;
+  beforeInsert: (handler: TriggerHandler<TriggerInsertEvent<Shape>>) => TriggerDefinition;
+  beforeUpdate: (handler: TriggerHandler<TriggerUpdateEvent<Shape>>) => TriggerDefinition;
+}
+/**
+* Per-file metadata returned by {@link ReadOnlyStorage.getMetadata}. A clean
+* public mirror of `@lunora/storage`'s `ObjectMetadata` — re-declared here so
+* the ctx surface carries no dependency on the storage package's types. Matches
+* the columns Convex surfaces for `ctx.storage.getMetadata` / `_storage`.
+*/
+interface StorageMetadata {
+  /** The object's `Content-Type`, when recorded. */
+  contentType?: string;
+  /** Custom metadata set at upload time, if any. */
+  customMetadata?: Record<string, string>;
+  /** The object's key. */
+  key: string;
+  /** Hex-encoded SHA-256 of the body, when R2 carries a checksum. */
+  sha256?: string;
+  /** Body length in bytes. */
+  size: number;
+  /** When the object was last written (epoch ms), when reported. */
+  uploaded?: number;
+}
+/**
+* Read-only projection of `Storage` exposed on `QueryCtx` / `MutationCtx`.
+*
+* Queries are pure reads, and mutations run inside a transactional scope —
+* neither is allowed to perform side-effectful R2 writes (`upload`) or
+* deletes (`delete`). They can, however, **read** existing objects and
+* resolve signed URLs (the URL signing itself is HMAC-only — no R2 round
+* trip), so the read-only surface keeps `download` and `getSignedUrl`. The
+* full {@link Storage} surface stays on `ActionCtx`.
+*/
+interface ReadOnlyStorage<Buckets extends string = string> {
+  /**
+  * Select a named bucket (declared via `v.storage("name")`). The returned
+  * accessor's operations target that bucket — `ctx.storage.bucket("avatars")
+  * .download(key)`. The bare `ctx.storage` targets the default bucket.
+  */
+  bucket: (name: Buckets) => ReadOnlyStorage<Buckets>;
+  /** The bucket this accessor's operations target (the default for the bare `ctx.storage`). */
+  readonly bucketName: string;
+  /** Fetch the body of an existing object. Returns `null` when absent. */
+  download: (key: string) => Promise<ReadableStream | null>;
+  /**
+  * Read a file's metadata (size, content-type, sha256, upload time, custom
+  * metadata) without fetching its body. Returns `null` when the object is
+  * absent. Mirrors Convex's `ctx.storage.getMetadata`.
+  */
+  getMetadata: (key: string) => Promise<StorageMetadata | null>;
+  /** Resolve a short-lived signed URL for an existing object. */
+  getSignedUrl: (key: string, options?: {
+    expiresInSeconds?: number;
+  }) => Promise<string>;
+  /** Public URL pointing at the configured base for `key`. */
+  getUrl: (key: string) => string;
+}
+interface Storage<Buckets extends string = string> extends ReadOnlyStorage<Buckets> {
+  /** Select a named bucket; the returned accessor exposes the full read/write surface. */
+  bucket: (name: Buckets) => Storage<Buckets>;
+  delete: (key: string) => Promise<void>;
+  /**
+  * Mint a short-lived signed `PUT` URL a client can upload directly to,
+  * optionally pinning the `Content-Type` the uploader must send. Mirrors
+  * Convex's `storage.generateUploadUrl`.
+  */
+  generateUploadUrl: (key: string, options?: {
+    contentType?: string;
+    expiresInSeconds?: number;
+  }) => Promise<string>;
+  /**
+  * Upload `body` to `key` from the server, returning the stored object's key
+  * and etag. Mirrors Convex's `storage.store`. Accepts the same guard fields
+  * as `@lunora/storage`'s `UploadOptions` so `maxSize` /
+  * `allowedContentTypes` enforcement isn't lost behind the Convex-style alias.
+  */
+  store: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: {
+    allowedContentTypes?: ReadonlyArray<string>;
+    contentType?: string;
+    customMetadata?: Record<string, string>;
+    maxSize?: number;
+  }) => Promise<{
+    etag: string;
+    key: string;
+  }>;
+}
+interface VectorMatch {
+  id: string;
+  metadata?: Record<string, unknown>;
+  score: number;
+}
+interface VectorMatches {
+  count: number;
+  matches: ReadonlyArray<VectorMatch>;
+}
+interface VectorQueryInput {
+  /** Embedder used when `input` is supplied instead of a precomputed `vector`. */
+  embed?: VectorEmbedder;
+  filter?: Record<string, unknown>;
+  /** Natural-language input embedded via `embed`. Ignored when `vector` is set. */
+  input?: string;
+  namespace?: string;
+  topK?: number;
+  /** Precomputed query vector; skips `embed`. */
+  vector?: ReadonlyArray<number>;
+}
+interface VectorUpsertInput {
+  embed: VectorEmbedder;
+  id: string;
+  input: string;
+  metadata?: Record<string, unknown>;
+  namespace?: string;
+}
+interface VectorRecord {
+  id: string;
+  metadata?: Record<string, unknown>;
+  values: ReadonlyArray<number>;
+}
+/**
+* Read-only vector surface exposed on {@link QueryCtx}. Mirrors the read half
+* of `@lunora/bindings/vectors`' `LunoraVectors` so the live adapter is assignable.
+*/
+interface VectorSearchReader {
+  getByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorRecord>>;
+  query: (indexName: string, input: VectorQueryInput) => Promise<VectorMatches>;
+}
+/**
+* Mutating vector surface on {@link MutationCtx} / {@link ActionCtx}. `upsert`
+* is queued post-commit by default; `upsertNow` forces a synchronous write.
+* `db.delete` on a vectorized table auto-propagates the matching `deleteByIds`.
+*/
+interface VectorSearch extends VectorSearchReader {
+  deleteByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<void>;
+  upsert: (indexName: string, input: VectorUpsertInput) => Promise<void>;
+  upsertNow: (indexName: string, input: VectorUpsertInput) => Promise<void>;
+}
+/**
+* Structured logger on every function `ctx`. Each call emits one attributed log
+* line — tagged with the function path on the server — that flows to an
+* `ObservabilitySink`'s `onLog` (where you route it in production) and, in
+* development, to the dev server terminal via the CLI / Vite plugin formatter.
+* Mirrors the `console` method names so it's a drop-in for `console.log` inside a
+* handler, but with attribution and a routable transport.
+*
+* Accepts any number of values per call, exactly like `console`; objects are
+* rendered into the human-readable message. The raw, un-rendered arguments are
+* preserved ONLY on the in-process `onLog` sink (which you opt into and control);
+* the rendered message — not the structured args — is what reaches the dev
+* terminal and the platform's Workers Logs.
+*
+* Attribution follows the dispatched function: a log emitted inside an internal
+* function invoked via `ctx.runQuery`/`runMutation`/`runAction` is attributed to
+* the outer request entrypoint, since the composed call reuses its context.
+*/
+interface LunoraLogger {
+  readonly debug: (...args: unknown[]) => void;
+  readonly error: (...args: unknown[]) => void;
+  readonly info: (...args: unknown[]) => void;
+  readonly log: (...args: unknown[]) => void;
+  readonly warn: (...args: unknown[]) => void;
+}
+interface QueryCtx {
+  readonly auth: AuthState;
+  readonly db: DatabaseReader;
+  /**
+  * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
+  * forwarded server-side (never read from a client header). `undefined` when
+  * unknown: a live-subscription re-run, a server-initiated dispatch, or
+  * non-Cloudflare hosting. A convenient rate-limit key for anonymous traffic.
+  */
+  readonly ip?: string;
+  /** Structured, function-attributed logger; see {@link LunoraLogger}. */
+  readonly log: LunoraLogger;
+  /**
+  * Wall-clock time (epoch ms) the function began, captured once so the whole
+  * handler sees a single stable value. Query/mutation handlers must be
+  * deterministic — they may be re-run on OCC retry / subscription re-eval — so
+  * read time through `ctx.now` instead of `Date.now()` (the latter is flagged
+  * by the `nondeterministic_query_mutation` advisor). Actions may use `Date.now()`.
+  */
+  readonly now: number;
+  /**
+  * Compose a read-only subquery in-process, reusing this query's read
+  * context (same transaction, same `db`). Executes the referenced query's
+  * handler directly — no fresh DO RPC round-trip — so it observes the exact
+  * same snapshot. A query may only call other queries; there is no
+  * `runMutation` on a `QueryCtx` (writes are not allowed from a query).
+  * Mirrors Convex's `ctx.runQuery`.
+  */
+  readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
+  readonly storage: ReadOnlyStorage;
+  readonly vectors: VectorSearchReader;
+}
+interface MutationCtx {
+  readonly auth: AuthState;
+  readonly db: DatabaseWriter;
+  /**
+  * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
+  * forwarded server-side (never read from a client header). `undefined` when
+  * unknown: a live-subscription re-run, a server-initiated dispatch, or
+  * non-Cloudflare hosting. A convenient rate-limit key for anonymous traffic.
+  */
+  readonly ip?: string;
+  /** Structured, function-attributed logger; see {@link LunoraLogger}. */
+  readonly log: LunoraLogger;
+  /**
+  * Wall-clock time (epoch ms) the function began, captured once so the whole
+  * handler sees a single stable value. Mutation handlers must be deterministic
+  * — they may be re-run on OCC retry — so read time through `ctx.now` instead
+  * of `Date.now()` (the latter is flagged by the `nondeterministic_query_mutation`
+  * advisor). Actions may use `Date.now()`.
+  */
+  readonly now: number;
+  /**
+  * Compose a submutation in-process, reusing this mutation's `db` writer.
+  * Executes the referenced mutation's handler directly — no fresh DO RPC —
+  * so its writes apply through the same shard invocation as the enclosing
+  * mutation. Note: writes are not wrapped in a SQL transaction, so a partial
+  * failure does not roll back earlier writes (the same as a top-level
+  * mutation). Mirrors Convex's `ctx.runMutation`.
+  */
+  readonly runMutation: <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>) => Promise<R>;
+  /**
+  * Compose a read-only subquery in-process, reusing this mutation's `db`.
+  * Executes the referenced query's handler directly — no fresh DO RPC — so
+  * it observes this mutation's in-flight writes. Mirrors Convex's
+  * `ctx.runQuery`.
+  */
+  readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
+  readonly scheduler: Scheduler;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
+  readonly storage: ReadOnlyStorage;
+  readonly vectors: VectorSearch;
+  /** Start / resume / inspect durable workflows; see {@link Workflows}. */
+  readonly workflows: Workflows;
+}
+interface ActionCtx {
+  readonly auth: AuthState;
+  readonly db: DatabaseWriter;
+  readonly fetch: typeof globalThis.fetch;
+  /**
+  * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
+  * forwarded server-side (never read from a client header). `undefined` when
+  * unknown: a live-subscription re-run, a server-initiated dispatch, or
+  * non-Cloudflare hosting. A convenient rate-limit key for anonymous traffic.
+  */
+  readonly ip?: string;
+  /** Structured, function-attributed logger; see {@link LunoraLogger}. */
+  readonly log: LunoraLogger;
+  /**
+  * Wall-clock time (epoch ms) the action began, captured once for convenience
+  * and parity with query/mutation `ctx.now`. Actions run exactly once, so they
+  * may also use ambient `Date.now()` freely.
+  */
+  readonly now: number;
+  readonly runAction: <A extends ArgsValidator, R>(reference: RegisteredAction<A, R>, args: InferArgs<A>) => Promise<R>;
+  readonly runMutation: <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>) => Promise<R>;
+  readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
+  readonly scheduler: Scheduler;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
+  readonly storage: Storage;
+  readonly vectors: VectorSearch;
+  /** Start / resume / inspect durable workflows; see {@link Workflows}. */
+  readonly workflows: Workflows;
+}
+/**
+* Stand-in returned by codegen so projects can `import { api } from "./_generated/api"`.
+* The runtime value is opaque; the types are filled in by generated declarations.
+*/
+type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
+declare const anyApi: AnyApi;
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, 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 VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };