@lunora/server 1.0.0-alpha.5 → 1.0.0-alpha.50

package/dist/types.d.mts

@@ -1,4 +1,29 @@
+import { SearchLanguage, SearchStrategy } from '@lunora/search-core';
+export type { SearchLanguage, SearchStrategy } from '@lunora/search-core';
 import { ValidatorMap, InferValidatorMap, Id, Validator, Infer } from '@lunora/values';
+/**
+ * Declared HTTP caching for an exposed endpoint (`.expose({ cache })`). Lives
+ * here, alongside the path/method contract, for the same reason: the runtime
+ * WRITES these headers and the OpenAPI emitter DESCRIBES them, and the two must
+ * not be able to disagree. Deriving both from {@link cacheControlValue} /
+ * {@link cacheVaryValue} makes "the published spec matches what the runtime
+ * actually sends" structural rather than a hand-kept invariant.
+ */
+interface RestCachePolicy {
+  /**
+   * Extra request headers this app authenticates on, beyond
+   * {@link CREDENTIAL_HEADERS}. Declare these whenever `resolveIdentity` reads
+   * something else (`x-api-key`, a tenant header, …): they join both the
+   * credential check and the emitted `Vary`. Without them, a caller
+   * authenticating that way is treated as anonymous.
+   */
+  readonly credentialHeaders?: ReadonlyArray<string>;
+  readonly maxAge: number;
+  readonly scope: "private" | "public";
+  readonly staleWhileRevalidate?: number;
+  readonly tag?: string;
+  readonly vary?: string;
+}
 /** 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}. */
@@ -6,12 +31,12 @@ 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/
-*/
+ * 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 = {
@@ -23,31 +48,181 @@ type ShardMode = {
 } | {
   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 (plan 077 / 136).
+ *
+ * `"full-pull"` (the default) reads the **whole** tenant membership each tick and
+ * diffs it, so it observes upstream deletes for free — but costs a full read per tick
+ * (the Phase-0 bench put the ceiling at ~10k rows).
+ *
+ * `"incremental"` pulls **only rows past a durable watermark** (`cursor`), cheap for
+ * large low-churn tables above the full-pull cap. Because an absent row then means
+ * "unchanged", not "deleted", incremental requires a delete-visibility path: either a
+ * `reconcileEveryMs` periodic full-pull sweep, or a `softDeleteColumn` whose
+ * tombstones the pull returns. `defineSchema` throws (and the
+ * `external_source_incremental_no_delete_path` advisor lint fails the build) when an
+ * incremental source declares neither.
+ */
+type ExternalSourceMode = "full-pull" | "incremental";
+/**
+ * Incremental-ingest cursor (plan 136): the monotonic watermark column plus the
+ * watermark-parameterized pull query. `column` names the field in the pulled rows
+ * whose max becomes the next watermark (e.g. `"updated_at"`). `query` is a second
+ * SQL that returns only rows changed since the watermark — the watermark binds as
+ * the parameter AFTER `tenantBy`'s params (e.g. Postgres
+ * `... WHERE tenant_id = $1 AND updated_at >= $2 ORDER BY updated_at`). Prefer `>=`
+ * with the idempotent upsert apply so rows sharing the boundary timestamp are never
+ * skipped (re-pulling them is a no-op).
+ */
+interface ExternalSourceCursor {
+  /** The monotonic watermark column in the pulled rows; its max advances the stored watermark. */
+  column: string;
+  /** The incremental pull SQL. `tenantBy`'s params bind first, then the watermark as the trailing param. */
+  query: string;
+}
+/**
+ * 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>;
+  /** **Required for `mode: "incremental"`**: the watermark column + watermark-parameterized pull query (plan 136). Rejected on a `"full-pull"` source. */
+  cursor?: ExternalSourceCursor;
+  /** 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. `"full-pull"` (the default) diffs the whole membership; `"incremental"` pulls past a `cursor` watermark. */
+  mode?: ExternalSourceMode;
+  /** The full tenant-membership query, with driver-native placeholders (`$1` / `?`). `tenantBy` binds its params. */
+  query: string;
+  /**
+   * **Incremental delete-visibility (plan 136)**: run a full-pull sweep at most
+   * this often (millis) to GC upstream deletes an incremental slice can't see.
+   * One of `reconcileEveryMs` / `softDeleteColumn` is required for incremental;
+   * rejected on a `"full-pull"` source.
+   */
+  reconcileEveryMs?: number;
+  /** Poll cadence, or `"manual"`. Omit ⇒ the runtime's size-scaled default. */
+  refresh?: ExternalSourceRefresh;
+  /**
+   * **Incremental delete-visibility (plan 136)**: the upstream soft-delete
+   * tombstone column (e.g. `"deleted_at"`). When set, the incremental pull must
+   * return tombstoned rows and the ingest turns each into a local delete — an
+   * alternative to `reconcileEveryMs`. Rejected on a `"full-pull"` source.
+   */
+  softDeleteColumn?: string;
+  /**
+   * **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 {
+  /** Indexed text column; a dot-separated path (`"properties.name"`) reads a nested field. */
   field: string;
+  /** Columns `.eq()` may narrow by inside the search builder. At most 16. */
   filterFields?: ReadonlyArray<string>;
+  /**
+   * Text analysis for this index. Accent folding is always applied — it is
+   * what makes `café` and `cafe` the same token on every backend, which they
+   * otherwise are not. Naming a language additionally drops that language's
+   * stopwords from both documents and queries.
+   *
+   * Analysis is baked into the stored index, so changing this rebuilds it:
+   * the runtime records which profile a companion was built with and
+   * re-indexes when it no longer matches.
+   */
+  language?: SearchLanguage;
   name: string;
+  /**
+   * Skip the migration-time backfill. By default, creating the index's
+   * companion also indexes the rows already in the table, so a search index
+   * added to a populated table works immediately. On a very large table that
+   * scan is expensive to run inside a deploy: `staged: true` maintains the
+   * index on write only and leaves the initial population to an out-of-band
+   * `backfillSearchIndexes`.
+   */
+  staged?: boolean;
+  /**
+   * How the index is stored and matched.
+   *
+   * `"portable"` (default) keeps one implementation on every backend, with
+   * identical matching *and* ranking — the invariant the rest of the search
+   * docs rest on.
+   *
+   * `"native"` hands matching to the engine's own full-text index where it has
+   * one (Postgres `tsvector` + GIN today; ignored elsewhere). It scales far
+   * better on large corpora and common terms, because the portable path
+   * aggregates every matching token row before ranking. The trade: the engine
+   * ranks, so results are ordered by its formula rather than the shared
+   * scorer. Matching still agrees — the vector is built from the same analyzed
+   * tokens — but a `.global()` table using it will not return rows in the same
+   * order as the sharded twin.
+   */
+  strategy?: SearchStrategy;
+}
+/**
+ * A geospatial index declared via `.geoIndex(name, { field })`. The runtime
+ * maintains a geohash companion table over the `v.geoPoint()` column `field` so
+ * `withGeoIndex(name, q => q.near(point, radius) | q.within(bbox))` resolves a
+ * proximity / bounding-box read as a geohash-prefix range scan plus a Haversine
+ * refine/sort on the candidate rows.
+ *
+ * - `field` — the `v.geoPoint()` column whose lat/lng feed the geohash.
+ * - `precision` — geohash character length on the companion (default 9, ~4.8 m cells); higher precision narrows each cell.
+ */
+interface GeoIndexDefinition {
+  field: string;
+  name: string;
+  precision?: number;
+}
+/**
+ * Declarative table-level TTL declared via `.ttl(field, { after? })`. A DO
+ * alarm-driven sweep deletes (or, when the table also `.softDelete()`s,
+ * soft-deletes) rows whose expiry timestamp has passed.
+ *
+ * - `field` — an epoch-millisecond column. Without `after`, its value is the absolute expiry instant; with `after`, `field` is a base timestamp and the row expires `after` milliseconds later (`field + after`).
+ * - `after` — optional millisecond offset added to `field` to derive the expiry.
+ */
+interface TtlDefinition {
+  after?: number;
+  field: 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).
-*/
+ * 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;
@@ -57,32 +232,32 @@ interface AggregateIndexDefinition {
   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.
-*/
+ * 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.
-*/
+ * 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;
@@ -93,16 +268,16 @@ interface RankIndexDefinition {
 /** 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.
-*/
+ * 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";
@@ -113,15 +288,15 @@ interface RelationDefinition {
 /** 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.
-*/
+ * 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.
-*/
+ * 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;
@@ -132,74 +307,110 @@ interface TableVectorIndex {
 }
 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.
-  */
+   * 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;
+  /**
+   * Geospatial indexes declared via `.geoIndex(name, { field })`. The runtime
+   * maintains a geohash companion over the named `v.geoPoint()` column so
+   * `withGeoIndex(name, q => q.near(point, radius) | q.within(bbox))` resolves
+   * a proximity/bounding-box read as a geohash-prefix range scan plus a
+   * Haversine refine/sort. Empty unless `.geoIndex()` was called.
+   */
+  geoIndexes: ReadonlyArray<GeoIndexDefinition>;
   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(...)`.
-  */
+   * `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.
-  */
+   * `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.
-  */
+   * Set by `.ownedBy(field)` — the column holding the owning user's id (named
+   * `ownerField`, a data field, rather than colliding with the fluent
+   * `.ownedBy()` builder method — same convention as `shardBy()`/`shardMode`).
+   *
+   * A shape over this table with `owner: true` derives its predicate from this
+   * field, so "only the owner may replicate these rows" is declared once on the
+   * table instead of being restated in every shape's `where`. Absent ⇒ the table
+   * has no single owning column and a shape must spell its predicate out.
+   */
+  ownerField?: string;
+  /**
+   * 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.
-  */
+   * 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.
-  */
+   * 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}.
-  */
+   * 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>;
+  /**
+   * Set by `.ttl(field, { after })` — the declarative auto-expiry policy. A DO
+   * alarm-driven sweep deletes rows whose expiry timestamp has passed (or
+   * soft-deletes them when the table also `.softDelete()`s). Named `ttlPolicy`
+   * (a data field) rather than colliding with the fluent `.ttl()` builder
+   * method — same convention as `shardBy()`/`shardMode`. Absent ⇒ rows never
+   * auto-expire.
+   */
+  ttlPolicy?: TtlDefinition;
   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`).
-*/
+ * 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;
@@ -211,38 +422,104 @@ interface VectorIndexDefinition {
 }
 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).
-  */
+   * 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.
-*/
+ * 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";
+/**
+ * x402 payment tag attached by the `.x402({ price })` builder modifier. Marks a
+ * public procedure as paid: the origin worker answers an unpaid client RPC with
+ * HTTP 402, verifies + settles the payment, and only then dispatches to the
+ * shard. The runtime reads only `price` from here — the network, recipient, and
+ * facilitator live in the worker-level x402 charge config, so `@lunora/runtime`
+ * never has to import `@lunora/x402` (and its viem/solana deps).
+ */
+interface X402ProcedureConfig {
+  /**
+   * USD-denominated price: a number of dollars (`0.01`) or a decimal string
+   * (`"0.01"`, or the `"$0.01"` shorthand). Resolved to the network
+   * stablecoin's base units (USDC has 6 decimals) at challenge time.
+   */
+  readonly price: number | string;
+}
+/**
+ * HTTP caching for an exposed REST endpoint, declared as
+ * `.expose({ rest: true, cache: { scope: "public", maxAge: 60 } })`. The runtime
+ * turns this into `Cache-Control` / `Cache-Tag` / `Vary` response headers, and a
+ * `cache.tag` is purgeable through `ctx.cache.purge({ tags: [...] })`.
+ *
+ * This is NOT equivalent to `httpRoute(...).cacheControl()`, which writes whatever
+ * value the author passes with no credential downgrade. That is the unguarded
+ * escape hatch; this is the guarded surface.
+ *
+ * Caching a procedure whose result depends on the caller is how a REST cache
+ * turns into a data leak, so `scope` is enforced at runtime rather than trusted:
+ * a request that carries credentials (an `Authorization` header or any `Cookie`)
+ * is ALWAYS answered `private`, even under `scope: "public"` — see
+ * {@link https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control MDN}
+ * for what `private` forbids. So a per-user response can never be stored in a
+ * shared/edge cache, and the worst a mis-declared `scope` can cost is a missed
+ * cache hit. `scope: "public"` additionally emits `Vary: authorization, cookie`
+ * so an intermediary can't hand a stored anonymous variant to a signed-in caller.
+ *
+ * Only ever applied to a cacheable exchange: a `GET` (so `query` procedures — a
+ * `mutation` / `action` is `POST`-only) that produced a 2xx.
+ */
+type RestCacheConfig = RestCachePolicy;
+/**
+ * Opt-in public-surface tag attached by the `.expose({ rest: true })` builder
+ * modifier (plan 167). Marks a procedure as deliberately published over the
+ * public REST surface: the runtime mints a `/_lunora/rest/&lt;namespace>/&lt;fn>` route
+ * that dispatches THROUGH the procedure (so `ctx.auth` / RLS / validators are
+ * enforced), and the generated OpenAPI describes it. Everything is default-closed
+ * — a procedure without this tag is unreachable over REST.
+ */
+interface ExposeConfig {
+  /** Opt this endpoint's responses into HTTP caching. Omit to leave them uncached. */
+  readonly cache?: RestCacheConfig;
+  /** Publish this procedure over the public REST surface. */
+  readonly rest?: boolean;
+}
 interface RegisteredFunction<A extends ArgsValidator, R, Kind extends FunctionKind> {
   readonly args: A;
+  /**
+   * Set by the `.expose({ rest: true })` builder modifier. Marks the procedure
+   * as published on the public REST surface (plan 167). Absent on procedures that
+   * are reachable only via typed RPC (the default).
+   */
+  readonly expose?: ExposeConfig;
   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.
-  */
+   * 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;
+  /**
+   * Set by the `.x402({ price })` builder modifier. Marks the procedure as paid
+   * so the origin worker gates it behind an x402 402-challenge before dispatch.
+   * Absent on unpaid functions.
+   */
+  readonly x402?: X402ProcedureConfig;
 }
 type RegisteredQuery<A extends ArgsValidator, R> = RegisteredFunction<A, R, "query">;
 type RegisteredMutation<A extends ArgsValidator, R> = RegisteredFunction<A, R, "mutation">;
@@ -250,11 +527,11 @@ type RegisteredAction<A extends ArgsValidator, R> = RegisteredFunction<A, R, "ac
 /** 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`).
-*/
+ * 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;
@@ -266,20 +543,20 @@ interface LifecycleEvent {
   readonly userId: string | null;
 }
 /**
-* A registered connection-lifecycle hook — an internal mutation tagged with the
-* lifecycle side it fires on. Produced by `onConnect` / `onDisconnect`.
-*/
+ * 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.
-*/
+ * 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>;
@@ -289,10 +566,10 @@ interface RegisteredStream<A extends ArgsValidator, R> {
 /** 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.
-*/
+ * 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>;
@@ -322,55 +599,79 @@ interface SystemQuery<T extends SystemTableName> {
   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`.
-*/
+ * 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.)
-  */
+   * 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.
-  */
+   * 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.
-*/
+ * 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 {
+  /**
+   * The throwing sibling of {@link DatabaseReader.normalizeId}: brand `id` as an
+   * {@link Id} for `tableName`, or throw `BAD_REQUEST` when it is not structurally
+   * an id. Pure — it never reads the database, so a valid id for a row that
+   * doesn't exist still returns.
+   *
+   * This is the **parse boundary** for an id that arrived as a plain `string`: a
+   * wire payload, a mutator's args, a change plan computed on the client. The
+   * alternative is `value as Id&lt;"table">` at every such call site — an assertion,
+   * not a check, and one that has to be repeated for every table a helper is
+   * generic over:
+   *
+   * ```ts
+   * for (const patch of plan.patches) {
+   *     await ctx.db.patch(ctx.db.asId("nodes", patch.id), patch.fields);
+   * }
+   * ```
+   *
+   * Ids are opaque strings, so the check is exactly `normalizeId`'s: it rejects
+   * empty, whitespace-bearing, and NUL-bearing values, not "an id that isn't in
+   * this table". Use it to get the brand honestly, and `get()` to learn whether
+   * the row exists.
+   */
+  asId: <T extends string>(tableName: T, id: string) => Id<T>;
   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`).
-  */
+   * 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}.
-  */
+   * 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. */
@@ -378,14 +679,14 @@ 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.
-  */
+   * 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;
@@ -398,46 +699,55 @@ interface PaginationResult<T = Record<string, unknown>> {
   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.
-  */
+   * 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.
-*/
+ * 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")`.
-  */
+   * 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()`.
-  */
+   * 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>;
+  /**
+   * Restrict the query to a declared `.geoIndex()`. The builder's
+   * `.near(point, radiusMeters)` returns rows within `radiusMeters` of `point`,
+   * ordered nearest-first; `.within(bbox)` returns rows inside the
+   * latitude/longitude bounding box. Both resolve as a geohash-prefix range
+   * scan over the index's companion followed by a Haversine refine. Pair with
+   * `.take(n)` to cap results (`.paginate()` is not supported on a geo query).
+   */
+  withGeoIndex: (indexName: string, build: (q: GeoFilterBuilder) => GeoFilterBuilder) => TableReader<Row>;
   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).
-  */
+   * 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 {
@@ -454,87 +764,201 @@ interface SearchFilterBuilder {
   /** Full-text match `query` against the index's searchable `field`. Call exactly once. */
   search: (field: string, query: string) => SearchFilterBuilder;
 }
+/** A latitude/longitude point (WGS84 decimal degrees) accepted by geo queries. */
+interface GeoPointInput {
+  lat: number;
+  lng: number;
+}
 /**
-* 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`.
-*/
+ * An axis-aligned latitude/longitude bounding box: `sw` is the south-west
+ * (min lat, min lng) corner, `ne` the north-east (max lat, max lng) corner.
+ */
+interface GeoBoundingBox {
+  ne: GeoPointInput;
+  sw: GeoPointInput;
+}
+/**
+ * Builder passed to {@link TableReader.withGeoIndex}. Call exactly one of
+ * `.near(...)` / `.within(...)` — the two are mutually exclusive proximity vs
+ * bounding-box modes.
+ */
+interface GeoFilterBuilder {
+  /** Rows within `radiusMeters` of `point`, resolved nearest-first. Call exactly once. */
+  near: (point: GeoPointInput, radiusMeters: number) => GeoFilterBuilder;
+  /** Rows whose point falls inside the bounding `box`. Call exactly once. */
+  within: (box: GeoBoundingBox) => GeoFilterBuilder;
+}
+/**
+ * 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;
 }
+/** Options accepted by {@link DatabaseWriter.insertMany} and the per-table facade. */
+interface InsertManyOptions extends BatchWriteOptions {
+  /**
+   * When `true`, a UNIQUE-constraint breach for a row resolves to `null`
+   * instead of throwing — the rest of the batch is still inserted. Skipped rows
+   * keep their input-order slot with `null` in the returned array. Mirrors
+   * better-drizzle's `createMany({ skipDuplicates: true })`.
+   */
+  skipDuplicates?: boolean;
+}
 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.)
-  */
+   * Delete EVERY row in `tableName`, chunking internally until the table is
+   * empty — the erasure primitive.
+   *
+   * Unlike `deleteWhere(tableName, {})` there is **no batch cap**: a
+   * `BATCH_LIMIT_EXCEEDED` at row 501 of an account deletion is a bug, not a
+   * safety rail. Rows still go through the single-row delete pipeline, so
+   * triggers, cascades, companions, CDC, and live subscriptions stay correct.
+   *
+   * On a `.softDelete()` table the default flips the marker column; pass
+   * `{ hard: true }` to remove the rows physically (what GDPR erasure means).
+   */
+  deleteAll: (tableName: string, options?: {
+    chunkSize?: number;
+    hard?: boolean;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  /**
+   * 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.
-  */
+   * Delete every row matching `where` in one call. Matching rows are resolved
+   * first, then each row is deleted through the single-row delete pipeline
+   * (triggers, companion sync, CDC, broadcast) so reactive subscriptions and
+   * search/aggregate companions stay correct.
+   *
+   * **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.
+   */
+  deleteWhere: (tableName: string, where: Record<string, unknown>, 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.
-  */
+   * 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.
+   *
+   * Pass `{ skipDuplicates: true }` to turn UNIQUE-constraint breaches into
+   * `null` results for that row instead of failing the whole batch; the rest of
+   * the batch is still inserted and order is preserved.
+   *
+   * **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 & {
+      skipDuplicates: true;
+    }): Promise<(Id<T> | null)[]>;
+    <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options?: InsertManyOptions): 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.)
-  */
+   * Patch many rows by id in one call. Each `{ id, patch }` is applied like a
+   * single `patch()` (per-row triggers + RLS). Returns the number of rows
+   * actually patched.
+   *
+   * **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>;
+  }>, options?: BatchWriteOptions) => Promise<{
+    patched: number;
+  }>;
+  /**
+   * Patch every row matching `where` with the same `patch` in one call. The
+   * matching rows are resolved first, then each row is updated through the
+   * single-row patch pipeline (OCC, triggers, companion sync, CDC, broadcast)
+   * so reactive subscriptions and search/aggregate companions stay correct.
+   *
+   * **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.
+   */
+  patchWhere: (tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: Record<string, unknown>;
+  }, options?: BatchWriteOptions) => Promise<{
+    patched: number;
+  }>;
   replace: <T extends string>(id: Id<T>, document: Record<string, unknown>) => Promise<void>;
+  /**
+   * Erase every shard-local table — the account-deletion / tenant-teardown
+   * primitive. Sweeps the schema's non-`.global()` tables with
+   * {@link DatabaseWriter.deleteAll}`({ hard: true })` and returns the per-table
+   * counts.
+   *
+   * `.global()` tables are skipped by design: their rows live in D1 and are shared
+   * across shards, so "wipe this shard" must not reach them. Restrict the sweep
+   * with `options.tables`, or spare one with `options.exclude` (e.g. an audit log
+   * that must outlive the data).
+   *
+   * ```ts
+   * export const deleteAccount = internalMutation({ handler: async ({ ctx }) => ctx.db.wipeShard() });
+   * ```
+   */
+  wipeShard: (options?: {
+    chunkSize?: number;
+    exclude?: ReadonlyArray<string>;
+    tables?: ReadonlyArray<string>;
+  }) => Promise<{
+    deleted: number;
+    tables: Record<string, number>;
+  }>;
 }
 /** Authenticated identity surfaced into every context. */
 interface AuthState {
@@ -542,11 +966,11 @@ interface AuthState {
   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.
-*/
+ * 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). */
@@ -560,6 +984,21 @@ interface ScheduledJob {
   /** Routing hint forwarded so dispatch lands on the right shard. */
   shardKey?: string;
 }
+/**
+ * A schedulable durable-workflow reference — the generated `workflows.&lt;name>` /
+ * `agents.&lt;name>` object, which carries its `WORKFLOW_*`/`AGENT_*` binding and
+ * stable name. Structural mirror of `@lunora/scheduler`'s `WorkflowReference` so
+ * `ctx.scheduler` can target a workflow/agent without a dependency on
+ * `@lunora/scheduler` / `@lunora/workflow`. A scheduled workflow target starts a
+ * fresh instance on fire (the args become its `params`).
+ */
+interface SchedulableWorkflowReference {
+  /** The `WORKFLOW_*`/`AGENT_*` binding name (present on a generated ref). */
+  readonly binding?: string;
+  readonly isLunoraWorkflow: true;
+  /** The workflow/agent export/stable name (present on a generated ref). */
+  readonly name?: string;
+}
 interface Scheduler {
   /** Cancel a pending job by id. `cancelled` is `false` when no such job exists. */
   cancel: (id: string) => Promise<{
@@ -569,16 +1008,23 @@ interface Scheduler {
   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>;
+  /**
+   * Schedule a one-shot run `delayMs` from now. `target` is a function path
+   * (`"ns:fn"`) dispatched as a one-shot, or a generated `workflows.&lt;name>` /
+   * `agents.&lt;name>` reference which starts a fresh durable instance on fire
+   * (the args become its `params`).
+   */
+  runAfter: (delayMs: number, target: SchedulableWorkflowReference | string, args?: Record<string, unknown>) => Promise<string>;
+  /** Like {@link Scheduler.runAfter} but fires at an absolute epoch-ms timestamp. */
+  runAt: (timestampMs: number, target: SchedulableWorkflowReference | 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`.
-*/
+ * 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 {
@@ -615,9 +1061,9 @@ interface WorkflowInstance {
   terminate: () => Promise<void>;
 }
 /**
-* A typed handle to one declared workflow, addressable from `ctx.workflows`.
-* Mirrors `@lunora/workflow`'s `WorkflowHandle`.
-*/
+ * 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>;
@@ -627,36 +1073,51 @@ interface WorkflowHandle<Params = Record<string, unknown>> {
   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`.
-*/
+ * 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.
-*/
+ * Programmatic cache purge surface exposed on {@link ActionCtx}. Actions run
+ * in the Worker (not the DO), so they can reach the Worker's `ctx.cache.purge`.
+ * Queries and mutations do not expose this — they run inside the Durable Object.
+ */
+interface CachePurge {
+  /**
+   * Purge cached responses matching the given tags, or everything when
+   * `purgeEverything` is true. Only available in action handlers.
+   */
+  purge: (options: {
+    purgeEverything?: boolean;
+    tags?: string[];
+  }) => Promise<unknown>;
+}
+/**
+ * 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.
-*/
+ * `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>;
@@ -666,11 +1127,11 @@ 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]> } & {
+ * 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;
 };
@@ -682,11 +1143,11 @@ interface TriggerInsertEvent<Shape extends Record<string, Validator> = Record<st
   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.
-*/
+ * 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;
@@ -695,10 +1156,10 @@ interface TriggerUpdateEvent<Shape extends Record<string, Validator> = Record<st
   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.
-*/
+ * 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";
@@ -722,10 +1183,10 @@ interface TriggerQueryArgs {
   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.
-*/
+ * 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;
@@ -770,17 +1231,17 @@ interface TriggerRankPageOptions {
   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).
-*/
+ * 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>;
@@ -796,10 +1257,10 @@ interface TriggerDatabase {
   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).
-*/
+ * 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;
@@ -807,20 +1268,20 @@ interface TriggerCtx {
 /** 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.
-*/
+ * 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`.
-*/
+ * 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;
@@ -830,11 +1291,11 @@ interface TriggerBuilder<Shape extends Record<string, Validator> = Record<string
   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`.
-*/
+ * 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;
@@ -850,31 +1311,31 @@ interface StorageMetadata {
   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`.
-*/
+ * 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.
-  */
+   * 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`.
-  */
+   * 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?: {
@@ -888,20 +1349,20 @@ interface Storage<Buckets extends string = string> extends ReadOnlyStorage<Bucke
   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`.
-  */
+   * 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.
-  */
+   * 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;
@@ -945,144 +1406,484 @@ interface VectorRecord {
   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>;
+ * 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<IndexName extends string = string> {
+  getByIds: (indexName: IndexName, ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorRecord>>;
+  query: (indexName: IndexName, 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<IndexName extends string = string> extends VectorSearchReader<IndexName> {
+  deleteByIds: (indexName: IndexName, ids: ReadonlyArray<string>) => Promise<void>;
+  upsert: (indexName: IndexName, input: VectorUpsertInput) => Promise<void>;
+  upsertNow: (indexName: IndexName, input: VectorUpsertInput) => Promise<void>;
 }
 /**
-* 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, filterable key/value fields attached to a log line — the second
+ * argument of a `ctx.log.&lt;level>(message, fields)` call, or the fields bound by
+ * `ctx.log.with(fields)`. They travel to an `ObservabilitySink`'s `onLog` and,
+ * for a network sink, become OTLP log-record attributes a log pipeline (or the
+ * Cloud log viewer) can filter and index on. Primitive values pass through;
+ * objects/arrays are JSON-encoded at the sink boundary.
+ */
+type LogFields = Record<string, unknown>;
+/**
+ * One `ctx.log` severity method. Two call forms:
+ *
+ * - **Structured** — `ctx.log.info("order placed", { orderId, total })`: a message string plus a `fields` object. The fields are indexed as attributes.
+ * - **Console-style** — `ctx.log.info("state", value, other)`: any number of values, joined into the display message exactly like `console.log`.
+ *
+ * The structured form is matched when the second argument is a plain object;
+ * otherwise the call is treated as console-style, so existing `console`-shaped
+ * calls keep working unchanged.
+ */
+interface LunoraLogMethod {
+  (message: string, fields?: LogFields): void;
+  (...args: unknown[]): 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.
-*/
+ * 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, structured fields, and a routable transport.
+ *
+ * Six severities spanning the OpenTelemetry ramp: `trace`, `debug`, `info` (and
+ * its `log` alias), `warn`, `error`, `fatal`.
+ *
+ * Two ways to attach structured {@link LogFields}: pass them per call
+ * (`ctx.log.info(message, fields)`) or bind them once with {@link with} for a
+ * child logger that stamps every line. The rendered `message` and the structured
+ * `fields` reach the dev terminal and the platform's Workers Logs; the raw,
+ * un-rendered console-style arguments are preserved ONLY on the in-process
+ * `onLog` sink (which you opt into and control).
+ *
+ * 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;
+  readonly debug: LunoraLogMethod;
+  readonly error: LunoraLogMethod;
+  /**
+   * Emit a **structured event** instead of a log line — OpenTelemetry's Events
+   * API, on the wire as `LogRecord.eventName` (plus an `event.name` attribute
+   * for collectors predating that field).
+   *
+   * ```ts
+   * ctx.log.event("checkout.completed", { plan: user.plan, total, currency });
+   * ```
+   *
+   * The difference from `ctx.log.info("checkout completed", { … })` is what a
+   * backend can do with it. A log line's payload is its message: prose, written
+   * for a human, free to be reworded next sprint — so "how many checkouts
+   * completed, by plan, this hour" degrades into a substring search over
+   * English. An event's payload is its `fields` under a **stable name**, which a
+   * collector can index, group, and alert on directly.
+   *
+   * Rule of thumb: `log.*` for narration you'd read while debugging, `event` for
+   * anything you'd ever put on a dashboard. And for facts about the request as a
+   * whole, prefer `ctx.span` — one wide event beats a dozen
+   * events, however well named.
+   */
+  readonly event: (name: string, fields?: LogFields) => void;
+  readonly fatal: LunoraLogMethod;
+  readonly info: LunoraLogMethod;
+  readonly log: LunoraLogMethod;
+  readonly trace: LunoraLogMethod;
+  readonly warn: LunoraLogMethod;
+  /**
+   * Return a child logger that stamps `fields` onto every line it emits,
+   * merged under any per-call fields (per-call wins on a key clash). Chainable
+   * — `ctx.log.with({ requestId }).with({ step })` accumulates both. Use it to
+   * bind request-scoped context once instead of repeating it per call.
+   */
+  readonly with: (fields: LogFields) => LunoraLogger;
+}
+/**
+ * Handle the enclosing `ctx.trace` span hands its body, so the body can attach
+ * attributes only known *after* it resolves (an AI call's token usage / dollar
+ * cost, a downstream status, a computed count). Declared structurally here to
+ * mirror `shared/span-event.ts`'s `SpanHandle` and `@lunora/do`'s implementation;
+ * a cross-package assignability guard in `@lunora/testing` fails the build if the
+ * three drift apart. Start attributes are snapshotted before the body runs;
+ * handle writes are merged over them at record time, post-hoc winning on a clash.
+ */
+/**
+ * One AI **evaluation** verdict — a scorer's `{name, score, label?}` — to attach
+ * to a generation span via {@link SpanHandle.recordEvaluation}. Declared
+ * structurally to mirror `shared/evaluation-attributes.ts`'s `EvaluationInput`
+ * without a dependency edge.
+ */
+interface SpanEvaluation {
+  /** Optional categorical label (e.g. `"pass"` / `"fail"`), emitted as `.label`. */
+  label?: string;
+  /** Scorer name — the key's name segment; non-`[A-Za-z0-9._-]` chars become `_`. */
+  name: string;
+  /** Numeric score (typically `[0, 1]`), emitted as `.score`. */
+  score: number;
+}
+interface SpanHandle {
+  /**
+   * Record a timestamped event on the enclosing span — a retry, a cache miss, a
+   * state transition. Prefer this over an extra `ctx.log` line for anything that
+   * only makes sense *relative to this span*: it rides the span's own export, so
+   * it costs no additional record and can never be separated from its context.
+   */
+  addEvent: (name: string, attributes?: LogFields) => void;
+  /**
+   * Link this span to one in another trace — how a queue consumer points back at
+   * the request that enqueued its message without collapsing every producer into
+   * one giant trace.
+   */
+  addLink: (link: SpanLink) => void;
+  /**
+   * Attach an AI **evaluation** verdict to this (generation) span as the
+   * `gen_ai.evaluation.&lt;name>.score` / `.label` OpenTelemetry attributes, so a
+   * scorer's grade rides the same trace as the generation it graded. Convenience
+   * over {@link SpanHandle.setAttributes} that owns the key format; privacy-safe —
+   * only the name, score, and optional label are emitted. Throws on an empty name
+   * or a non-finite score.
+   */
+  recordEvaluation: (evaluation: SpanEvaluation) => void;
+  /**
+   * Record a **handled** exception as the OTel-conventional `exception` span
+   * event (`exception.type` / `exception.message` / `exception.stacktrace`),
+   * without marking the span failed.
+   *
+   * For an error you swallowed — a retried request, a fallback that worked. An
+   * error that escapes the span body is recorded automatically and *does* set
+   * the error status, so don't call this for one you're re-throwing.
+   */
+  recordException: (error: unknown) => void;
+  /** Set one attribute on the enclosing span (merged at record time; post-hoc wins on key clash). */
+  setAttribute: (key: string, value: LogFields[string]) => void;
+  /** Merge attributes onto the enclosing span (post-hoc wins on key clash). */
+  setAttributes: (fields: LogFields) => void;
+  /**
+   * The W3C ids of the span this handle refers to (32-hex trace, 16-hex span).
+   *
+   * On `ctx.span` these are the DISPATCH's ids — the trace the whole request
+   * belongs to. Use it to echo a trace id back to a caller so a user can quote
+   * it in a bug report, to build a `traceparent` for a hand-rolled outbound
+   * call, or to parent a third-party library's spans onto this request.
+   */
+  spanContext: () => {
+    spanId: string;
+    traceId: string;
+  };
+}
+/**
+ * A causal reference to a span in another trace (OTel `Span.links`). Ids are
+ * lowercase hex — 32 chars for `traceId`, 16 for `spanId`.
+ */
+interface SpanLink {
+  /** Attributes describing the relationship, e.g. `{ "link.kind": "enqueued_by" }`. */
+  attributes?: LogFields;
+  spanId: string;
+  traceId: string;
+}
+/** OTel `SpanKind`. Drives a collector's service map — see {@link SpanOptions.kind}. */
+type SpanKind = "client" | "consumer" | "internal" | "producer" | "server";
+/** Options accepted by `ctx.trace(name, fn, options)` beyond a plain attribute bag. */
+interface SpanOptions {
+  /** Start attributes, snapshotted before the body runs. */
+  attributes?: LogFields;
+  /**
+   * OTel `SpanKind`, default `"internal"`. Set `"client"` for a call OUT to
+   * another service and `"producer"`/`"consumer"` for queue hops: a collector
+   * builds its service map from this, so leaving everything `"internal"` yields
+   * a trace with no topology.
+   */
+  kind?: SpanKind;
+  /** Links to spans in other traces, known at span start. */
+  links?: SpanLink[];
+}
+/**
+ * Span factory on every function `ctx`. Wraps a sub-operation so it becomes its
+ * own **span** nested under the dispatch's RPC span, giving a trace real shape:
+ * without it a slow request is one opaque bar, with it you see which part was
+ * slow.
+ *
+ * ```ts
+ * const charge = await ctx.trace("stripe.charge", () => stripe.charges.create(…), { orderId });
+ * ```
+ *
+ * **Nesting is explicit.** The body receives a tracer bound to its own span;
+ * calling *that* is what makes a child:
+ *
+ * ```ts
+ * await ctx.trace("fulfil", async (trace) => {
+ *     // Children of "fulfil" — including under Promise.all, where an ambient
+ *     // "currently open span" would mis-record these as nested inside each other.
+ *     await Promise.all([trace("reserve.stock", …), trace("email.receipt", …)]);
+ * });
+ * ```
+ *
+ * Calling `ctx.trace` again inside a body (rather than the passed tracer) is not
+ * an error — that span is simply parented to the dispatch instead of to the
+ * enclosing span, which is flatter but never wrong.
+ *
+ * Spans share the dispatch's trace id with its `ctx.log` lines and any container
+ * the handler calls (the same `traceparent` is propagated), so one trace spans
+ * worker, shard, and container.
+ *
+ * The span is recorded when the body settles, and the body's value is returned
+ * unchanged. A throw is recorded as an error span and then **re-thrown** — this
+ * is instrumentation, never flow control. Recording is best-effort: a failing
+ * sink can't turn a working handler into a broken one.
+ *
+ * **Post-hoc attributes.** The body also receives a {@link SpanHandle} as its
+ * second argument. The `attributes` passed here are stamped at span start (and
+ * snapshotted, so a later mutation can't rewrite them); anything the body sets
+ * through the handle — `span.setAttribute(k, v)` / `span.setAttributes({…})` — is
+ * merged over that snapshot when the span is recorded, so a value known only once
+ * the body has resolved (an AI call's token usage / dollar cost, a computed
+ * count) still lands on the span. Post-hoc wins on a key clash. The handle is a
+ * trailing parameter, so every existing `(trace) => …` body keeps working
+ * unchanged.
+ * @param name Span name, e.g. `"stripe.charge"`. Prefer a low-cardinality name
+ * and put the varying part in `attributes` — a name built from an id makes every
+ * span its own group in a collector.
+ * @param fn The body to time, receiving a tracer bound to this span for any
+ * nested spans and the enclosing span's {@link SpanHandle} for post-hoc
+ * attributes. May be sync or async; the result is awaited.
+ * @param attributes Either a plain attribute bag to stamp on the span at start
+ * (normalized like a log line's `fields`), or a {@link SpanOptions} object when
+ * you need `kind` or `links`. It is read as options only when *every* key is one
+ * of `attributes`/`kind`/`links`; `{ attributes: { kind: "premium" } }` is the
+ * explicit form if your own attributes happen to be named that.
+ */
+type LunoraTracer = <T>(name: string, function_: (trace: LunoraTracer, span: SpanHandle) => Promise<T> | T, attributes?: LogFields | SpanOptions) => Promise<T>;
+/**
+ * `ctx.span` — a handle onto **this request's own span**, and with it the
+ * wide-event API.
+ *
+ * ```ts
+ * export const checkout = mutation({ handler: async (ctx, args) => {
+ *     ctx.span.setAttributes({ "user.plan": user.plan, "cart.items": cart.length });
+ *     const payment = await charge(cart);
+ *     ctx.span.setAttributes({ "payment.provider": payment.provider, "payment.total": payment.total });
+ *     if (payment.retried) ctx.span.addEvent("payment.retried", { attempts: payment.attempts });
+ *     return payment;
+ * }});
+ * ```
+ *
+ * **Why this instead of more log lines.** The usual way to make a handler
+ * observable is to sprinkle `ctx.log.info` through it, which costs one record per
+ * call, scatters one request's facts across a dozen rows, and forces every
+ * question to be answered by correlating them back together. The wide-event
+ * pattern inverts that: accumulate the facts as you learn them, and emit **one**
+ * richly-attributed record per unit of work. Cost is flat — one span per request
+ * no matter how much you attach — and every question ("p99 checkout latency for
+ * pro-plan users with >10 items") becomes a single filter over one table instead
+ * of a join across log lines.
+ *
+ * **This is plain OpenTelemetry, not a Lunora convention.** The attributes land
+ * on the span the dispatch already emits, and are additionally exported as an
+ * OTel Event record named `lunora.dispatch`, correlated by `trace_id`/`span_id`.
+ * Any OTLP backend groups and aggregates them with no special configuration.
+ *
+ * **`span` vs `trace`.** `ctx.trace(name, fn)` creates a NEW child span to time a
+ * sub-operation; `ctx.span` attaches to the one that already exists for the
+ * request. Use `trace` for "how long did this part take", `span` for "what was
+ * true about this request". Inside a `ctx.trace` body, the handle passed as the
+ * body's second argument is that child span's equivalent of this.
+ *
+ * Attributes are normalized exactly like `ctx.log` fields, and recording is
+ * best-effort — a telemetry failure never breaks the handler.
+ */
+type LunoraWideEvent = SpanHandle;
+/**
+ * Application metrics on every function `ctx` — the third signal alongside
+ * `ctx.log` and `ctx.trace`. Each call records one measurement that flows to an
+ * `ObservabilitySink`'s `onMetric`, and from `otlpSink` to a collector's
+ * `/v1/metrics`.
+ *
+ * ```ts
+ * ctx.metrics.count("orders.placed", 1, { plan: user.plan });
+ * ctx.metrics.record("checkout.latency_ms", Date.now() - started);
+ * ctx.metrics.gauge("cart.items", cart.items.length);
+ * ```
+ *
+ * Pick the instrument by the question you want to answer: `count` for "how many"
+ * (summed over time), `gauge` for "how many right now" (replaces the last
+ * reading), `record` for "what's the distribution" (percentiles, not just a
+ * mean).
+ *
+ * `attributes` are the metric's dimensions. Keep them **low-cardinality** — an
+ * attribute valued by user id or order id creates a distinct time series per id,
+ * which is how a metrics backend gets expensive. Put identifiers on a log line or
+ * a span instead.
+ *
+ * No pre-aggregation happens: one call is one exported measurement, with counter
+ * deltas for the collector to sum. In a hot loop, sum locally and record once
+ * rather than calling per iteration.
+ */
+interface LunoraMetrics {
+  /**
+   * Add to a monotonic counter (default `1`) — requests served, retries,
+   * bytes sent. The collector sums successive deltas.
+   */
+  readonly count: (name: string, value?: number, attributes?: LogFields) => void;
+  /**
+   * Report a point-in-time reading that replaces the previous one — queue
+   * depth, cache size, connections open.
+   */
+  readonly gauge: (name: string, value: number, attributes?: LogFields) => void;
+  /**
+   * Observe one sample of a distribution — latency, payload size. Use this,
+   * not a counter, when percentiles matter.
+   */
+  readonly record: (name: string, value: number, attributes?: LogFields) => 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.
-  */
+   * The validated, typed environment. Populated only when the project declares
+   * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+   * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+   * coercion-aware. Absent (optional) without a contract — declare
+   * `lunora/env.ts` to populate and type it.
+   */
+  readonly env?: Record<string, unknown>;
+  /**
+   * 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;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
-  * 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()`.
-  */
+   * 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`.
-  */
+   * 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;
+  /** Attach facts to THIS request's span — the wide event; see {@link LunoraWideEvent}. */
+  readonly span: LunoraWideEvent;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   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.
-  */
+   * The validated, typed environment. Populated only when the project declares
+   * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+   * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+   * coercion-aware. Absent (optional) without a contract — declare
+   * `lunora/env.ts` to populate and type it.
+   */
+  readonly env?: Record<string, unknown>;
+  /**
+   * 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;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
-  * 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()`.
-  */
+   * 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`.
-  */
+   * 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`.
-  */
+   * 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;
+  /** Attach facts to THIS request's span — the wide event; see {@link LunoraWideEvent}. */
+  readonly span: LunoraWideEvent;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
   readonly workflows: Workflows;
 }
 interface ActionCtx {
   readonly auth: AuthState;
+  /**
+   * Programmatic Workers Cache purge; see {@link CachePurge}.
+   * **Action-only** — actions run in the Worker, which has a `cache` binding.
+   * Queries and mutations run inside the Durable Object and do not expose this.
+   * Optional at runtime because Workers Cache is only present when enabled.
+   */
+  readonly cache?: CachePurge;
   readonly db: DatabaseWriter;
+  /**
+   * The validated, typed environment. Populated only when the project declares
+   * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+   * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+   * coercion-aware. Absent (optional) without a contract — declare
+   * `lunora/env.ts` to populate and type it.
+   */
+  readonly env?: Record<string, unknown>;
   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.
-  */
+   * 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;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
-  * 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.
-  */
+   * 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>;
@@ -1090,15 +1891,19 @@ interface ActionCtx {
   readonly scheduler: Scheduler;
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
+  /** Attach facts to THIS request's span — the wide event; see {@link LunoraWideEvent}. */
+  readonly span: LunoraWideEvent;
   readonly storage: Storage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   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.
-*/
+ * 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 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 };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExposeConfig, type ExternalSourceCursor, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GeoBoundingBox, type GeoFilterBuilder, type GeoIndexDefinition, type GeoPointInput, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type LunoraWideEvent, 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 RestCacheConfig, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type SpanEvaluation, type SpanHandle, type SpanKind, type SpanLink, type SpanOptions, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type 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 TtlDefinition, 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, type X402ProcedureConfig, anyApi };