@lunora/do 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -195,10 +195,17 @@ interface RelationDefinitionLike {
   readonly references: string;
   readonly table: string;
 }
-/** Per-relation refinements: filter / order / cap / recurse into the children. */
+/** Per-relation refinements: filter / order / cap / project / recurse into the children. */
 interface NestedWith {
   limit?: number;
   orderBy?: OrderByInput[];
+  /**
+  * Project each loaded child down to these fields (like the top-level
+  * `findMany` `select`). Applied AFTER grouping, so the join key stays
+  * available to map children to parents; `_id`/`_creationTime` and any deeper
+  * `with` relations are always retained.
+  */
+  select?: ReadonlyArray<string>;
   where?: WhereInput;
   with?: WithInput;
 }
@@ -212,8 +219,17 @@ interface WithInput {
   _count?: Record<string, true>;
 }
 interface ResolveWithOptions {
-  counter: (tableName: string, where?: WhereInput) => Promise<number>;
   fetcher: (tableName: string, args: QueryArgs) => Promise<QueryPage>;
+  /**
+  * Grouped aggregate: for every FK value in `values`, return the count of
+  * child rows in `tableName` whose `whereField` equals that value,
+  * optionally AND-ing in `policyWhere` (the child table's RLS read filter).
+  * Returns a `Map` keyed by FK value with the per-group count — missing
+  * keys (groups with zero children) are not included; callers default to 0.
+  * A single `GROUP BY :whereField … WHERE :whereField IN (values)` query
+  * replaces the former one-query-per-distinct-value loop.
+  */
+  groupedCounter: (tableName: string, whereField: string, values: unknown[], policyWhere?: WhereInput) => Promise<Map<unknown, number>>;
   parents: Record<string, unknown>[];
   /**
   * Per-target-table read filter (RLS) applied to each relation fetch/count and
@@ -227,7 +243,18 @@ interface ResolveWithOptions {
   tableName: string;
   with: WithInput;
 }
+/**
+* Cross-backend fan-out for grouped `_count` on backends whose `groupedCounter`
+* must fall back to scalar calls (e.g. a DO's global-D1 child or the sql-store's
+* cross-shard reverse direction). Issues one `counter(table, where)` per FK
+* value in parallel and collects the results into a Map.
+*
+* Used by both the DO and sql-store `relationGroupedCounter` implementations so
+* the parallel fan-out logic isn't duplicated.
+*/
+declare const fanOutScalarCounts: (counter: (tableName: string, where?: WhereInput) => Promise<number>, tableName: string, whereField: string, values: unknown[], policyWhere: WhereInput | undefined) => Promise<Map<unknown, number>>;
 /** Distinct, non-nullish values of `field` across `rows`, preserving first-seen order. */
+
 /**
 * Resolve every requested relation on `parents` (a single already-fetched
 * page), mutating each parent in place: `one` → `Doc | null`, `many` →
@@ -289,9 +316,9 @@ declare const applyOnDelete: (options: ApplyOnDeleteOptions) => Promise<void>;
 * fakes (which never carry a runtime parser) keep working.
 */
 declare const runRowValidators: (definition: TableDefinitionLike, document: Record<string, unknown>) => void;
-type SortDirection$1 = "asc" | "desc";
+type SortDirection = "asc" | "desc";
 /** A single `{ field: "asc" | "desc" }` entry; `orderBy` is an ordered list of these. */
-type OrderByInput = Record<string, SortDirection$1>;
+type OrderByInput = Record<string, SortDirection>;
 interface QueryArgs {
   /**
   * Predicate injected by the runtime (e.g. by `@lunora/server`'s RLS
@@ -304,6 +331,12 @@ interface QueryArgs {
   */
   baseWhere?: WhereInput;
   cursor?: null | string;
+  /**
+  * Opt a list read OUT of soft-delete scoping: when `true`, rows whose
+  * soft-delete column is set are INCLUDED. Has no effect on a table without
+  * `.softDelete()`. Default (absent/false) hides soft-deleted rows.
+  */
+  includeDeleted?: boolean;
   limit?: number;
   orderBy?: OrderByInput[];
   /**
@@ -324,6 +357,15 @@ interface QueryArgs {
   * reads (`findMany`/`findFirst`) — this flag specifically guards `count`.
   */
   restrictsCounts?: boolean;
+  /**
+  * Project each returned row down to these fields. The system fields `_id` and
+  * `_creationTime` are always retained (cursors + by-id reuse depend on them),
+  * and any relations attached via `with` (their relation keys and `_count`)
+  * survive the trim. Applied AFTER the rows are read and relations resolved, so
+  * read-dependency tracking and cursor encoding see the full row — only the
+  * payload returned to the caller is narrowed. Omit for the full document.
+  */
+  select?: ReadonlyArray<string>;
   where?: WhereInput;
   with?: WithInput;
 }
@@ -341,7 +383,7 @@ interface QueryPage {
   splitCursor?: null | string;
 }
 interface OrderKey {
-  direction: SortDirection$1;
+  direction: SortDirection;
   field: string;
 }
 /**
@@ -376,6 +418,26 @@ declare const buildSeekWhere: (keys: OrderKey[], cursorValues: unknown[]) => Whe
 * the page it terminates. Reactive pagination uses this for a page's fixed end
 * cursor; the shared compiler renders it per dialect.
 */
+
+/**
+* Project `page` rows down to `select` — plus the always-kept system fields and
+* the relation/`_count` keys attached by a `with` load (passed as `withInput`,
+* the same object handed to `findMany`). Returns the page unchanged when
+* `select` is undefined. Pure; callers apply it AFTER relation resolution +
+* cursor encoding so only the returned payload is trimmed (dependency tracking +
+* the cursor still see the full row).
+*/
+declare const applySelect: (page: Record<string, unknown>[], select: ReadonlyArray<string> | undefined, withInput?: Record<string, unknown>) => Record<string, unknown>[];
+/**
+* The read-scope predicate that hides soft-deleted rows — `{ [field]: { isNull:
+* true } }` matching the live rows whose soft-delete column is null/absent — or
+* `undefined` when the table isn't `.softDelete()` or the read opted in via
+* `includeDeleted`. AND-merge it into a list read's `where` (the by-id path
+* never calls this, so `get`/`patch`/`replace`/`restore` still address the row).
+*/
+declare const softDeleteScope: (softDeleteMode: {
+  field: string;
+} | undefined, includeDeleted: boolean | undefined) => undefined | WhereInput;
 type RankDirection = "asc" | "desc";
 interface RankSortKeyLike {
   readonly direction: RankDirection;
@@ -554,6 +616,7 @@ declare const rankTableName: (table: string, indexName: string) => string;
 * - `sortValues[i]` === `serializeSqlValue(doc[index.sortBy[i].field])` — the same transform `syncRankIndexEntry` applies to the stored `__sort_k&lt;i>__` column, so the comparison is byte-for-byte (and JSON-safe for the cross-shard wire) regardless of which shard owns the row. `rankBefore` re-applies it idempotently, so a direct caller passing raw values still works.
 * - `rowId` === `doc._id`, the `__id__` tiebreak.
 */
+declare const stableStringify: (value: unknown) => string;
 /** A single memoized result, the deps it read, and any active subscribers. */
 interface CacheEntry {
   /** Approximate serialized size of `result`, charged against `maxBytes`. */
@@ -686,16 +749,6 @@ declare class ReactiveCache {
   private evict;
 }
 /**
-* Stable, sorted JSON encoding of `args` for use in a cache key. Object keys
-* are visited in lexical order at every depth so `{ a: 1, b: 2 }` and
-* `{ b: 2, a: 1 }` hash to the same string. Arrays preserve their order
-* (the index IS the key). `undefined` values are skipped at the object level
-* so `{ a: undefined }` collides with `{}` — matches Convex behavior and
-* avoids spurious cache misses on optional args. Inside arrays `undefined`
-* encodes as `null` to keep positional semantics.
-*/
-declare const stableStringify: (value: unknown) => string;
-/**
 * Compose a cache key from a function path, a stably-encoded args object, and
 * the caller's identity discriminator. Exported so the wiring layer and tests
 * build identical keys without each side reinventing the format.
@@ -951,7 +1004,32 @@ interface SubscriptionQuery {
   */
   table?: string;
 }
+/**
+* A live shape subscription registered on a socket — the partial-replication
+* parallel to {@link SubscriptionQuery}. The client names a `defineShape` shape
+* and supplies validated `args`; the DO resolves it to a table + RLS-composed
+* `effectiveWhere` under the socket's verified identity (never the client's
+* word) and pokes the membership diff. `sinceSeq`/`sinceEpoch` carry the
+* client's last applied checkpoint for resume.
+*/
+interface ShapeSubscriptionQuery {
+  /** Validated shape arguments (e.g. `{ channelId }`); forwarded to `resolveShape`. */
+  args?: Record<string, unknown>;
+  /** Registered shape name (the `defineShape` export the codegen subclass resolves). */
+  name: string;
+  /** Resume epoch the client persisted alongside {@link ShapeSubscriptionQuery.sinceSeq} (see {@link SubscriptionQuery.sinceEpoch}). */
+  sinceEpoch?: string;
+  /** Resume checkpoint: the `__cdc_log` cursor the client's view of this shape last reflected (see {@link SubscriptionQuery.sinceSeq}). */
+  sinceSeq?: number;
+}
 interface SubscriptionEnvelope {
+  /**
+  * Stable per-client id carried by the `connect` envelope. Recorded on the
+  * socket attachment so a shape poke can echo this client's
+  * `__client_watermark` as its `lastMutationId`. Ignored on other envelope
+  * types; absent for clients that don't use custom mutators.
+  */
+  clientId?: string;
   /**
   * App-supplied connection context carried by the `connect` envelope (e.g.
   * `{ roomId, sessionId }`). Merged into the socket attachment and forwarded
@@ -966,6 +1044,19 @@ interface SubscriptionEnvelope {
   id: string;
   query?: SubscriptionQuery;
   /**
+  * Shape descriptor of a `shape_subscribe` envelope: the named shape + its
+  * validated args. Carries the client's resume checkpoint via
+  * {@link SubscriptionEnvelope.sinceCheckpoint}/{@link SubscriptionEnvelope.sinceEpoch}.
+  */
+  shape?: {
+    args?: Record<string, unknown>;
+    name: string;
+  };
+  /** Resume checkpoint on a `shape_subscribe` envelope (the `__cdc_log` cursor the client's shape view is at). */
+  sinceCheckpoint?: number;
+  /** CDC epoch the {@link SubscriptionEnvelope.sinceCheckpoint} belongs to. */
+  sinceEpoch?: string;
+  /**
   * Topic of a `whisper`/`whisper_subscribe`/`whisper_unsubscribe` envelope —
   * an app-chosen channel name (e.g. `"room:42:cursors"`) scoped to this shard.
   */
@@ -983,7 +1074,7 @@ interface SubscriptionEnvelope {
   * this shard with NO SQLite/CDC write (AnyCable-style whispering — typing
   * indicators, live cursors). The sender never receives its own whisper.
   */
-  type: "ack" | "connect" | "stream" | "subscribe" | "unsubscribe" | "whisper" | "whisper_subscribe" | "whisper_unsubscribe";
+  type: "ack" | "connect" | "shape_subscribe" | "shape_unsubscribe" | "stream" | "subscribe" | "unsubscribe" | "whisper" | "whisper_subscribe" | "whisper_unsubscribe";
 }
 /**
 * The argument a connection-lifecycle hook receives. Structurally matches
@@ -1058,6 +1149,15 @@ interface SocketAttachment {
   */
   admin?: boolean;
   /**
+  * Stable per-client id from the `connect` envelope (the same id the client
+  * stamps on its custom-mutator pushes). Lets a shape poke echo this client's
+  * `__client_watermark` as the poke's `lastMutationId`, so a `@lunora/db`
+  * collection can drop the optimistic overlay for writes this poke has
+  * synced. Absent for clients that don't use custom mutators. Persisted so it
+  * survives hibernation.
+  */
+  clientId?: string;
+  /**
   * `true` once the socket's `connect` envelope has fired the `onConnect`
   * hooks. Gates the dispatch so a client that re-sends `connect` (or a
   * duplicate frame) can't re-fire the hooks for an already-announced socket —
@@ -1091,6 +1191,14 @@ interface SocketAttachment {
   * hooks so they run under the connecting user.
   */
   identity?: Record<string, unknown>;
+  /**
+  * Live shape subscriptions registered on this socket, keyed by the
+  * client-supplied subscription id. The partial-replication parallel to
+  * {@link SocketAttachment.subs}: the poke protocol fans membership diffs to
+  * these, while `subs` drives the legacy `data`/`delta` re-execution path.
+  * Absent until the socket sends its first `shape_subscribe`.
+  */
+  shapes?: Record<string, ShapeSubscriptionQuery>;
   subs: Record<string, SubscriptionQuery>;
   /**
   * Verified user id resolved at upgrade (from `x-lunora-userid`), or absent
@@ -1106,6 +1214,36 @@ interface SocketAttachment {
   whispers?: string[];
 }
 /**
+* A `shape_subscribe`'s resolved query: which `table` to replicate, the
+* identity-scoped `effectiveWhere` (the shape predicate AND-merged with the
+* table's RLS read base-where), the optional projected `columns` allow-list,
+* and whether the table is `.global()` (served by the latency-tiered poll path
+* rather than the CDC poke path). The codegen subclass's `resolveShape` builds
+* it under the socket's verified identity, so the membership query the poke
+* protocol runs is RLS-correct by construction.
+*/
+interface ResolvedShape {
+  columns?: ReadonlyArray<string>;
+  effectiveWhere?: WhereInput;
+  /** `true` when the shape's table is `.global()` (lives in D1, not this DO's SQLite) — no per-DO op-log to diff, so served by the poll path. */
+  global?: boolean;
+  table: string;
+}
+/**
+* Identity a subscription/shape query is executed under, threaded EXPLICITLY
+* into the codegen `resolveShape`/`buildCtx` rather than read from the shared,
+* per-request identity fields. The value passed is the socket's OWN verified
+* identity (stamped on the {@link SocketAttachment} at the WS upgrade from the
+* runtime-minted `x-lunora-userid`/`x-lunora-identity` headers the client can't
+* forge), passed BY VALUE so a deferred refresh or interleaved RPC can't clobber
+* it. An anonymous socket leaves both fields `undefined`, so an RLS/`ctx.auth`
+* query fails closed (empty/denied) rather than leaking another user's data.
+*/
+interface SubscriptionIdentity {
+  identity?: Record<string, unknown>;
+  userId?: string;
+}
+/**
 * One-shot backfill of every declared aggregate index. Used by tests and
 * production hosts that want to populate counters up-front instead of on first
 * read. Idempotent: counter rows that already exist are left alone, so it's
@@ -1147,10 +1285,16 @@ interface CdcChange {
 * Read changelog entries newer than `sinceSeq` in commit order, up to `limit`
 * (clamped to [1, 10000]). Returns the rows plus the cursor to resume from (the
 * last `seq`, or `sinceSeq` when the page is empty).
+*
+* The optional `tables` set narrows the page to changes on those tables — the
+* shape/poke path reads one filtered page per flush so it never scans op-log
+* entries for tables no live shape is watching. Omit it (or pass an empty set)
+* for the full, unfiltered page (the existing streaming-export/resume callers).
 */
 declare const readCdcChanges: (sql: SqlExec, options?: {
   limit?: number;
   sinceSeq?: number;
+  tables?: ReadonlySet<string>;
 }) => {
   changes: CdcChange[];
   cursor: number;
@@ -1186,6 +1330,11 @@ declare const applyCdcChanges: (writer: DatabaseWriterLike, changes: ReadonlyArr
 declare const runShardMigrations: (sql: SqlExec, schema: SchemaLike, options?: {
   cdc?: boolean;
 }) => void;
+/** One shape member: its `_id` key plus the decoded document (id + creationTime merged in). */
+interface ShapeRow {
+  doc: Record<string, unknown>;
+  id: string;
+}
 /**
 * Structural projection of `state.storage.sql` (workerd's SqlStorage). We
 * only require the `exec` overload — the cursor it returns is iterable and
@@ -1233,6 +1382,16 @@ interface TableDefinitionLike {
     field?: string;
     kind: "global" | "root" | "shardBy";
   };
+  /**
+  * Mirror of `@lunora/server`'s `TableDefinition.softDeleteMode` (set by
+  * `.softDelete()`). When present, `delete()` flips the `field` column to a
+  * timestamp instead of physically removing the row (cascading as a soft
+  * delete), and list reads scope out rows whose `field` is set unless
+  * `includeDeleted` is passed. By-id reads/writes are unaffected.
+  */
+  readonly softDeleteMode?: {
+    field: string;
+  };
   readonly triggerMap?: Record<string, TriggerDefinitionLike>;
 }
 interface IndexDefinitionLike {
@@ -1525,7 +1684,16 @@ interface DatabaseWriterLike {
   * RLS-aware ctx seam from §3.2).
   */
   count: (tableName: string, where?: RestrictableQueryOptions | WhereInput) => Promise<number>;
-  delete: (id: string, expectedTable?: string) => Promise<void>;
+  /**
+  * Delete a row by id. On a `.softDelete()` table this flips the marker column
+  * (cascading as a soft delete) instead of removing the row; pass
+  * `options.hard` to force a physical removal (which cascades as a physical
+  * delete, reaching already-soft-deleted children too). Non-soft tables ignore
+  * `options.hard` — they always delete physically.
+  */
+  delete: (id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }) => Promise<void>;
   /**
   * Delete many rows by id in one call (a loop over `delete()`). The returned
   * `deleted` is the number of ids **requested**, not rows actually removed (an
@@ -1702,6 +1870,14 @@ interface DatabaseWriterLike {
   rankPageRows?: (tableName: string, indexName: string, options?: RankPageOptions) => Promise<ShardRankPageResult>;
   replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
   /**
+  * Un-soft-delete a row: clears the `.softDelete()` marker column (a by-id
+  * UPDATE, so it works on a row that list reads currently hide). Throws when
+  * the row's table isn't `.softDelete()`. Optional on the interface — the DO
+  * writer implements it; the `.global()` twin does too, so a restore on a
+  * global table routes through the DO writer's global fallback.
+  */
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
+  /**
   * Best-effort, read-only reader over Lunora's system tables
   * (`_scheduled_functions`, `_storage`). Eventually consistent and **not**
   * part of the shard's transaction snapshot — see {@link SystemDatabaseReader}.
@@ -1918,6 +2094,22 @@ declare const readAggregateValue: (op: string, row: {
 * string.
 */
 declare const encodeAggregateKey: (by: ReadonlyArray<string>, source: Record<string, unknown>) => string;
+/** One recorded admin operation, in monotonic `seq` order. */
+interface AuditEntry {
+  /** JSON-decoded extra context (the acting user, op-specific counts, …); absent when none was recorded. */
+  detail?: Record<string, unknown>;
+  /** Primary key of the affected row, when the op targets one. */
+  id?: string;
+  /** Short op identifier, e.g. `writeRow` or `runMigration`. */
+  op: string;
+  /** Monotonic per-shard cursor — strictly increasing, never reused. */
+  seq: number;
+  /** Affected table, when the op targets one. */
+  table?: string;
+  /** Wall-clock millis when the op was recorded. */
+  ts: number;
+}
+/** Fields accepted when appending one audit entry; `seq` is assigned by the table. */
 /** Reserved single-row auth accumulator table. Auto-hidden from the data browser by the `__lunora` prefix. */
 declare const AUTH_METRICS_TABLE = "__lunora_auth_metrics";
 /** Reserved coarse time-series table: app-wide auth attempt/failure counts bucketed by a fixed window. */
@@ -2155,6 +2347,112 @@ interface RenderedSql {
 * identifiers quoted and placeholders numbered the way that engine expects.
 */
 declare const renderSql: (engine: SqlEngine, query: SQL) => RenderedSql;
+/** The result of {@link diffExternalSource}: the changes to replay, and the baseline the next tick diffs from. */
+interface ExternalSourceDiffResult {
+  /** Ordered for `applyCdcChanges`: upserts in pulled order, then deletes in baseline order. */
+  changes: CdcChange[];
+  /** `id → canonical-value JSON` — pass back as the `baseline` next tick (or persist for an incremental cursor). */
+  nextBaseline: Map<string, string>;
+}
+/**
+* Project a row to the document the ingest loop stores + compares on: `_id` plus
+* either the `columns` allow-list or every field except the framework-assigned
+* `_creationTime` (which the source never supplies). Returned as a plain object;
+* key order is irrelevant because {@link stableStringify} sorts keys. Used for BOTH
+* the pulled side here and the local baseline, so the two are byte-identical for an
+* unchanged row.
+*/
+
+/**
+* Diff a sourced table's freshly-pulled membership against the local baseline.
+* Returns the `CdcChange[]` to apply (in stable order: upserts in pulled order,
+* then deletes in baseline order) and the next baseline (`id → canonical JSON`).
+*/
+declare const diffExternalSource: (pulled: ReadonlyArray<Record<string, unknown>>, baseline: ReadonlyMap<string, string>, options: {
+  columns?: ReadonlyArray<string>;
+  table: string;
+}) => ExternalSourceDiffResult;
+/** The outcome of one materialize pass: how many changes were applied, and the baseline the next tick diffs from. */
+interface MaterializeResult {
+  /** Number of `CdcChange`s applied (inserts + updates + deletes). Zero on a steady-state tick. */
+  applied: number;
+  /** `id → projected-value JSON` — the post-tick membership, to feed back as `baseline` next tick. */
+  nextBaseline: Map<string, string>;
+}
+/**
+* Diff `pulled` against `baseline` and apply the delta to `writer`. Returns the
+* applied count and the next baseline. A steady-state tick (membership unchanged)
+* applies nothing and returns `applied: 0`.
+*/
+declare const materializeExternalRows: (writer: DatabaseWriterLike, pulled: ReadonlyArray<Record<string, unknown>>, baseline: ReadonlyMap<string, string>, options: {
+  columns?: ReadonlyArray<string>;
+  table: string;
+}) => Promise<MaterializeResult>;
+/**
+* Read the materialized table's current membership as the canonical full-pull
+* baseline (`id → canonical JSON`). Reuses the shape scanner (`selectShapeRows`)
+* and the SAME {@link projectExternalSourceRow} + {@link stableStringify} the diff
+* uses, so a stored row (with `_creationTime` + arbitrary key order) compares
+* byte-identical to its freshly-pulled source counterpart — an unchanged row
+* produces no spurious update.
+*/
+declare const readExternalSourceBaseline: (sql: SqlExec, table: string, columns?: ReadonlyArray<string>) => Map<string, string>;
+/**
+* Run one full-pull materialize tick: read the table's current membership as the
+* baseline, diff the freshly-pulled rows against it, and apply the delta. This is
+* the system-driven loop body the DO poll alarm calls — the table IS the baseline
+* (design §1 Fact A), so no separate snapshot is kept. Pass both the read handle
+* (`sql`) and the validated `writer` (the DO has both); they must address the same
+* table.
+*/
+declare const runExternalSourceTick: (sql: SqlExec, writer: DatabaseWriterLike, pulled: ReadonlyArray<Record<string, unknown>>, options: {
+  columns?: ReadonlyArray<string>;
+  table: string;
+}) => Promise<MaterializeResult>;
+/** The minimal SqlClient surface the poll loop calls (mirrors `@lunora/hyperdrive`'s `SqlClient`). */
+interface SourceClientLike {
+  query: <Row = Record<string, unknown>>(text: string, parameters?: ReadonlyArray<unknown>) => Promise<Row[]>;
+}
+/** Poll cadence: `"manual"` (never auto-poll) or a minimum interval between polls. */
+type SourceRefresh = "manual" | {
+  everyMs: number;
+};
+/** The runtime `.source(...)` config the poll loop reads — a structural mirror of `@lunora/server`'s `ExternalSourceDefinition` (only the fields the tick uses). */
+interface ExternalSourceLike {
+  binding: string;
+  columns?: ReadonlyArray<string>;
+  idColumn?: string;
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
+  query: string;
+  refresh?: SourceRefresh;
+  tenantBy?: (shardKey: string) => ReadonlyArray<unknown>;
+}
+/**
+* Lift an external row to a Lunora document: the `idColumn` value becomes a
+* stringified `_id`, then either `map` shapes the body or every other column is
+* copied verbatim. Throws on a missing/null id, and on a non-scalar id, so a
+* misconfigured query fails loudly instead of materializing rows under the literal
+* id `"undefined"` (or collapsing many rows onto one id). Shared with
+* `@lunora/hyperdrive`'s `projectSourceRow`.
+*/
+declare const liftSourceId: (row: Record<string, unknown>, options?: {
+  idColumn?: string;
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+* Whether a source should poll on this alarm tick. `"manual"` never auto-polls;
+* `{ everyMs }` polls at most once per interval (the alarm floor still bounds it
+* from below); an omitted `refresh` polls every tick. `lastPolledMs` is `undefined`
+* before the first poll (always due).
+*/
+declare const isSourceDue: (refresh: SourceRefresh | undefined, lastPolledMs: number | undefined, nowMs: number) => boolean;
+/**
+* Pull a sourced table's tenant slice from `client`, project each row through
+* {@link liftSourceId}, and materialize it via {@link runExternalSourceTick}
+* (read local baseline → diff → apply through the validated CDC writer). The
+* per-table body the DO poll alarm runs; `shardKey` binds into `tenantBy`.
+*/
+declare const pullExternalSourceTick: (sql: SqlExec, writer: DatabaseWriterLike, client: SourceClientLike, table: string, source: ExternalSourceLike, shardKey: string) => Promise<MaterializeResult>;
 /**
 * Reserved `functionPath` prefix for admin introspection RPCs. These travel
 * over the same `/_lunora/rpc` → shard `/rpc` path as ordinary functions, but
@@ -2177,6 +2475,19 @@ declare const ADMIN_FUNCTION_PREFIX = "__lunora_admin__:";
 */
 declare const RELATION_FUNCTION_PREFIX = "__lunora_relation__:";
 /**
+* Reserved `functionPath` prefix for live feature-flag reads. The React client's
+* `useFlag`/`useFlags` subscribe to `__lunora_flags__:eval` over the same WS
+* channel as a user query; `ShardDO` intercepts it before user dispatch and
+* serves it from the codegen-overridden flag-subscription read hook, which
+* evaluates the flag through the app's OpenFeature provider under the socket's
+* verified identity. Like the other reserved prefixes it is NOT admin-gated (a
+* flag read is public, scoped to the subscriber's own targeting context), and
+* the `__lunora_` namespace is reserved so a real `&lt;file>:&lt;function>` can't
+* collide. Re-evaluated on every write-flush so values stay live within a
+* session (provider-side flips with no intervening write surface on reconnect).
+*/
+declare const FLAGS_FUNCTION_PREFIX = "__lunora_flags__:";
+/**
 * Fully-qualified reserved paths the data browser invokes. The
 * `__lunora_admin__:` prefix is spelled out inline rather than interpolated so
 * the values stay emittable under `--isolatedDeclarations`.
@@ -2196,6 +2507,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getAuditLog: "__lunora_admin__:getAuditLog";
   readonly getAuthMetrics: "__lunora_admin__:getAuthMetrics";
   readonly getCapturedMail: "__lunora_admin__:getCapturedMail";
+  readonly getFanoutMetrics: "__lunora_admin__:getFanoutMetrics";
   readonly getFunctionStats: "__lunora_admin__:getFunctionStats";
   readonly listSubscriptions: "__lunora_admin__:listSubscriptions";
   readonly listTableIndexes: "__lunora_admin__:listTableIndexes";
@@ -2207,6 +2519,8 @@ declare const ADMIN_FUNCTIONS: {
   readonly getSettings: "__lunora_admin__:getSettings";
   readonly getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus";
   readonly importShard: "__lunora_admin__:importShard";
+  readonly listFlags: "__lunora_admin__:listFlags";
+  readonly listQueues: "__lunora_admin__:listQueues";
   readonly listTables: "__lunora_admin__:listTables";
   readonly listWorkflows: "__lunora_admin__:listWorkflows";
   readonly maskPolicies: "__lunora_admin__:maskPolicies";
@@ -2234,30 +2548,6 @@ interface TableInfo {
   name: string;
   rowCount: number;
 }
-/**
-* One recorded admin operation served by `__lunora_admin__:getAuditLog`, sourced
-* from the reserved `__lunora_audit__` table (see `audit-log.ts`). Unlike the
-* in-memory `getMetrics`/`getFunctionStats` counters, the audit log is durable —
-* it survives hibernation/restart and is bounded only by a retention cap. `seq`
-* is a monotonic per-shard cursor the studio pages through; `op` is the short
-* op name (`writeRow`, `runMigration`, `importShard`, `applyCdc`); `table`/`id`
-* are present when the op targets one; `detail` carries op-specific context
-* (notably the acting `userId`).
-*/
-interface AuditEntry {
-  /** JSON extra context (acting user, op-specific counts, …); absent when none was recorded. */
-  detail?: Record<string, unknown>;
-  /** Primary key of the affected row, when the op targets one. */
-  id?: string;
-  /** Short op identifier, e.g. `writeRow`. */
-  op: string;
-  /** Monotonic per-shard cursor — strictly increasing, never reused. */
-  seq: number;
-  /** Affected table, when the op targets one. */
-  table?: string;
-  /** Epoch-ms the op was recorded. */
-  ts: number;
-}
 /** Payload of a `__lunora_admin__:getAuditLog` call: the recorded entries, newest first. */
 interface AuditLogResult {
   entries: AuditEntry[];
@@ -2510,20 +2800,64 @@ interface StorageRulesResult {
 * package's tests and the studio's fails the build if the two key sets diverge.
 */
 interface StudioFeaturesResult {
+  /** `@lunora/bindings/analytics` / `ctx.analytics` is used, or it is a declared dependency. */
+  analytics: boolean;
+  /** `@lunora/auth` is a declared dependency (backs the Users / Sessions / Organizations / Configuration pages). */
+  auth: boolean;
+  /** `@lunora/flags` / `ctx.flags` is used, or it is a declared dependency. */
+  flags: boolean;
+  /** `@lunora/bindings/kv` / `ctx.kv` is used, or it is a declared dependency. */
+  kv: boolean;
   /** `@lunora/mail` is imported by a `lunora/` source or a declared dependency. */
   mail: boolean;
   /** `@lunora/payment` is used (import or `ctx.payments`) or a declared dependency. */
   payments: boolean;
+  /** `@lunora/queue` / `ctx.queues` is used, the app declares queues, or it is a declared dependency. */
+  queues: boolean;
   /** `@lunora/scheduler` / `ctx.scheduler` is used, the app declares crons, or it is a declared dependency. */
   scheduler: boolean;
   /** `@lunora/storage` / `ctx.storage` is used, the schema declares storage columns/rules, or it is a declared dependency. */
   storage: boolean;
-  /** The schema declares vector indexes, `@lunora/vectors` / `ctx.vectors` is used, or it is a declared dependency. */
+  /** The schema declares vector indexes, `@lunora/bindings/vectors` / `ctx.vectors` is used, or it is a declared dependency. */
   vectors: boolean;
   /** `@lunora/workflow` / `ctx.workflows` is used, the app declares workflows, or it is a declared dependency. */
   workflows: boolean;
 }
 /**
+* One feature flag evaluated under a supplied targeting context, surfaced by
+* `__lunora_admin__:listFlags` for the studio's read-only Flags page. The `key`
+* and `type` are statically discovered by `@lunora/codegen` from the app's
+* `ctx.flags.&lt;type>("key", …)` reads; `value`/`reason`/`variant`/`errorCode`
+* come from the live OpenFeature evaluation (the codegen subclass overrides the
+* base `evaluateFlags` hook). `value` is the resolved flag value as JSON.
+*/
+interface FlagEvaluation {
+  /** OpenFeature `errorCode` when the evaluation failed (the value falls back to the default). */
+  errorCode?: string;
+  /** The discovered flag key (the first argument of a `ctx.flags.&lt;type>(...)` read). */
+  key: string;
+  /** OpenFeature `reason` for the resolution (`TARGETING_MATCH`, `DEFAULT`, `ERROR`, …). */
+  reason?: string;
+  /** The flag's value type, derived from which `ctx.flags.&lt;type>` method read it. */
+  type: "boolean" | "number" | "object" | "string";
+  /** The resolved value (JSON), or the type default when unconfigured / on error. */
+  value: unknown;
+  /** OpenFeature `variant` identifier when the provider reports one. */
+  variant?: string;
+}
+/**
+* Payload of a `__lunora_admin__:listFlags` call: every statically-discovered
+* flag evaluated under the supplied targeting context. `configured` is `false`
+* when the app wires no `@lunora/flags` provider (the base hook), so the studio
+* can distinguish "no flags configured" from "configured but zero flags read".
+*/
+interface FlagsResult {
+  /** `true` when an `@lunora/flags` provider is wired (the codegen override ran). */
+  configured: boolean;
+  /** Each discovered flag evaluated under the request's targeting context. */
+  flags: FlagEvaluation[];
+}
+/**
 * One declared Cloudflare Workflow, surfaced by `__lunora_admin__:listWorkflows`
 * for the studio's Workflows page. Statically discovered by `@lunora/codegen`
 * from `lunora/workflows.ts` (the codegen subclass overrides the base hook);
@@ -2544,6 +2878,28 @@ interface WorkflowsResult {
   workflows: WorkflowMetadata[];
 }
 /**
+* One declared Cloudflare Queue, surfaced by `__lunora_admin__:listQueues` for
+* the studio's Queues page. Statically discovered by `@lunora/codegen` from
+* `lunora/queues.ts` (the codegen subclass overrides the base hook); queues are
+* not Durable Objects and carry no runtime state in the shard, so this is pure
+* declaration metadata. `binding` is the generated `QUEUE_*` producer binding,
+* `name` the deployed `queues.producers[].queue`, `exportName` the
+* `lunora/queues.ts` export (`ctx.queues.&lt;exportName>`), `mode` whether the
+* queue is consumed by a worker (`push`) or polled externally (`pull`), and
+* `deadLetterQueue` the optional DLQ a push consumer dead-letters to.
+*/
+interface QueueMetadata {
+  binding: string;
+  deadLetterQueue?: string;
+  exportName: string;
+  mode: "pull" | "push";
+  name: string;
+}
+/** Payload of a `__lunora_admin__:listQueues` call: every declared queue, sorted by export name. */
+interface QueuesResult {
+  queues: QueueMetadata[];
+}
+/**
 * Lifecycle state of a workflow instance, mirrored from `@lunora/workflow`'s
 * `WorkflowInstanceStatus` so `@lunora/do` carries no dependency on the workflow
 * package. Returned by `getWorkflowInstanceStatus` and `createWorkflowInstance`.
@@ -2617,7 +2973,12 @@ interface TablePage {
   */
   refs?: Record<string, string>;
   rows: Record<string, unknown>[];
-  total: number;
+  /**
+  * Total rows matching the predicate. Absent when the read passed
+  * `skipCount: true` (the caller sources the count from a separate,
+  * predicate-keyed read instead of recomputing it per page).
+  */
+  total?: number;
 }
 /** Comparison a {@link FilterClause} applies. `contains` is a case-sensitive substring (LIKE); the rest are direct SQL comparisons. */
 type FilterOperator = "contains" | "eq" | "gt" | "gte" | "lt" | "lte" | "ne";
@@ -2633,8 +2994,6 @@ interface FilterClause {
   operator: FilterOperator;
   value?: unknown;
 }
-/** Sort direction for an {@link OrderByClause}. */
-type SortDirection = "asc" | "desc";
 /**
 * A server-side sort over one displayed column. `column` resolves the same way a
 * {@link FilterClause}'s does — a physical/meta column orders by its identifier, a
@@ -2675,6 +3034,14 @@ interface ReadTablePageOptions {
   * Empty/whitespace is treated as no filter.
   */
   search?: string;
+  /**
+  * Skip the `SELECT COUNT(*)` and return the page with `total` absent. The
+  * data browser splits the row count into a separate predicate-keyed read (one
+  * that excludes `offset`), so paging never re-counts; the page read passes
+  * this to avoid recomputing the same total per offset. Unset → the COUNT runs
+  * (today's behavior) and `total` is populated.
+  */
+  skipCount?: boolean;
   table: string;
 }
 /**
@@ -3284,6 +3651,16 @@ declare const assertFlatPredicate: (where: WhereInput | undefined, schema: Resol
 * and issues no extra query).
 */
 declare const resolveRelationPredicates: (where: WhereInput | undefined, options: ResolveRelationPredicatesOptions) => Promise<WhereInput | undefined>;
+/**
+* Registration-time guard for partial-replication shapes. A live shape can only
+* be poked from the op-log of its OWN shard Durable Object, so an
+* `effectiveWhere` that joins to a `.shardBy()` table reaches rows that live in
+* other DOs the poke loop can never observe. Reject such a shape up front with
+* the two supported remedies. Called from the generated `resolveShape` override
+* the moment a socket subscribes (the first point the compiled predicate and the
+* schema's shard modes are both in hand).
+*/
+declare const assertShapeShardable: (effectiveWhere: WhereInput | undefined, schema: ResolveContext["schema"], table: string) => void;
 /** Severity of a `ctx.log.*` call, mirroring the console method names (`log` is the default level, distinct from `info`). */
 type ContextLogLevel = "debug" | "error" | "info" | "log" | "warn";
 /** The fields {@link emitLogEvent} ships for one `ctx.log.*` call. */
@@ -3582,6 +3959,44 @@ declare class SessionDO {
   private handleRevoke;
 }
 /**
+* Diff the previously-sent list snapshot (`previousJson`, the memo's
+* `lastJson`) against the new query result and produce per-row
+* {@link MutationDelta}s the client can merge in place via `applyDelta` —
+* Convex-parity live-pagination deltas (server half of gap #20).
+*
+* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
+* unless ALL of these hold:
+*
+* 1. `previousJson` parses to an array (there IS a previous list to diff against).
+* 2. `nextResult` is also an array.
+* 3. Every row in both arrays is a plain object carrying a string `_id`.
+* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
+* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
+*
+* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
+* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
+* full new `row`; delete omits it (matching the wire contract `@lunora/client`
+* parses). Deltas are ordered deletes-then-inserts/updates so the client never
+* sees a transient over-length page.
+*
+* Per-row serialization is done exactly **once** per refresh (finding #6). Each
+* row is stringified a single time into a fingerprint reused for both the
+* `prev !== next` change-detection compare and — when the caller passes the
+* optional `frames` sink — the pre-serialized delta frame body. The returned
+* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
+* exact `JSON.stringify(delta)` string for each returned delta, in the same
+* order, so the caller can splice it straight into the `{type:"delta"}` frame
+* without serializing the delta (and the row inside it) a second time.
+* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
+*/
+declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
+/**
+* Send one WebSocket frame, reporting whether it left the socket. A throw from
+* `ws.send` (socket closed mid-flush, outbound buffer gone) is the only
+* delivery-failure signal the runtime exposes; callers use the boolean to decide
+* whether to advance a subscription's delivered-diff baseline.
+*/
+/**
 * Optional programmatic log sink, resolved from `createShardDO({ observability })`.
 * Structurally a subset of `@lunora/runtime`'s `ObservabilitySink`, so a user can
 * pass the SAME sink object to `createWorker` (which drives `onRpc`) and
@@ -3634,6 +4049,13 @@ interface ShardDOState {
     getCurrentBookmark?: () => Promise<string>;
     /** Native PITR: arm a restore to `bookmark` on next restart; returns the undo bookmark. */
     onNextSessionRestoreBookmark?: (bookmark: string) => Promise<string>;
+    /**
+    * Arm the DO's single alarm to fire at `scheduledTime` (ms epoch),
+    * waking {@link ShardDO.alarm}. Used by the global-shape poll loop.
+    * Optional: present on the real runtime, absent in the unit harness
+    * (where the poll loop degrades to seed-only).
+    */
+    setAlarm?: (scheduledTime: Date | number) => Promise<void>;
     sql: {
       [key: string]: unknown;
       /**
@@ -3678,34 +4100,15 @@ interface SubscriptionOutcome {
   tables: Set<string>;
 }
 /**
-* Identity a subscription query is executed under, threaded EXPLICITLY into
-* `executeSubscription` → `buildCtx` rather than read from the shared,
-* per-request `currentRequestUserId`/`currentRequestIdentity` instance fields.
-*
-* The value passed is the socket's OWN verified identity, captured at the WS
-* upgrade from the runtime-forwarded, server-minted `x-lunora-userid` /
-* `x-lunora-identity` headers (the client cannot forge them — the runtime
-* strips any client-supplied copies) and stamped on the {@link SocketAttachment}.
-* `seedSubscription` and `refreshSubscriptions` read it off the attachment and
-* pass it here BY VALUE — never by reading the mutable per-request
-* `currentRequestUserId`/`currentRequestIdentity` instance fields, which a
-* deferred (`waitUntil`) refresh or a concurrently-interleaved RPC could be
-* mutating. That value-passing is what keeps a subscription re-run from
-* observing or clobbering an in-flight RPC's identity.
-*
-* Developer-facing consequence: a query that authorizes or filters on the
-* caller's identity — via `.use(rls(...))` or by reading `ctx.auth.userId` —
-* evaluates over the live channel under the CONNECTING user, so its seed and
-* every write-driven refresh return that user's rows, matching the one-shot
-* `fetch` RPC. An anonymous socket (no identity resolved at upgrade) leaves
-* both fields `undefined`, so such a query fails closed (empty/denied) rather
-* than leaking another user's data. See the lunora-realtime skill
-* ("Authorization & live queries").
+* Classification of a watermarked custom-mutator push against the shard's
+* `__client_watermark`: `expected` is the next in-order sequence, `kind`
+* whether the push is a replay (`"already"`), the next one (`"next"`), or an
+* out-of-order arrival (`"gap"`).
 */
-interface SubscriptionIdentity {
-  identity?: Record<string, unknown>;
-  userId?: string;
-}
+type ClientMutationClass = {
+  expected: number;
+  kind: "already" | "gap" | "next";
+};
 /**
 * Optional shard-level configuration passed through `super(state, env, …)`.
 * Reserved as a bag rather than positional args so subclasses don't break
@@ -3834,38 +4237,6 @@ interface RunShardRankPageArgs {
   take?: number;
 }
 /**
-* Diff the previously-sent list snapshot (`previousJson`, the memo's
-* `lastJson`) against the new query result and produce per-row
-* {@link MutationDelta}s the client can merge in place via `applyDelta` —
-* Convex-parity live-pagination deltas (server half of gap #20).
-*
-* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
-* unless ALL of these hold:
-*
-* 1. `previousJson` parses to an array (there IS a previous list to diff against).
-* 2. `nextResult` is also an array.
-* 3. Every row in both arrays is a plain object carrying a string `_id`.
-* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
-* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
-*
-* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
-* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
-* full new `row`; delete omits it (matching the wire contract `@lunora/client`
-* parses). Deltas are ordered deletes-then-inserts/updates so the client never
-* sees a transient over-length page.
-*
-* Per-row serialization is done exactly **once** per refresh (finding #6). Each
-* row is stringified a single time into a fingerprint reused for both the
-* `prev !== next` change-detection compare and — when the caller passes the
-* optional `frames` sink — the pre-serialized delta frame body. The returned
-* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
-* exact `JSON.stringify(delta)` string for each returned delta, in the same
-* order, so the caller can splice it straight into the `{type:"delta"}` frame
-* without serializing the delta (and the row inside it) a second time.
-* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
-*/
-declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
-/**
 * Threshold at which a `__root__` DO triggers the size warning. 1 GiB —
 * exactly 10% of the 10 GiB per-DO SQLite ceiling, leaving plenty of runway
 * to plan a `.shardBy()` migration before the wall hits.
@@ -3918,6 +4289,28 @@ declare abstract class ShardDO {
   */
   protected static readonly MAX_SUBSCRIPTIONS_PER_SOCKET = 32;
   /**
+  * Poll interval (ms) for `.global()`-table shapes. A global table lives in
+  * D1 with no per-DO op-log, so its shapes can't be poke-live; the DO re-reads
+  * each subscribed global shape's membership from D1 on an alarm every
+  * `GLOBAL_SHAPE_POLL_INTERVAL_MS` and pokes only the diff. This is the
+  * latency floor for a global-shape update — deliberately coarse (seconds, not
+  * the sub-millisecond poke-live path) since the D1 read fans out per tick.
+  */
+  protected static readonly GLOBAL_SHAPE_POLL_INTERVAL_MS = 2e3;
+  /**
+  * Upper bound on a `.global()`-shape's materialized membership. Each global
+  * shape keeps its ENTIRE current membership as a per-socket snapshot
+  * (`Map&lt;rowKey, hash&gt;`) so the poll loop can diff it; that snapshot — and the
+  * read buffer feeding it — scale with the membership size, multiplied by every
+  * subscribed socket. An unbounded membership (a global table with no narrowing
+  * shape predicate or RLS read scope) would grow them without limit and evict
+  * the DO. A shape whose membership exceeds this cap is failed closed (left
+  * empty, logged) rather than retained — the developer must narrow it. Sized
+  * well above any reasonable per-identity replicated set so legitimate shapes
+  * never trip it.
+  */
+  protected static readonly GLOBAL_SHAPE_MAX_ROWS = 5e4;
+  /**
   * Per-socket whisper-topic cap. Topic membership rides the same hibernation
   * attachment as `subs`, so bound it for the same reason — a runaway
   * `whisper_subscribe` loop must not wedge the attachment past the runtime's
@@ -4017,6 +4410,39 @@ declare abstract class ShardDO {
   */
   private currentRequestMutationId;
   /**
+  * Stable per-device client id for the in-flight custom-mutator push,
+  * forwarded via the `x-lunora-client-id` header. Backs the
+  * `__client_watermark` table: the dispatch path classifies the paired
+  * `currentRequestClientSeq` against the stored high-watermark (already
+  * processed / next / out-of-order gap). Absent on legacy mutations and
+  * queries (those keep the `__idempotency` path). Cleared in `fetch`'s
+  * `finally`.
+  */
+  private currentRequestClientId;
+  /**
+  * Monotonic per-client mutation sequence for the in-flight custom-mutator
+  * push, forwarded via the `x-lunora-client-seq` header (numeric). Paired
+  * with `currentRequestClientId` to drive the watermark classification.
+  * `undefined` when absent or non-numeric.
+  */
+  private currentRequestClientSeq;
+  /**
+  * The in-flight push's custom-mutator classification, stashed by `fetch`
+  * before `handleRpc` so the in-transaction bookkeeping ({@link
+  * ShardDO.commitMutationBookkeeping}) can advance the `__client_watermark` for
+  * a `"next"` push inside the same commit as the writes. `undefined` for an
+  * ordinary mutation / non-mutator push. Cleared per request.
+  */
+  private currentMutatorClass;
+  /**
+  * Set once a mutation's replay bookkeeping (idempotency row + watermark
+  * advance) has committed INSIDE the handler transaction, so the post-dispatch
+  * path skips the now-redundant best-effort writes. Cleared per request; stays
+  * `false` for actions/queries (no transaction wrapper) so their dispatch-level
+  * idempotency persist still runs.
+  */
+  private mutationBookkeepingCommitted;
+  /**
   * Wall-clock millis of the last `__idempotency` GC sweep on this warm
   * instance. The dedup write throttles `trimIdempotent` to at most once an
   * hour off this field (in-memory, so a fresh instance just sweeps on its
@@ -4047,6 +4473,18 @@ declare abstract class ShardDO {
   */
   private pendingChangedTables;
   /**
+  * Coalesced set of tables awaiting a subscription-refresh pass, merged
+  * across every {@link ShardDO.flushChangedTables} call that lands while a
+  * pass is already draining. The single drain loop
+  * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
+  * writes to the same table therefore collapses into one (or two) refresh
+  * passes instead of N, so each affected subscription's handler re-runs once
+  * per burst rather than once per write. `undefined` when nothing is pending.
+  */
+  private pendingRefreshTables;
+  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
+  private refreshInFlight;
+  /**
   * Last pushed result per `(socket, subId)`, keyed by socket. Lets
   * `refreshSubscriptions` skip re-running queries whose tables were
   * untouched and suppress pushes when the re-run result is unchanged. Held
@@ -4054,6 +4492,39 @@ declare abstract class ShardDO {
   * memo simply forces one re-run and (at most) one redundant push.
   */
   private readonly subMemos;
+  /**
+  * Per-socket poke baseline for shape subscriptions: maps each shape's
+  * subscription id to the `__cdc_log` cursor it has been poked through.
+  * `pokeShapeSubscribers` reads each op page since this cursor and advances
+  * it to the flush watermark. In-memory only (like {@link ShardDO.subMemos});
+  * a cold memo on a reconnected/hibernated socket re-seeds from the client's
+  * `sinceCheckpoint`.
+  */
+  private readonly shapeMemos;
+  /**
+  * Per-socket, per-**global**-shape membership snapshot: maps each global
+  * shape's subscription id to a `key → projected-value JSON` map of the rows
+  * last poked to that socket. A `.global()` (D1) table has no op-log to diff,
+  * so {@link ShardDO.refreshGlobalShape} re-reads the full membership on each
+  * alarm tick and diffs it against this snapshot to compute the poke. Parallel
+  * to {@link ShardDO.shapeMemos} (the cursor baseline for poke-live shapes).
+  *
+  * This is a hot in-memory **cache** over the durable `__global_shape_snapshot`
+  * table (keyed by the socket's `connectionId` + subId): a hibernation eviction
+  * clears the WeakMap, so on the next alarm wake {@link ShardDO.readGlobalSnapshot}
+  * misses and re-loads the baseline from SQLite — without it, the diff would run
+  * against an empty baseline and a row deleted from D1 while the DO slept would
+  * never be poked as a `delete`, lingering on the client as a phantom row.
+  */
+  private readonly globalShapeSnapshots;
+  /**
+  * Whether a global-shape poll alarm is currently armed. Guards
+  * {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed; reset in
+  * {@link ShardDO.alarm} before the poll so a still-subscribed shape re-arms.
+  */
+  private globalPollScheduled;
+  /** Monotonic per-DO poke id source; correlates a poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
+  private pokeSequence;
   /** Per-socket whisper-rate token bucket (see {@link ShardDO.WHISPER_RATE_BURST}). In-memory; resets on hibernation. */
   private readonly whisperBuckets;
   /**
@@ -4072,6 +4543,35 @@ declare abstract class ShardDO {
   */
   private readonly metrics;
   /**
+  * Running fan-out cost counters surfaced by the
+  * `__lunora_admin__:getFanoutMetrics` RPC — one tally for the reactive
+  * shape-poke path (`pokeShapeSubscribers`) and one for the whisper broadcast
+  * path (`broadcastWhisper`). Each pass records the sockets it iterated (the
+  * O(subscribers) cost) and delivered to. In-memory and reset on
+  * hibernation/restart, sharing `metrics.sinceMs` as the "since this instance
+  * woke" epoch. This is the observability half of plan 075's auto-elastic
+  * relay tier (Phase 1): measure the per-flush fan-out cost so the promotion
+  * threshold is grounded in real numbers, with no behavior change.
+  */
+  private readonly fanout;
+  /**
+  * The runtime's Durable Object namespace binding name (e.g. `"SHARD"`),
+  * forwarded as `x-lunora-shard-binding` on every request so a DO can address
+  * its siblings (`this.env[binding].getByName(...)`) for the relay hub. Absent
+  * in single-DO mode / the unit harness — when absent, the relay tier is inert
+  * and whispers stay shard-local (no behavior change). In-memory; re-learned per
+  * request.
+  */
+  private shardBinding;
+  /**
+  * The auto-elastic fan-out relay collaborator (plan 075) — an {@link OwnerRelay}
+  * or {@link RelayMember} chosen ONCE from this DO's name, or `undefined` for an
+  * unnamed (single-DO) DO where the relay tier is inert. All relay state +
+  * transport lives on it, reached back through the {@link RelayHost} adapter, so
+  * owner-only state can never sit next to relay-only state on this class.
+  */
+  private readonly relay;
+  /**
   * Declared indexes (`table:index`) a query has exercised since this instance
   * woke, stamped by `getCtxDbIndexUseHook`. In-memory and reset on
   * hibernation/restart — drives the `unused_index` runtime advisory.
@@ -4172,6 +4672,15 @@ declare abstract class ShardDO {
   webSocketClose(ws: WebSocket, _code: number, _reason: string, _wasClean: boolean): Promise<void>;
   /** Hibernation API: invoked on socket error. */
   webSocketError(_ws: WebSocket, _error: unknown): void;
+  /**
+  * Durable Object alarm handler — the heartbeat for `.global()`-table shapes.
+  * The runtime wakes this when the poll alarm armed by `scheduleGlobalPoll`
+  * fires; it refreshes every subscribed global shape (diff-poke from the global
+  * backend) and re-arms while any remain. With no global subscribers left, the
+  * alarm is not re-armed and the DO goes idle. A base-only / global-free DO
+  * never arms it, so this stays dormant there.
+  */
+  alarm(): Promise<void>;
   /** Subclasses implement function dispatch. */
   abstract handleRpc(functionPath: string, args: Record<string, unknown>): Promise<unknown>;
   /**
@@ -4418,6 +4927,35 @@ declare abstract class ShardDO {
   */
   protected studioFeatures(): StudioFeaturesResult;
   /**
+  * Evaluate every statically-discovered feature flag under `context` for the
+  * studio's read-only Flags page (`__lunora_admin__:listFlags`). The flag keys
+  * + value types are discovered by `@lunora/codegen` from the app's
+  * `ctx.flags.&lt;type>("key", …)` reads and evaluated through the configured
+  * `@lunora/flags` provider — work only the codegen subclass can do, so it
+  * overrides this. The base class wires no provider and reports
+  * `configured: false` with zero flags (an un-generated `ShardDO` has none).
+  */
+  protected evaluateFlags(_context?: Record<string, unknown>): Promise<FlagsResult>;
+  /**
+  * Serve one reserved {@link FLAGS_FUNCTION_PREFIX} live flag read for the
+  * React client's `useFlag`/`useFlags`. `functionPath` carries the flag key +
+  * type and `args` the per-subscriber targeting context; the codegen subclass
+  * overrides this to evaluate the flag through the app's `@lunora/flags`
+  * provider under `identity` and return the resolved value. The base class
+  * wires no provider, so it returns `null` — `resolveReactiveOutcome` reads
+  * `null` as "nothing to deliver" and the subscriber keeps its default.
+  */
+  protected runFlagSubscriptionRead(_functionPath: string, _arguments: Record<string, unknown>, _identity?: SubscriptionIdentity): Promise<unknown>;
+  /**
+  * The Cloudflare Queues declared by this app, surfaced via
+  * `__lunora_admin__:listQueues` for the studio's Queues page. Queues are NOT
+  * Durable Objects and hold no shard state, so this is pure declaration
+  * metadata statically discovered by `@lunora/codegen` from `lunora/queues.ts`
+  * and emitted into the generated subclass, which overrides this. The base
+  * class can't see the user's project, so it reports none.
+  */
+  protected queuesMetadata(): QueuesResult;
+  /**
   * The Cloudflare Workflows declared by this app, surfaced via
   * `__lunora_admin__:listWorkflows` for the studio's Workflows page. Workflows
   * are NOT Durable Objects and hold no shard state, so this is pure
@@ -4580,16 +5118,117 @@ declare abstract class ShardDO {
   * unless the request carried an `x-lunora-mutation-id` header (queries and
   * legacy clients leave `currentRequestMutationId` undefined).
   *
-  * Called on the live dispatch path right after the handler's writes have
-  * auto-committed, through the same `this.sql` handle, so the dedup row is
-  * durable iff those writes are. (The DO has no ambient BEGIN/COMMIT around a
-  * mutation — `handleRpc` invokes the user handler directly — so this can't
-  * piggyback on a surrounding transaction; it commits as its own statement
-  * immediately after.) `INSERT OR IGNORE` keeps a concurrent double-dispatch
-  * of the same id idempotent. Also runs the throttled dedup-table GC.
+  * For a mutation this runs INSIDE the handler's transaction (via
+  * {@link ShardDO.commitMutationBookkeeping}, which `handleRpc` invokes before
+  * the transaction commits), so the dedup row is durable iff the writes are —
+  * closing the crash window where the writes commit but the replay guard does
+  * not. Actions/queries aren't transaction-wrapped, so they call this on the
+  * live dispatch path right after the handler resolves, through the same
+  * `this.sql` handle. `INSERT OR IGNORE` keeps a concurrent double-dispatch (or
+  * the now-skipped post-dispatch call) of the same id idempotent. Also runs the
+  * throttled dedup-table GC.
   */
   protected persistIdempotentResult(result: unknown): void;
   /**
+  * Whether `functionPath` names a registered custom mutator (a `defineMutator`
+  * declaration) rather than an ordinary `mutation`. The base class knows of no
+  * mutators, so the default is `false`; the codegen-generated subclass
+  * overrides this to consult its mutator registry. When `true` (and the push
+  * carries a `clientId`/`clientSeq`), the dispatch path applies the
+  * `__client_watermark` ordering semantics instead of the legacy idempotency
+  * dedup.
+  */
+  protected isCustomMutator(_functionPath: string): boolean;
+  /**
+  * Classify an in-flight custom-mutator push against the shard's stored
+  * high-watermark for `currentRequestClientId`. The watermark is the highest
+  * per-client sequence the DO has applied, so the push is exactly one of:
+  *
+  * - `"already"` — `seq &lt;= watermark`: a replay of a confirmed (or in-flight,
+  * now-resent) mutation. The handler must NOT re-run; the dispatch path returns
+  * a benign ack so the client drops the pending overlay.
+  * - `"next"` — `seq == watermark + 1`: the next mutation in order. Run the
+  * authoritative `server` impl and advance the watermark in the same commit.
+  * - `"gap"` — `seq > watermark + 1`: an out-of-order arrival (an earlier push
+  * was lost). Halt: the client must resend from `watermark + 1`.
+  *
+  * Returns `undefined` when the push is not a watermarked custom mutator
+  * (missing client id/seq, or a stub `sql` handle without the table) so the
+  * caller falls through to the legacy idempotency path.
+  */
+  protected classifyClientMutation(): ClientMutationClass | undefined;
+  /**
+  * Terminal response for a watermarked custom-mutator push that is NOT the
+  * next-in-order mutation — an idempotent replay ack (`"already"`) or an
+  * out-of-order halt (`"gap"`). Returns `undefined` for an ordinary mutation
+  * or a `"next"` push so `fetch` proceeds to the authoritative handler. Records
+  * the function call on the short-circuit paths so metrics stay attributed.
+  */
+  protected rejectNonNextMutation(functionPath: string, mutatorClass: ClientMutationClass | undefined, dispatchStartedAt: number): Response | undefined;
+  /**
+  * Respond to a dispatch that hit the `(identity, mutationId)` idempotency
+  * cache. Records the (zero-work) function call, then: for a `"next"` custom
+  * mutator whose handler already committed but whose watermark advance was
+  * lost to a crash in between, re-advance and echo `lastMutationId` exactly as
+  * the post-commit path does (otherwise the cached branch returns a bare
+  * result with a stale watermark and the client reports every later seq as a
+  * gap forever); for everything else, return the bare cached `{ result }`.
+  */
+  protected respondFromIdempotencyCache(functionPath: string, dispatchStartedAt: number, mutatorClass: ClientMutationClass | undefined, cachedValue: unknown): Response;
+  /**
+  * The CDC cursor a just-committed plain mutation landed at — the post-write
+  * high-watermark, on the same scale as the `cursor` on `data`/`delta` frames.
+  * The client drops a pending per-call optimistic overlay once it sees a frame
+  * with `cursor >= commitCursor` (gapless reconciliation that keeps mutations
+  * concurrent, without the serialized custom-mutator watermark). Scoped to a
+  * mutation (carries an `x-lunora-mutation-id`) on a CDC-enabled shard;
+  * `undefined` otherwise, leaving the wire byte-identical for queries/actions
+  * and CDC-off shards.
+  */
+  protected mutationCommitCursor(): number | undefined;
+  /**
+  * Build the success response for a dispatched RPC. A `"next"` custom-mutator
+  * push echoes the applied `lastMutationId` so the client drops the pending
+  * optimistic overlay as soon as the ack lands; a plain mutation echoes
+  * `commitCursor` (see {@link mutationCommitCursor}); other calls return the
+  * bare `{ result }` envelope unchanged.
+  */
+  protected buildDispatchResponse(mutatorClass: ClientMutationClass | undefined, result: unknown): Response;
+  /**
+  * Commit a mutation's replay bookkeeping — the `(identity, mutationId)`
+  * idempotency dedup row and, for a `"next"` custom-mutator push, the
+  * `__client_watermark` advance — INSIDE the handler's transaction. Called by
+  * the generated `handleRpc` mutation branch after the user handler resolves
+  * but before the transaction commits, so the writes, the dedup row, and the
+  * watermark land in one atomic commit: a crash can't leave the writes durable
+  * without the replay guard (which a re-dispatch would otherwise re-run) nor
+  * without the watermark. Sets {@link ShardDO.mutationBookkeepingCommitted} so
+  * `fetch` skips the redundant post-dispatch persist.
+  */
+  protected commitMutationBookkeeping(result: unknown): void;
+  /**
+  * Best-effort replay bookkeeping for the live dispatch path, run after
+  * `handleRpc` returns. A generated mutation already committed it atomically
+  * inside its transaction (via {@link ShardDO.commitMutationBookkeeping}, which
+  * sets the flag), so this skips. Actions/queries aren't transaction-wrapped,
+  * so they record their dedup row here (a no-op without an `x-lunora-mutation-id`),
+  * and a `"next"` push advances its watermark (the gap self-heals on replay).
+  */
+  protected recordPostDispatchBookkeeping(result: unknown, mutatorClass: ClientMutationClass | undefined): void;
+  /**
+  * Advance the stored high-watermark for the in-flight custom mutator to
+  * `currentRequestClientSeq` through the same `this.sql` handle. On the
+  * transactional path ({@link ShardDO.commitMutationBookkeeping}, `strict`) it
+  * runs inside the handler's commit, so the watermark is durable iff the writes
+  * are; a failure rethrows to roll the mutation back. On the best-effort
+  * cache-hit recovery path (`strict` omitted) a missing table is swallowed —
+  * the replay re-runs and re-advances (the read side treats a missing row as
+  * watermark 0), so the gap self-heals.
+  */
+  protected advanceClientMutationWatermark(options?: {
+    strict?: boolean;
+  }): void;
+  /**
   * Replay a batch of CDC changes into this shard (point-in-time recovery).
   * Schema-aware — it builds a `createShardCtxDb` writer — so the base class
   * can't implement it; the codegen-generated subclass overrides this to call
@@ -4608,6 +5247,17 @@ declare abstract class ShardDO {
   protected subscribe(ws: WebSocket, subId: string, query: SubscriptionQuery): "ok" | "serialize_failed" | "too_many";
   protected unsubscribe(ws: WebSocket, subId: string): void;
   /**
+  * Register a live shape subscription on a socket — the partial-replication
+  * parallel to {@link ShardDO.subscribe}. Stores the descriptor in the
+  * attachment's `shapes` registry (created lazily) so it survives
+  * hibernation, sharing the per-socket cap with `subs`. Returns a status the
+  * caller surfaces as a structured error frame; never throws (a thrown
+  * `webSocketMessage` is a fatal-channel error under the hibernation API).
+  */
+  protected shapeSubscribe(ws: WebSocket, subId: string, shape: ShapeSubscriptionQuery): "ok" | "serialize_failed" | "too_many";
+  /** Remove a shape subscription and its poke baseline. Mirrors {@link ShardDO.unsubscribe}'s rollback-on-serialize-failure contract. */
+  protected shapeUnsubscribe(ws: WebSocket, subId: string): void;
+  /**
   * Decide whether a single subscription is interested in a mutation
   * delta. The default implementation checks the table name, then runs a
   * shallow-equality predicate over `query.args` against `delta.row`. A
@@ -4645,6 +5295,74 @@ declare abstract class ShardDO {
   */
   protected executeSubscription(_functionPath: string, _args: Record<string, unknown>, _identity?: SubscriptionIdentity): Promise<SubscriptionOutcome | null>;
   /**
+  * Resolve a named shape to its concrete query plan for `identity`. The base
+  * class has no shape registry, so it returns `undefined` — partial
+  * replication is disabled and a `shape_subscribe` is rejected. The
+  * codegen-generated subclass overrides this to look the shape up in the
+  * project's `defineShape` registry, evaluate its `where(ctx, args)` under the
+  * subscriber's verified identity, and AND-compose it with the table's RLS
+  * read base-where into {@link ResolvedShape.effectiveWhere}.
+  *
+  * `identity` is the socket's OWN verified identity (the same unforgeable
+  * value `refreshSubscriptions` threads), passed by value so this never reads
+  * the mutable per-request identity fields. Returning `undefined` is the
+  * fail-closed signal — an unknown shape, or an RLS-required table with no
+  * policy resolving for this identity, yields no subscription rather than
+  * leaking rows.
+  */
+  protected resolveShape(_name: string, _args: Record<string, unknown>, _identity?: SubscriptionIdentity): ResolvedShape | undefined;
+  /**
+  * The RLS-uniform gate (plan 075 Phase 3): whether a reactive shape may be
+  * relay-multicast — i.e. one delta is correct for **every** subscriber. The owner
+  * decides it (see {@link OwnerRelay.isShapeRelayUniform} — a static RLS read-policy
+  * guard plus claim-exhaustive `Proxy` probes, fail-closed); this thin delegation
+  * is the seam the gate test exercises. A non-owner DO is never relay-uniform.
+  */
+  protected isShapeRelayUniform(name: string, args: Record<string, unknown>): boolean;
+  /**
+  * Read the FULL current membership of a `.global()`-table shape from its D1
+  * (or Hyperdrive) backend — the seed/poll source for the latency-tiered
+  * global shape path. A `.global()` table lives in another store with no
+  * per-DO op-log, so this is the only way to learn its rows from inside the
+  * shard DO; {@link ShardDO.seedGlobalShape} calls it once on subscribe and
+  * {@link ShardDO.refreshGlobalShape} on every alarm tick, diffing the result
+  * against the per-socket snapshot to compute the poke.
+  *
+  * The base class has no global backend, so it returns `[]` (a base-only DO,
+  * or a project with no global tables, never resolves a global shape). The
+  * codegen subclass overrides it to drain `globalDb.findMany(table, { where:
+  * effectiveWhere })` under the socket's verified `identity` — the same
+  * unforgeable value `resolveShape` composed the RLS predicate with, so the
+  * D1 read is identity-scoped exactly like the poke-live path.
+  */
+  protected readGlobalShapeRows(_resolved: ResolvedShape, _identity?: SubscriptionIdentity): Promise<ShapeRow[]>;
+  /**
+  * Poll external-source (`.source(...)`) tables once (plan 077): materialize
+  * each sourced table's freshly-pulled tenant slice into this DO's SQLite. The
+  * base `ShardDO` has no sourced tables, so it returns `0` and the ingest tier
+  * stays dormant — zero behavior change for every existing DO. The codegen
+  * subclass overrides it to, per sourced table, build a `createShardCtxDb`
+  * writer, read the tenant slice from Hyperdrive under this DO's shard key, and
+  * run `runExternalSourceTick` (read local baseline → diff → apply via the
+  * validated CDC writer). Returns the number of sourced tables still being
+  * polled, so the shared poll alarm ({@link ShardDO.alarm}) re-arms while ingest
+  * is active.
+  */
+  protected pollExternalSources(): Promise<number>;
+  /**
+  * Arm the shared poll alarm for external-source ingest (plan 077). The alarm is
+  * shared with the global-shape poll tier; the codegen subclass calls this once
+  * (on construction / first sourced write) so a sourced DO starts its ingest
+  * loop, after which {@link ShardDO.alarm} re-arms itself while
+  * {@link ShardDO.pollExternalSources} reports remaining work. Idempotent; a
+  * no-op when the runtime exposes no `setAlarm` (unit harness).
+  */
+  protected scheduleSourcePoll(): Promise<void>;
+  /** This DO's shard key (its DO name), or `__root__` for the single-DO default. The `tenantBy` mapper binds it into the source query. */
+  protected currentShardKey(): string;
+  /** Record a contained external-source ingest failure (one sourced table's poll) into the log ring without aborting the others. */
+  protected recordExternalSourceError(table: string, error: unknown): void;
+  /**
   * Look up a streaming-query function and return a thunk that produces the
   * `AsyncIterable&lt;unknown>` when handed an {@link AbortSignal}. The codegen
   * subclass overrides this to dispatch via `LUNORA_FUNCTIONS`; the base
@@ -4837,6 +5555,26 @@ declare abstract class ShardDO {
   */
   private errorToResponse;
   /**
+  * Batch dispatch (plan 088). Applies each `calls[]` entry through the SAME
+  * single-call `/rpc` path (via a nested `this.fetch`), **sequentially**, so
+  * the per-`(identity, mutationId)` idempotency dedup and the per-client
+  * `__client_watermark` ordering are enforced entry-by-entry exactly as for an
+  * individual call — no duplication of the dispatch core, no reordering.
+  *
+  * Failures are **per-slot, not fail-fast**: an entry that throws (or a
+  * custom-mutator `OUT_OF_ORDER` gap) is captured in its own result slot and
+  * later entries still run. Ordering is still safe — a later same-client
+  * mutator after a gap re-classifies as a gap too (the watermark never
+  * advanced), so it cannot apply out of order; unrelated entries/queries are
+  * independent. The response is `{ results: [{ id, status, body }] }` in
+  * request order; each `body` is the untouched single-call envelope (its
+  * `result` already wire-encoded), so the client demuxes + decodes each
+  * exactly as one call.
+  */
+  private handleBatchRpc;
+  /** Dispatch one batch entry through the single-call `/rpc` path and capture its envelope (plan 088). */
+  private dispatchBatchEntry;
+  /**
   * Serve a reserved admin-introspection RPC (`__lunora_admin__:*`) for the
   * data browser. Gated by `env.LUNORA_ADMIN_TOKEN`: introspection is
   * **disabled unless the token is configured**, and when it is, the request
@@ -4920,6 +5658,16 @@ declare abstract class ShardDO {
   */
   private handleGetWorkflowInstanceStatus;
   /**
+  * Serve `__lunora_admin__:listFlags` — the studio's read-only Flags page.
+  * Evaluates every statically-discovered feature flag under an optional
+  * `args.context` targeting context (the studio's editable context editor)
+  * via the {@link evaluateFlags} hook, which the codegen subclass overrides
+  * with live OpenFeature evaluation. Read-only: a flag lookup mutates no shard
+  * state, so nothing is flushed or audited. Admin-gated by `handleAdminRpc`'s
+  * caller.
+  */
+  private handleListFlags;
+  /**
   * Run `run()` with the per-request identity pinned to (`userId`, `identity`),
   * then restore the prior values in a `finally` (even if `run()` throws), so the
   * forced identity can never leak into a later dispatch on this DO instance. The
@@ -5111,6 +5859,20 @@ declare abstract class ShardDO {
   * Read-only: it touches no SQLite and mutates no socket state.
   */
   private collectSubscriptions;
+  /**
+  * Assemble the `__lunora_admin__:getFanoutMetrics` payload for the Studio
+  * fan-out observability panel (plan 075 Phase 1). The point-in-time topic
+  * subscriber counts are folded live from each socket's attachment via
+  * {@link summarizeFanoutTopics}; the running per-path cost counters are the
+  * in-memory {@link ShardDO.fanout} tallies, sharing `metrics.sinceMs` as the
+  * "since this instance woke" epoch. Touches no SQLite and mutates no socket
+  * state; it does call `relay.relayCount()`, which advances the promotion
+  * latch — safe here because that transition is a pure, monotonic function of
+  * the live socket count (DOs are single-threaded), so a metrics poll only ever
+  * drives the latch to the same state the routing path would compute for the
+  * same count, never a divergent one.
+  */
+  private collectFanoutMetrics;
   /** Resolve a `getAuditLog` admin read, parsing the optional `limit`/`sinceSeq` cursor args and ensuring the reserved table first. */
   private readAdminAuditLog;
   /**
@@ -5179,6 +5941,49 @@ declare abstract class ShardDO {
   */
   private executeAdminSubscription;
   /**
+  * Resolve one subscription (seed or refresh) to its {@link SubscriptionOutcome}
+  * by routing the `functionPath` to the right read path — shared by
+  * {@link seedSubscription} and {@link refreshSubscriptions} so both branch
+  * identically:
+  * - `__lunora_admin__:*` → {@link executeAdminSubscription} (raw SQLite read).
+  * - {@link FLAGS_FUNCTION_PREFIX} → {@link runFlagSubscriptionRead} (the codegen subclass evaluates the flag through the configured provider). The value isn't bound to any table, so it is tagged with the {@link ADMIN_WILDCARD} dep — re-evaluated on every write-flush so a live `useFlag` stays current within a session. A `null` read means "nothing to deliver" (no provider, or a flag that resolved to `null`).
+  * - everything else → {@link executeSubscription} (the user query, under the socket's own by-value identity).
+  */
+  private resolveReactiveOutcome;
+  /**
+  * SECURITY BOUNDARY for cross-socket reactive dedup. A read is
+  * identity-INDEPENDENT only when its result cannot vary by the caller's
+  * verified identity — i.e. the admin/reserved introspection reads, which
+  * route to {@link executeAdminSubscription} and ignore the
+  * {@link SubscriptionIdentity} entirely.
+  *
+  * Everything else is identity-DEPENDENT and must NEVER be shared across
+  * sockets: a user query may be `rls()` / `ctx.auth`-scoped (different rows
+  * per identity), and a flag read ({@link FLAGS_FUNCTION_PREFIX}) evaluates
+  * the provider with the subscriber's identity (per-user targeting). Sharing
+  * one socket's result with another would leak one identity's rows/flags to a
+  * different identity, so this predicate gates {@link resolveReactiveOutcomeDeduped}
+  * shut for them.
+  */
+  protected isIdentityIndependent(functionPath: string): boolean;
+  /**
+  * Memoizing wrapper over {@link resolveReactiveOutcome}: flush-local sharing across sockets.
+  * Within a single {@link refreshSubscriptions} pass, N sockets subscribed to
+  * the SAME identity-independent `(functionPath, args)` re-run the query N
+  * times today (see the Case-6 fan-out characterization). When the read is
+  * identity-independent (admin/reserved — see {@link isIdentityIndependent})
+  * its result is the same for every socket, so the first run is cached (by its
+  * in-flight Promise, since the bounded worker pool runs sockets in parallel)
+  * and shared with the rest — collapsing N runs to ONE.
+  *
+  * Identity-DEPENDENT reads are passed straight through, UNCACHED: each socket
+  * must evaluate under its own by-value identity (RLS / `ctx.auth` / per-user
+  * flags), so they never share a result. The `cache` is created fresh per
+  * flush by the caller, so a result is never reused across passes (it would go
+  * stale after the next write).
+  */
+  private resolveReactiveOutcomeDeduped;
+  /**
   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
   * `false` (closed) when the token is unset so admin introspection is
   * opt-in rather than exposed by default.
@@ -5210,6 +6015,17 @@ declare abstract class ShardDO {
   */
   private flushChangedTables;
   /**
+  * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
+  * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
+  * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
+  * by the next loop iteration, so every committed write is observed by a
+  * refresh that runs after it — bursts simply share a pass. The post-write
+  * high-watermark and live-socket set are re-read inside each
+  * `refreshSubscriptions` / `pokeShapeSubscribers` call, so a later batch
+  * always reflects the latest committed state.
+  */
+  private drainSubscriptionRefreshes;
+  /**
   * For every live subscription whose query reads one of `changed`, re-run
   * the query and push a fresh `{ type: "data" }` frame when the result
   * differs from the last one sent. Subscriptions with no `functionPath`
@@ -5282,6 +6098,216 @@ declare abstract class ShardDO {
   */
   private seedSubscription;
   /**
+  * Drive the full `shape_subscribe` flow as one failure-aware unit: persist the
+  * attachment, seed the shape, and ack ONLY once both succeed. A persist
+  * rejection (`too_many`/`serialize_failed`) or a seed that can't resolve the
+  * shape (unknown / RLS-denied / cross-shard-invalid) rolls the attachment back
+  * and sends an `error` frame instead of acking — so a client is never left
+  * acked but subscribed to a shape that will never deliver. Never throws (a
+  * thrown `webSocketMessage` is fatal to the hibernating socket).
+  */
+  private handleShapeSubscribe;
+  /** Send a structured `error` frame for a failed `shape_subscribe`, swallowing a send on an already-closed socket. */
+  private sendShapeSubscribeError;
+  /**
+  * Seed a freshly-registered shape subscription. Resolves the shape under the
+  * socket's verified identity, then ships either:
+  *
+  * - a **catch-up** poke (the membership diff in `(sinceCheckpoint, cursor]`)
+  * when the client supplied a still-current checkpoint within the CDC retention
+  * window and on this epoch — the cheap reconnect path; or
+  * - a **full** insert-poke of the shape's entire current membership — a
+  * first-time subscribe, or a reconnect that fell outside retention / forked
+  * epoch.
+  *
+  * Either way the per-socket shape memo advances to the flush watermark so
+  * later `pokeShapeSubscribers` passes diff from the right point.
+  *
+  * Returns `"ok"` once the shape resolved and its seed poke was attempted, or a
+  * `{ code, message }` failure when the shape can't be resolved — an unknown /
+  * RLS-denied shape (a base class with no registry resolves nothing), or a
+  * `resolveShape` that threw (e.g. a cross-shard-join guard). The caller rolls
+  * back the persisted attachment and errors instead of acking, so a client is
+  * never left subscribed to a shape that will never deliver.
+  */
+  private seedShapeSubscription;
+  /**
+  * Seed a non-`.global()` (op-log-backed) shape: either a catch-up diff over
+  * `(sinceSeq, cursor]` when the client supplied a still-current checkpoint on
+  * this epoch within the CDC retention window, or a full membership insert-poke
+  * otherwise. The memo advances to `cursor` only once the poke is delivered, so
+  * a failed send re-diffs from the prior point rather than skipping rows. May
+  * throw (a stub `sql` handle, a membership probe failure); the caller converts
+  * it to a structured `shape_subscribe` error.
+  */
+  private seedOpLogShape;
+  /**
+  * Compute an op-log shape seed (cursor, epoch, the resume base, and the
+  * membership `rowsPatch`) WITHOUT sending — the shared core of
+  * {@link ShardDO.seedOpLogShape} (sends to a local socket) and the owner relay's
+  * `buildShapeSeedFrames` (serializes the frames for a relay to deliver, plan 075
+  * Phase 3, via the {@link RelayHost} seam). Resume only when CDC is on, the client is on this
+  * epoch, its checkpoint doesn't run ahead of ours, and the log still covers it;
+  * else a full re-seed. A fully-compacted log only proves "nothing missed" when
+  * the client is already at `cursor`.
+  * @returns the cursor/epoch, the resume base (`baseCheckpoint`), and the membership patch
+  */
+  private computeOpLogShapeSeed;
+  /**
+  * Fan the membership diff of every shape affected by this flush to its
+  * subscribers — the partial-replication parallel to
+  * {@link ShardDO.refreshSubscriptions}, called alongside it from
+  * {@link ShardDO.flushChangedTables}. For each socket (bounded fan-out, same
+  * concurrency + `awaitWsDrain` backpressure as the subscription path) it
+  * resolves each shape under the socket's identity, diffs only the shapes
+  * whose table changed in `(memoCursor, frameCursor]`, and emits one poke
+  * carrying a part per changed shape. No-op when no socket holds a shape.
+  */
+  private pokeShapeSubscribers;
+  /**
+  * Diff every op-log-backed shape a socket holds against this flush, splitting
+  * the results into the poke parts to send and the per-shape memo advances. A
+  * `.global()` shape (driven by the alarm poll loop, not this flush) and a shape
+  * whose table didn't change are skipped; a shape whose resolve/diff throws is
+  * logged and skipped with its memo unadvanced so a later flush retries. Empty
+  * diffs advance unconditionally; part-bearing shapes advance only once the
+  * caller confirms the poke was delivered.
+  */
+  private collectShapePokeParts;
+  /**
+  * Drain the op-log range `(sinceSeq, upTo]` for `table` into the latest op per
+  * row id (collapsing multiple ops on the same row to the newest). Within one
+  * flush, every shape over the SAME `(table, sinceSeq, upTo)` reads the
+  * identical changelog slice, so the drained map is memoized in the
+  * caller-supplied `cache` (created fresh per flush) — N shapes on a table
+  * share ONE changelog drain instead of re-scanning it per shape. The
+  * per-shape membership probe still runs per shape (its predicate is
+  * identity/args-specific), so only the shared op read is collapsed.
+  */
+  private readShapeOpRange;
+  /**
+  * Read one page of the `__cdc_log` for a shape diff (table-scoped). A thin
+  * protected seam over {@link readCdcChanges}: it isolates the single
+  * changelog read that {@link readShapeOpRange} memoizes per flush, and gives
+  * tests a point to count the reads the op-range cache collapses.
+  */
+  protected readShapeCdcPage(sql: SqlExec, sinceSeq: number, tables: ReadonlySet<string>): {
+    changes: CdcChange[];
+    cursor: number;
+  };
+  /**
+  * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
+  * the changelog (drained across pages via {@link readShapeOpRange}, shared
+  * across same-range shapes in a flush), collapses to the latest op per row,
+  * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
+  * changed ids: a row still in the set → upsert with its post-image doc
+  * (projected to the shape's columns); a row that left the set, or any delete,
+  * → `delete(key)` (a delete carries no post-image, so membership is
+  * unknowable from the op alone — the client no-ops an unknown key).
+  */
+  private buildShapeDiff;
+  /** Build the full insert-poke of a shape's current membership — the first-seed/full-reseed rowset. */
+  private buildShapeSeed;
+  /**
+  * Seed a `.global()`-table shape: read its full membership from D1, ship it
+  * as one insert-poke, record the membership snapshot the alarm poll loop will
+  * diff against, and arm the poll alarm. A global shape has no op-log cursor,
+  * so the poke is stamped at this DO's current cursor (informational only) and
+  * carries no resume base — a reconnect always re-seeds full.
+  */
+  private seedGlobalShape;
+  /**
+  * Re-read a global shape's membership from D1 and poke only the diff against
+  * the socket's last snapshot: a new key → `insert`, a changed projected value
+  * → `update`, a vanished key → `delete`. The snapshot advances to the fresh
+  * membership even when the diff is empty, so the next tick compares from here.
+  * No frame is sent when nothing changed (the common steady-state tick).
+  */
+  private refreshGlobalShape;
+  /**
+  * Read a socket's global-shape baseline, preferring the hot in-memory cache
+  * and falling back to the durable `__global_shape_snapshot` table on a miss (a
+  * cold socket after a hibernation eviction). The loaded baseline repopulates
+  * the cache so subsequent ticks in this wake hit memory. An empty
+  * `connectionId` (a socket that never went through the lifecycle-aware upgrade,
+  * e.g. a unit harness) skips the durable read and behaves as in-memory-only.
+  */
+  private readGlobalSnapshot;
+  /** Record a socket's latest global-shape membership snapshot in the in-memory cache (creating the per-socket map lazily). */
+  private recordGlobalSnapshot;
+  /**
+  * Load a durable global-shape baseline from SQLite, or an empty map when none
+  * is stored / the durable path is unavailable. A stub `sql` handle (unit
+  * harness) or a missing table degrades to in-memory-only behavior rather than
+  * failing the poll tick.
+  */
+  private loadGlobalSnapshot;
+  /**
+  * Persist a socket's global-shape baseline to SQLite so the poll-loop diff
+  * survives hibernation. A no-op for a connection-id-less socket or a stub
+  * `sql` handle (the in-memory cache then carries the baseline for the DO's
+  * lifetime, matching the pre-durable behavior).
+  */
+  private saveGlobalSnapshot;
+  /**
+  * Arm the poll alarm for `.global()` shapes if one isn't already pending.
+  * Idempotent — every global-shape seed calls it, but only the first arms the
+  * alarm. Degrades to a no-op when the runtime exposes no `setAlarm` (the unit
+  * harness): a global shape is then seed-only, which the poll-loop tests assert
+  * by driving {@link ShardDO.alarm} directly.
+  */
+  private scheduleGlobalPoll;
+  /**
+  * Record a contained shape-tier error (poll / poke / seed) into the DO's log
+  * ring without aborting the rest of the pass. The shape pipeline is a
+  * best-effort fan-out: one socket's read or one shape's resolve failing must
+  * never take down the others — so callers swallow the throw and surface it
+  * here for diagnosis. `context` is a synthetic `shape:phase:subId` path.
+  */
+  private recordShapeError;
+  /**
+  * Guard a global shape's materialized membership against {@link
+  * ShardDO.GLOBAL_SHAPE_MAX_ROWS}. Returns `true` when the row count is within
+  * the cap; otherwise records a diagnosable error and returns `false` so the
+  * caller fails the shape closed (no snapshot retained, no poke sent) rather
+  * than risking a DO eviction on an unbounded global table. The transient read
+  * buffer is bounded by the same gate — an over-cap membership is dropped, not
+  * snapshotted per socket.
+  */
+  private withinGlobalShapeBound;
+  /**
+  * Refresh every `.global()`-table shape held across all live sockets, one
+  * diff-poke per (socket, shape). Returns the number of global shapes still
+  * subscribed so {@link ShardDO.alarm} knows whether to re-arm. Expired sockets
+  * are dropped in passing (mirrors {@link ShardDO.pokeShapeSubscribers}).
+  */
+  private pollGlobalShapes;
+  /**
+  * Refresh one socket's `.global()`-table shapes, containing per-shape
+  * failures so a single throw never aborts the poll tick (and with it the
+  * re-arm). Returns the count of global shapes still subscribed on this socket
+  * — a failed `resolveShape`/read keeps its shape counted so the alarm keeps
+  * polling and retries next tick.
+  */
+  private pollSocketGlobalShapes;
+  /**
+  * Send one poke (`pokeStart` → `pokePart` per shape → `pokeEnd`) to a socket.
+  * All parts apply atomically at `pokeEnd`. Returns `true` when every frame was
+  * handed to the socket, `false` when a send threw mid-poke (the socket closed)
+  * — callers must NOT advance their shape baselines on a `false` so the client
+  * re-receives the rows on its next flush/reconnect instead of losing them.
+  */
+  private sendPoke;
+  /**
+  * The recipient client's `__client_watermark` for stamping a poke's
+  * `lastMutationId`, or `undefined` when the socket announced no `clientId`
+  * (a client that doesn't use custom mutators — nothing to drop an overlay
+  * for). Read off the attachment so it survives hibernation.
+  */
+  private socketClientWatermark;
+  /** Record a shape's poke baseline cursor on a socket (creating the per-socket map lazily). */
+  private recordShapeMemo;
+  /**
   * Record `outcome` as this socket's diff baseline for `subId` without
   * sending a frame. Used by the resume fast-path, where the client keeps its
   * cached value but the server still needs a baseline so the next
@@ -5353,6 +6379,15 @@ declare abstract class ShardDO {
   * on older runtimes, where it degrades to a no-op.
   */
   private armWebSocketKeepalive;
+  /**
+  * Route the non-RPC requests `fetch` handles before the shard-local RPC
+  * endpoint: a WebSocket upgrade, and the internal `/_lunora/relay` owner↔relay
+  * control channel (never reachable by a client — the runtime forwards only
+  * worker-internal traffic there). Returns `undefined` for an RPC request, which
+  * `fetch` then dispatches.
+  * @returns the routed response, or `undefined` when this is an RPC request
+  */
+  private routeNonRpc;
   private handleWebSocketUpgrade;
   /**
   * Whether this shard has a `__cdc_log` table. The single source of the
@@ -5400,6 +6435,14 @@ declare abstract class ShardDO {
   * but per-topic auth does not exist here; see `whisperSubscribe` on the client.
   */
   private broadcastWhisper;
+  /**
+  * Deliver an already-serialized whisper `frame` to every local socket joined to
+  * `topic`, excluding `exclude` (the sender, or `undefined` for a frame the relay
+  * hub forwarded in — its sender lives on another DO). Records the fan-out pass
+  * for `getFanoutMetrics` (plan 075 Phase 1). Pure delivery — no SQLite, no CDC.
+  * @returns the number of sockets the frame was sent to
+  */
+  private deliverWhisperLocal;
   private readAttachment;
 }
 /**
@@ -5573,8 +6616,11 @@ interface WhereSqlStrategy {
   fieldRef: FieldRefSql;
   /**
   * Dialect `contains` rendering given the field reference and the (already
-  * bound) search term. Absent ⇒ the portable `… LIKE '%' || term || '%'`
-  * concat form (SQLite/Postgres); MySQL supplies a `CONCAT(...)` variant.
+  * bound, already wildcard-escaped) search term. Absent ⇒ the portable
+  * `… LIKE '%' || term || '%' ESCAPE '\'` concat form (SQLite/Postgres); MySQL
+  * supplies a `CONCAT(...)` variant. The term is escaped by
+  * {@link compileContains}, so an implementation MUST pair it with
+  * `ESCAPE '\'` for the literal-match to hold.
   */
   likeContains?: (reference: SQL, term: SQL) => SQL;
   /**
@@ -5596,4 +6642,4 @@ interface WhereSqlStrategy {
 * `undefined` when the input imposes no constraint (empty `where`).
 */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection$1 as SortDirection, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, armRestore, assertFlatPredicate, assertReadonly, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, listTables, matchesRankStaticWhere, matchesStaticWhere, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };