@supalive/core 1.20.2 → 1.22.0

package/dist/index-CzW0TkpK.d.ts

@@ -0,0 +1,2729 @@
+import { i as ObjectStorage } from "./object-storage-DTVmZq3l.js";
+import z, { ZodRawShape, ZodType, z as z$1 } from "zod";
+import { Span } from "@opentelemetry/api";
+import { RetryPolicy } from "cockatiel";
+import pino from "pino";
+import Redis from "ioredis";
+
+//#region src/db/types_db.d.ts
+/** Monotonically increasing integer from global_commit_ts sequence in Postgres */
+type CommitTs = bigint;
+declare const BigIntSchema: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+declare const CompareOperatorSchema: z.ZodEnum<{
+  "=": "=";
+  "!=": "!=";
+  ">": ">";
+  ">=": ">=";
+  "<": "<";
+  "<=": "<=";
+  like: "like";
+  ilike: "ilike";
+  contains: "contains";
+  icontains: "icontains";
+  between: "between";
+  in: "in";
+  jsonContains: "jsonContains";
+  jsonContainedBy: "jsonContainedBy";
+  jsonHasKey: "jsonHasKey";
+  jsonArrayContains: "jsonArrayContains";
+  isNull: "isNull";
+  isNotNull: "isNotNull";
+}>;
+type CompareOperator = z.infer<typeof CompareOperatorSchema>;
+type Predicate = LeafPredicate | {
+  kind: "and";
+  children: Predicate[];
+} | {
+  kind: "or";
+  children: Predicate[];
+};
+declare const PredicateSchema: z.ZodType<Predicate>;
+declare const LeafPredicateSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"leaf">;
+  column: z.ZodString;
+  operator: z.ZodEnum<{
+    "=": "=";
+    "!=": "!=";
+    ">": ">";
+    ">=": ">=";
+    "<": "<";
+    "<=": "<=";
+    like: "like";
+    ilike: "ilike";
+    contains: "contains";
+    icontains: "icontains";
+    between: "between";
+    in: "in";
+    jsonContains: "jsonContains";
+    jsonContainedBy: "jsonContainedBy";
+    jsonHasKey: "jsonHasKey";
+    jsonArrayContains: "jsonArrayContains";
+    isNull: "isNull";
+    isNotNull: "isNotNull";
+  }>;
+  value: z.ZodUnknown;
+  value2: z.ZodOptional<z.ZodUnknown>;
+  raw: z.ZodOptional<z.ZodBoolean>;
+  path: z.ZodOptional<z.ZodString>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    one: "one";
+    all: "all";
+  }>>;
+}, z.core.$strip>;
+type LeafPredicate = z.infer<typeof LeafPredicateSchema>;
+declare const AndPredicateSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"and">;
+  children: z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>;
+}, z.core.$strip>;
+type AndPredicate = z.infer<typeof AndPredicateSchema>;
+declare const OrPredicateSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"or">;
+  children: z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>;
+}, z.core.$strip>;
+type OrPredicate = z.infer<typeof OrPredicateSchema>;
+/** Query specification - what was queried (used for cache key generation) */
+type QuerySpec = ReadEntry;
+declare function normalizeIdToBytes(id: string | number, fromHex?: boolean): Uint8Array;
+declare function normalizeToBytes(value: Uint8Array | unknown): Uint8Array;
+declare function bytesFromJson(value: Uint8Array | unknown): Uint8Array;
+declare const PointReadSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"point">;
+  table: z.ZodString;
+  id: z.ZodString;
+  expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+}, z.core.$strip>;
+type PointRead = z.infer<typeof PointReadSchema>;
+declare const RawPointReadSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"point">;
+  tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  id: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  table: z.ZodString;
+  expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+}, z.core.$strip>;
+type RawPointRead = z.infer<typeof RawPointReadSchema>;
+/**
+ * Query specification for a range read (get with filters).
+ * This is the query definition, not the result.
+ */
+declare const RangeReadSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"range">;
+  table: z.ZodString;
+  predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+  columns: z.ZodArray<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type RangeRead = z.infer<typeof RangeReadSchema>;
+declare const RawRangeReadSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"range">;
+  table: z.ZodString;
+  tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+  columns: z.ZodArray<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type RawRangeRead = z.infer<typeof RawRangeReadSchema>;
+declare const ReadEntrySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"point">;
+  table: z.ZodString;
+  id: z.ZodString;
+  expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"range">;
+  table: z.ZodString;
+  predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+  columns: z.ZodArray<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>]>;
+type ReadEntry = z.infer<typeof ReadEntrySchema>;
+declare const RawReadEntrySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"point">;
+  tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  id: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  table: z.ZodString;
+  expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"range">;
+  table: z.ZodString;
+  tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+  columns: z.ZodArray<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>]>;
+type RawReadEntry = z.infer<typeof RawReadEntrySchema>;
+declare const WriteOpSchema: z.ZodEnum<{
+  insert: "insert";
+  update: "update";
+  delete: "delete";
+}>;
+type WriteOp = z.infer<typeof WriteOpSchema>;
+declare const WriteEntrySchema: z.ZodObject<{
+  table: z.ZodString;
+  tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+  id: z.ZodString;
+  op: z.ZodEnum<{
+    insert: "insert";
+    update: "update";
+    delete: "delete";
+  }>;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  prevData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+}, z.core.$strip>;
+type WriteEntry = z.infer<typeof WriteEntrySchema>;
+interface CommitLogEntry {
+  id: Uint8Array;
+  ts: bigint;
+  tableId: Uint8Array;
+  data: Uint8Array;
+  _parsedData?: Record<string, unknown> | null;
+}
+interface MutationResult<T> {
+  result: T;
+  writeSet: WriteEntry[];
+  commitTs: CommitTs;
+}
+interface LiveResult<T> {
+  ts: bigint;
+  data: T;
+  readSet: ReadEntry[];
+  /**
+   * Ephemeral keys (see db/ephemeral.ts) this computation read. A parallel
+   * dependency set to `readSet`: these carry no snapshot ts and no commit log,
+   * so they are invalidated by exact key match rather than predicate overlap,
+   * and are deliberately kept OUT of `readSet` so the OCC validator and the
+   * commit-log freshness scan never see them.
+   */
+  ephemeralKeys: string[];
+}
+declare const QueryCacheMetadataSchema: z.ZodObject<{
+  lastSnapshotTs: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+  version: z.ZodString;
+  readSet: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"point">;
+    table: z.ZodString;
+    id: z.ZodString;
+    expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"range">;
+    table: z.ZodString;
+    predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+    columns: z.ZodArray<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  }, z.core.$strip>]>>;
+  ephemeralKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type QueryCacheMetadata = z.infer<typeof QueryCacheMetadataSchema>;
+declare const QueryCacheEntrySchema: z.ZodObject<{
+  lastSnapshotTs: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+  data: z.ZodUnknown;
+  version: z.ZodString;
+}, z.core.$strip>;
+type QueryCacheEntry = z.infer<typeof QueryCacheEntrySchema>;
+declare const CachedPgMetadataSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+type CachedPgMetadata = z.infer<typeof CachedPgMetadataSchema>;
+interface RetryConfig {
+  maxAttempts: number;
+  backoff: "none" | "linear" | "exponential";
+  delayMs?: number;
+  onConflict?: (attempt: number, error: OccConflictError) => void;
+}
+declare const NO_RETRY: RetryConfig;
+declare const DEFAULT_RETRY: RetryConfig;
+declare class OccConflictError extends Error {
+  readonly reason: string;
+  readonly conflictDetail?: unknown | undefined;
+  constructor(reason: string, conflictDetail?: unknown | undefined);
+  static isOccConflictError(err: unknown): boolean;
+}
+declare class OccAbortError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/server/sub-manager-types.d.ts
+declare const RegisterSubscriptionParamsSchema: z.ZodObject<{
+  subId: z.ZodString;
+  cacheKey: z.ZodString;
+  queryName: z.ZodString;
+  args: z.ZodUnknown;
+  queryIdentity: z.ZodString;
+  instanceName: z.ZodString;
+  lastSnapshotTs: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+}, z.core.$strip>;
+type RegisterSubscriptionParams = z.infer<typeof RegisterSubscriptionParamsSchema>;
+declare const RegisterSubscriptionResultSchema: z.ZodObject<{
+  cacheKey: z.ZodString;
+  recompute: z.ZodBoolean;
+  readSet: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"point">;
+    table: z.ZodString;
+    id: z.ZodString;
+    expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"range">;
+    table: z.ZodString;
+    predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+    columns: z.ZodArray<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  }, z.core.$strip>]>>;
+  ephemeralKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RegisterSubscriptionResult = z.infer<typeof RegisterSubscriptionResultSchema>;
+declare const UpdateSubscriptionReadSetParamsSchema: z.ZodObject<{
+  cacheKey: z.ZodString;
+  subId: z.ZodString;
+  instanceName: z.ZodString;
+  lastSnapshotTs: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+  readSet: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"point">;
+    table: z.ZodString;
+    id: z.ZodString;
+    expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"range">;
+    table: z.ZodString;
+    predicate: z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>;
+    columns: z.ZodArray<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  }, z.core.$strip>]>>;
+  ephemeralKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type UpdateSubscriptionReadSetParams = z.infer<typeof UpdateSubscriptionReadSetParamsSchema>;
+/**
+ * `tracked: false` means the sub-manager has no record of this subId (e.g.
+ * a restart wiped state and the caller hasn't re-registered yet). The app
+ * server should treat this as a signal to register the sub before retrying.
+ */
+declare const UpdateSubscriptionReadSetResultSchema: z.ZodObject<{
+  tracked: z.ZodBoolean;
+}, z.core.$strip>;
+type UpdateSubscriptionReadSetResult = z.infer<typeof UpdateSubscriptionReadSetResultSchema>;
+declare const UnregisterSubscriptionParamsSchema: z.ZodObject<{
+  subId: z.ZodString;
+  instanceName: z.ZodString;
+}, z.core.$strip>;
+type UnregisterSubscriptionParams = z.infer<typeof UnregisterSubscriptionParamsSchema>;
+declare const UnregisterSubscriptionsParamsSchema: z.ZodArray<z.ZodObject<{
+  subId: z.ZodString;
+  instanceName: z.ZodString;
+}, z.core.$strip>>;
+type UnregisterSubscriptionsParams = z.infer<typeof UnregisterSubscriptionsParamsSchema>;
+declare const UnregisterSubscriptionResultSchema: z.ZodObject<{
+  ok: z.ZodBoolean;
+}, z.core.$strip>;
+type UnregisterSubscriptionResult = z.infer<typeof UnregisterSubscriptionResultSchema>;
+declare const UnregisterSubscriptionsResultSchema: z.ZodArray<z.ZodObject<{
+  ok: z.ZodBoolean;
+}, z.core.$strip>>;
+type UnregisterSubscriptionsResult = z.infer<typeof UnregisterSubscriptionsResultSchema>;
+declare const InvalidateWritesetParamsSchema: z.ZodObject<{
+  writeSet: z.ZodArray<z.ZodObject<{
+    table: z.ZodString;
+    tableId: z.ZodPipe<z.ZodAny, z.ZodTransform<Uint8Array<ArrayBufferLike>, any>>;
+    id: z.ZodString;
+    op: z.ZodEnum<{
+      insert: "insert";
+      update: "update";
+      delete: "delete";
+    }>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    prevData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    expectedCommitTs: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type InvalidateWritesetParams = z.infer<typeof InvalidateWritesetParamsSchema>;
+/**
+ * Ephemeral counterpart of {@link InvalidateWritesetParamsSchema}. Carries just
+ * the written keys — matching is an exact key lookup in the worker's index, with
+ * no predicate to evaluate and no row images to compare, so there is nothing
+ * else to send. The recompute re-reads the current value from Redis, so the
+ * VALUE never travels on this path either.
+ */
+declare const InvalidateEphemeralParamsSchema: z.ZodObject<{
+  keys: z.ZodArray<z.ZodString>;
+  version: z.ZodString;
+}, z.core.$strip>;
+type InvalidateEphemeralParams = z.infer<typeof InvalidateEphemeralParamsSchema>;
+declare const AffectedSubscriptionSchema: z.ZodObject<{
+  subId: z.ZodString;
+  queryName: z.ZodString;
+  args: z.ZodUnknown;
+  cacheKey: z.ZodString;
+  notifyInstances: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type AffectedSubscription = z.infer<typeof AffectedSubscriptionSchema>;
+declare const InvalidateWritesetResultSchema: z.ZodObject<{
+  affected: z.ZodArray<z.ZodObject<{
+    subId: z.ZodString;
+    queryName: z.ZodString;
+    args: z.ZodUnknown;
+    cacheKey: z.ZodString;
+    notifyInstances: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type InvalidateWritesetResult = z.infer<typeof InvalidateWritesetResultSchema>;
+declare const InvalidateEphemeralResultSchema: z.ZodObject<{
+  affected: z.ZodArray<z.ZodObject<{
+    subId: z.ZodString;
+    queryName: z.ZodString;
+    args: z.ZodUnknown;
+    cacheKey: z.ZodString;
+    notifyInstances: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type InvalidateEphemeralResult = z.infer<typeof InvalidateEphemeralResultSchema>;
+declare const RegistrationRecordSchema: z.ZodObject<{
+  queryName: z.ZodString;
+  args: z.ZodUnknown;
+  queryIdentity: z.ZodString;
+  cacheKey: z.ZodString;
+}, z.core.$strip>;
+type RegistrationRecord = z.infer<typeof RegistrationRecordSchema>;
+//#endregion
+//#region src/db/cache.d.ts
+declare class CacheLayer {
+  redis: Redis;
+  private readonly ttlSeconds;
+  /** Cached EVALSHA digests keyed by Lua source (see evalScript). */
+  private readonly scriptShaCache;
+  constructor(redis: Redis, ttlSeconds?: number);
+  /**
+   * Run a Lua script via EVALSHA using the script's SHA1 (computed locally — the
+   * same digest Redis keys scripts by, so no SCRIPT LOAD round-trip is needed on
+   * the hot path). On NOSCRIPT (the script isn't in Redis's cache yet, e.g. first
+   * use or after a Redis restart/failover) load it explicitly via SCRIPT LOAD and
+   * re-run via EVALSHA — so the script ends up cached server-side and subsequent
+   * EVALSHA calls hit. The runtime client is always ioredis (see initCacheLayer).
+   */
+  evalScript(src: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+  /** One-shot recompute: atomically write data + metadata (CAS on version). */
+  setQueryCacheAndMetadataFor(cacheKey: string, data: unknown, metaData: QueryCacheMetadata, ttlSeconds?: number): Promise<void>;
+  /** Subscribe path: write the data blob only (CAS against the metadata's
+   *  version). The metadata is written separately by the sub-worker; the
+   *  `version` links the two so a divergent pair is detected on read. Takes the
+   *  snapshot ts directly (rather than a pre-stringified version) so the entry
+   *  can carry `lastSnapshotTs` as its own field; `version` is derived from it,
+   *  preserving the `version === String(ts)` convention the CAS relies on. */
+  setQueryCacheFor(cacheKey: string, data: unknown, lastSnapshotTs: bigint, ttlSeconds?: number): Promise<void>;
+  getQueryCacheFor(cacheKey: string): Promise<QueryCacheEntry | null>;
+  /** Subscription recompute: replace the whole metadata (CAS on version). */
+  replaceQueryCacheMetadata(cacheKey: string, metaData: QueryCacheMetadata, ttlSeconds?: number): Promise<void>;
+  /** Still-fresh subscription: advance `lastSnapshotTs` only, preserving the
+   *  data's `version` + `readSet` (no recompute). Monotonic and non-clobbering
+   *  — see ADVANCE_META. `metaData` carries the new horizon plus the version +
+   *  readSet the caller read, which the script keeps unless a newer computation
+   *  has since landed. */
+  advanceQueryCacheMetadata(cacheKey: string, metaData: QueryCacheMetadata, ttlSeconds?: number): Promise<void>;
+  getQueryCacheMetaData(cacheKey: string): Promise<QueryCacheMetadata | null>;
+  persistRegistrationRecord(subId: string, record: RegistrationRecord): Promise<void>;
+  deleteRegistrationRecord(subId: string): Promise<void>;
+  deleteRegistrationsRecord(subIds: string[]): Promise<void>;
+  fetchRegistrationRecordsBatch(subIds: string[]): Promise<Map<string, RegistrationRecord | null>>;
+  getCachedTableColumnTypes(key: string): Promise<CachedPgMetadata | null>;
+  setCachedTableColumnsTypes(key: string, value: CachedPgMetadata): Promise<void>;
+  /**
+   * Race participant: try to claim `lock:recompute:<subId>:<commitTs>`
+   * with `SET NX EX`. The single Redis round-trip both arbitrates and
+   * sets a TTL fallback in case the winner crashes mid-recompute.
+   */
+  tryAcquireRecomputeLock(instanceId: string, subId: string, commitTs: string, ttl: number): Promise<boolean>;
+  /** Raw value at an ephemeral key, or `null` when absent/expired. */
+  ephemeralGet(key: string): Promise<string | null>;
+  /** Raw values for `keys`, positionally aligned; `null` for each absent key. */
+  ephemeralGetMany(keys: string[]): Promise<(string | null)[]>;
+  private getRegistrationKey;
+  private getQueryCacheDataKey;
+  private getQeruyCacheMetaKey;
+}
+type IORedisClient = Redis;
+//#endregion
+//#region src/db/db.d.ts
+interface DbQueryResult<T = any> {
+  rows: T[];
+  rowCount?: number | null;
+  /**
+   * Auto-increment / LAST_INSERT_ID value from the driver, when applicable
+   * (MySQL `ResultSetHeader.insertId`). Used to read the advanced value back
+   * from `UPDATE ... SET id = LAST_INSERT_ID(id + 1)` without a second
+   * round-trip. Undefined for Postgres / SELECTs.
+   */
+  insertId?: number | bigint;
+}
+interface RawClient {
+  query<T = any>(sql: string, params?: unknown[]): Promise<DbQueryResult<T>>;
+}
+interface PooledClient extends RawClient {
+  release(): void;
+}
+type DbType = "postgres" | "mysql";
+interface PendingPointEntry {
+  entry: PointRead;
+  key: string;
+}
+interface PreparedQuery {
+  sql: string;
+  params: unknown[] | unknown[][];
+  operation: "insertSingle" | "insertBatch" | "updateSingle" | "updateBatch" | "deleteSingle" | "deleteBatch" | "pointReadValidation" | "commit_logs";
+  table: string;
+  entryId?: unknown;
+  expectedTs?: bigint;
+  entries?: WriteEntry[];
+  pendingsEntry?: PendingPointEntry[];
+}
+interface PreparedQueries {
+  commits: PreparedQuery[];
+  validateReadPoints?: PreparedQuery[];
+  hasRangeRead: boolean;
+  tableIds?: Uint8Array[];
+  rawReadSet?: RawReadEntry[];
+}
+/**
+ * Bound to a single dedicated connection that holds the core-init lock. Passed
+ * to the callback of {@link Database.withCoreInitLock} so version reads/writes
+ * and migration statements all run under the same lock.
+ */
+interface CoreInitLockCtx {
+  exec(sql: string, params?: unknown[]): Promise<DbQueryResult>;
+  getVersion(): Promise<bigint>;
+  setVersion(version: bigint): Promise<void>;
+}
+interface Database {
+  readonly dbType: DbType;
+  readonly sqlBuilder: SqlBuilder;
+  columnTypes: Map<string, Map<string, string>>;
+  /**
+   * Current core schema version stored in `metadata.core_version`, or `0n`
+   * when unset. Read on a pooled connection for the lock-free fast path of
+   * {@link initCore}.
+   */
+  getCoreVersion(): Promise<bigint>;
+  /**
+   * The app's current schema-migration marker, stored in
+   * `metadata.app_migration`, or `0n` when unset. This is the 14-digit
+   * timestamp of the last applied migration file (e.g. `20260726112333` for
+   * `0001_20260726112333.sql`), written by the deploy pipeline's tracked
+   * migrate step. Used to key the bootstrap column-type cache
+   * (`supalive:schema:types:<app_migration>`) so a schema change automatically
+   * invalidates cold instances' cached types — see `bootstrapDbTypes`.
+   */
+  getAppMigration(): Promise<bigint>;
+  /**
+   * Runtime bootstrap statements to apply when migrating core TO `toVersion`
+   * (i.e. the `toVersion - 1` → `toVersion` step): data seeds, backfills, or a
+   * schema change that must be applied directly at runtime. Dialect-specific;
+   * the core schema (tables, indexes, the `global_commit_ts` sequence/counter)
+   * lives in the generated schema instead — see `coreTablesSql`.
+   */
+  coreMigrationStatements(toVersion: bigint): string[];
+  /**
+   * Run `fn` while holding the cross-process core-init lock (PG
+   * `pg_advisory_xact_lock`, MySQL `GET_LOCK`) on a single dedicated
+   * connection, so concurrent servers can't race the core migration. All of
+   * `fn`'s work runs on that locked connection via {@link CoreInitLockCtx}.
+   */
+  withCoreInitLock(fn: (ctx: CoreInitLockCtx) => Promise<void>): Promise<void>;
+  bootstrapColumnTypes(opts: {
+    redis?: CacheLayer;
+    cacheKey: string;
+    tables?: string[];
+  }): Promise<void>;
+  query<T = any>(sql: string, params?: unknown[]): Promise<DbQueryResult<T>>;
+  getClient(): Promise<PooledClient>;
+  getTransactionClient(): Promise<TxDatabase>;
+  getLatestSnapshotTimestamp(): Promise<bigint>;
+  updateLatestSnapshotTimestamp(commitTs: bigint): Promise<void>;
+  /**
+   * The retention watermark: the boundary `ts` below which commit_logs have
+   * been pruned, so any cache entry whose `lastSnapshotTs` is below it can no
+   * longer be freshness-checked (its scan window would miss deleted rows) and
+   * must be recomputed. Persisted in the `metadata` table (survives restarts)
+   * as a cheap PK read — callers load it into an in-memory variable at startup
+   * and keep it fresh via pub/sub rather than reading it per query. Returns the
+   * -1n genesis when nothing has been pruned yet (matching the empty-DB snapshot
+   * ts), so every entry is scannable.
+   */
+  getMinSnapshotTimestamp(): Promise<bigint>;
+  /**
+   * Advance the retention watermark. Monotonic: only ever moves forward (a
+   * stale writer can never lower it). Called by the sub-manager right before it
+   * prunes commit_logs below `ts`.
+   */
+  updateMinSnapshotTimestamp(ts: bigint): Promise<void>;
+  getNextTimestamp(): Promise<bigint>;
+  prepareCommitWrites(readSet: ReadEntry[], writeSet: WriteEntry[], commitTs: LazyCommitTsParam): Promise<PreparedQueries>;
+  commitWrites(beginTs: bigint, queries: PreparedQueries, commitTs: bigint): Promise<{
+    success: boolean;
+  }>;
+  close(): Promise<void>;
+  /**
+   * Delete commit_logs older than `ts` (exclusive). Used by the periodic
+   * retention sweep in SubscriptionManager so the table doesn't grow
+   * unbounded.
+   */
+  pruneCommitLogsBefore(ts: bigint): Promise<bigint>;
+  /**
+   * Oldest `ts` still present in commit_logs (i.e. the retention watermark
+   * after the last prune), or `null` when the table is empty. A cache entry
+   * whose `lastSnapshotTs` is below it can no longer be freshness-checked via
+   * {@link getCommitLogsBetweenTs} (the logs it would need were pruned), so the
+   * one-shot/register cache paths recompute instead of trusting it.
+   */
+  getMinCommitLogTs(): Promise<bigint | null>;
+  /**
+   * Half-open range scan: ts >= beginTs AND ts < endTs. Used by the
+   * subscription-recovery path to replay logs in a specific time window.
+   */
+  getCommitLogsBetweenTs(beginTs: bigint, endTs: bigint, tableIds: Uint8Array[]): Promise<CommitLogEntry[]>;
+  /**
+   * Existence-only freshness probe for point reads: does any commit in the
+   * half-open window `[beginTs, endTs)` touch one of the exact `(tableId, id)`
+   * pairs in `points`? Returns as soon as one match is found.
+   *
+   * Point-read overlap is a pure key match (`checkPointReadOverlap`), so it can
+   * be answered entirely in SQL with a `(table_id, id)` tuple `IN` against the
+   * `commit_logs_by_table_and_id (table_id, id, ts)` index — no row `data`
+   * blobs fetched, no JSON parsed. This is the precise-filtering path used by
+   * {@link CacheFreshness} for tables whose read set is point-reads-only; tables
+   * that also carry a range read still go through {@link getCommitLogsBetweenTs}
+   * because their predicates must be evaluated in-app. `points` empty → `false`.
+   */
+  hasCommitForPoints(beginTs: bigint, endTs: bigint, points: {
+    tableId: Uint8Array;
+    id: Uint8Array;
+  }[]): Promise<boolean>;
+  /**
+   * Conflict-check scan for OCC: ts >= sinceTs AND ts <> excludeTs. The
+   * exclude is our own commitTs so we don't conflict with ourselves; the
+   * lack of an upper bound is intentional, so a concurrent peer that
+   * happens to have a higher commitTs but committed before us is still
+   * visible. (MVCC keeps in-flight peers invisible until they commit.)
+   */
+  getCommitLogsSinceTs(sinceTs: bigint, excludeTs: bigint, tableIds: Uint8Array[]): Promise<CommitLogEntry[]>;
+  /**
+   * For each `update`/`delete` entry, attach `prevData` (consumed by the
+   * invalidator) and `expectedCommitTs` (the CAS fence).
+   *
+   * `expectedCommitTs` is preferentially copied from a prior point-read of
+   * the same row in `readSet` — that's the value the handler's logic
+   * actually depended on, so the CAS check enforces beginTs-level isolation
+   * for read-then-update patterns. If no prior read exists ("blind"
+   * write), we fall back to the value observed in this batch fetch (weak
+   * OCC, sufficient for writes that don't depend on prior state).
+   *
+   * `prevData` always comes from this batch fetch (SELECT * per table) so
+   * the invalidator has the full row regardless of which columns the
+   * handler's read selected.
+   *
+   * If the target row no longer exists at fetch time, `expectedCommitTs`
+   * is left undefined and the per-row CAS will match nothing — surfaced
+   * as OccConflictError.
+   */
+  attachPrevDataToWriteSet(writeSet: WriteEntry[], readSet: ReadEntry[]): Promise<void>;
+}
+interface TxDatabase extends Database {
+  begin(): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  release(): void;
+}
+interface JsonOpOptions$1 {
+  /**
+   * When true, the bound `value` parameter is treated as already prepared
+   * for the underlying SQL (e.g. a literal JSON path string for
+   * jsonHasKey, a JSON-encoded literal for the contains family). When
+   * false/omitted, the value was prepared client-side from a JS value.
+   */
+  raw?: boolean;
+  /**
+   * 1-based positional index of an extra bound parameter holding a
+   * jsonpath that scopes the contains-family check to a sub-document of
+   * the target column. When omitted, the check runs against the whole
+   * column value.
+   */
+  pathIndex?: number;
+  /**
+   * jsonHasKey only: when set, multiple path parameters are bound starting
+   * at `paramIndex`, and the predicate evaluates whether any (`one`) or
+   * every (`all`) path exists in the column.
+   */
+  mode?: "one" | "all";
+  /** Number of bound path parameters in multi-path mode. */
+  pathCount?: number;
+}
+interface SqlBuilder {
+  placeholder(index: number): string;
+  like(col: string, paramIndex: number): string;
+  ilike(col: string, paramIndex: number): string;
+  icontains(col: string, paramIndex: number): string;
+  /** PG @> ; MySQL JSON_CONTAINS */
+  jsonContains(col: string, paramIndex: number, opts?: JsonOpOptions$1): string;
+  /** PG <@ ; MySQL JSON_CONTAINS(candidate, target) */
+  jsonContainedBy(col: string, paramIndex: number, opts?: JsonOpOptions$1): string;
+  /**
+   * Key/path existence. With `opts.raw === true`, the bound param is a JSON
+   * path expression (PG `jsonb_path_exists`, MySQL `JSON_CONTAINS_PATH`).
+   * Otherwise the bound param is a literal top-level key (PG `?`, MySQL
+   * `JSON_CONTAINS_PATH($."<key>")` with server-side quoting).
+   * With `opts.pathCount` set, emits the multi-path form keyed by `mode`.
+   */
+  jsonHasKey(col: string, paramIndex: number, opts?: JsonOpOptions$1): string;
+  /** Array membership: target array contains the given element. */
+  jsonArrayContains(col: string, paramIndex: number, opts?: JsonOpOptions$1): string;
+}
+declare class LazyCommitTsParam {
+  value: unknown;
+  constructor(value: unknown);
+  toPostgres(prepareValue: (value: any) => any): any;
+  toString(): any;
+  validate(): void;
+}
+//#endregion
+//#region src/db/table-id.d.ts
+/**
+ * Canonical table identifier: a fixed **16-byte** digest of the table name
+ * (UUID v3, which is MD5-based). A `tableId` is fully derived from the table
+ * name, so it is never stored redundantly — the query-cache `readSet` persists
+ * only `table` (the name) and reconstructs the bytes on read via
+ * {@link tableIdOf}. The physical `commit_logs.table_id` column (MySQL
+ * `BINARY(16)`, Postgres `BYTEA`) and its indexes hold these same bytes.
+ *
+ * A fixed 16 bytes (rather than the raw UTF-8 of the name) is required for
+ * MySQL: `BINARY(16)` would overflow on a table name longer than 16 bytes and
+ * zero-pad shorter ones (breaking byte-exact id matching). MD5 sidesteps both.
+ * Only used for equality (never decoded back to a name), so a non-cryptographic
+ * digest is fine. Browser-safe and synchronous (via the `uuid` package), which
+ * matters because this module is reachable from the client bundle.
+ */
+declare function tableNameToId(tableName: string): Uint8Array;
+//#endregion
+//#region src/db/schema.d.ts
+interface ColumnCodec<TData = unknown, TDriver = unknown> {
+  encode?: (value: TData) => TDriver;
+  decode?: (value: TDriver) => TData;
+}
+type SchemaCodecField<TSchema extends ZodRawShape, K extends PropertyKey> = K extends keyof TSchema ? TSchema[K] extends z$1.ZodTypeAny ? z$1.infer<TSchema[K]> : unknown : K extends keyof BaseSchema ? BaseSchema[K] extends z$1.ZodTypeAny ? z$1.infer<BaseSchema[K]> : unknown : unknown;
+type SchemaCodecs<TSchema extends ZodRawShape> = Partial<{ [K in keyof (TSchema & BaseSchema)]: ColumnCodec<SchemaCodecField<TSchema, K>, any> }>;
+interface SchemaColumnsOptions<TSchema extends ZodRawShape = ZodRawShape> {
+  codecs?: SchemaCodecs<TSchema>;
+}
+interface SchemaColumnMapping {
+  [key: string]: string;
+}
+interface DeclarativeIndex {
+  name: string;
+  columns: string[];
+  unique?: boolean;
+  type?: "btree" | "hash" | "gin" | "gist" | "spgist" | "brin";
+  where?: string;
+  using?: string;
+  options?: string;
+  tablespace?: string;
+}
+type IndexDefinition = string | DeclarativeIndex;
+interface DefineSchemaConfig<TSchema extends ZodRawShape> {
+  name: string;
+  schema: TSchema;
+  options?: SchemaColumnsOptions<TSchema>;
+  columns?: SchemaColumnMapping;
+  indexes?: IndexDefinition[];
+}
+type CodecDataType<TCodec, TFallback> = [TCodec] extends [undefined] ? TFallback : TCodec extends {
+  decode: (...args: any[]) => infer TDecoded;
+} ? TDecoded : TCodec extends ColumnCodec<infer TData, unknown> ? TData : TFallback;
+type ZodOutput<TZod> = [TZod] extends [undefined] ? unknown : TZod extends z$1.ZodTypeAny ? z$1.infer<TZod> : unknown;
+type ComputedDataType<TCodec, TZod> = CodecDataType<TCodec, ZodOutput<TZod>>;
+type ComputedCodec<TData, TDriver> = ColumnCodec<TData, TDriver>;
+type OverrideField<TObj, TKey extends PropertyKey, TValue> = Omit<TObj, TKey> & { [K in TKey]: TValue };
+interface ComputedFieldConfig<TField extends string, TDecoded = unknown, TDriver = unknown, TZodType extends z$1.ZodTypeAny | undefined = undefined> {
+  field: TField;
+  sql: string;
+  alias?: string;
+  type?: TZodType;
+  codec?: {
+    decode: (value: TDriver) => TDecoded;
+    encode?: (value: TDecoded) => TDriver;
+  };
+}
+type ComputedField = {
+  field: string;
+  sql: string;
+  alias: string;
+  codec?: ColumnCodec<any, any>;
+};
+declare function defineComputedField<TField extends string, TDecoded = unknown, TDriver = unknown, TZodType extends z$1.ZodTypeAny | undefined = undefined>(config: ComputedFieldConfig<TField, TDecoded, TDriver, TZodType>): ComputedFieldConfig<TField, TDecoded, TDriver, TZodType>;
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type ApplySchemaCodecs<TBase, TCodecs> = { [K in keyof TBase]: K extends keyof TCodecs ? CodecDataType<TCodecs[K], TBase[K]> : TBase[K] };
+type ResolveSchemaType<TSchema extends ZodRawShape, TOptions extends SchemaColumnsOptions<TSchema>> = TOptions extends {
+  codecs: infer TCodecs;
+} ? Prettify<ApplySchemaCodecs<z$1.infer<z$1.ZodObject<TSchema & BaseSchema>>, TCodecs>> : Prettify<z$1.infer<z$1.ZodObject<TSchema & BaseSchema>>>;
+type IsOptionalField<T> = T extends z$1.ZodOptional<any> ? true : T extends z$1.ZodNullable<any> ? true : T extends z$1.ZodDefault<any> ? true : false;
+type OptionalKeys<TZod extends ZodRawShape> = { [K in keyof TZod]: IsOptionalField<TZod[K]> extends true ? K : never }[keyof TZod];
+type RequiredKeys<TZod extends ZodRawShape> = { [K in keyof TZod]: IsOptionalField<TZod[K]> extends true ? never : K }[keyof TZod];
+type BaseSchema = {
+  id: z$1.ZodString;
+  commitTs: z$1.ZodCoercedBigInt;
+};
+declare const schemaRegistry: Map<string, SchemaDefinition<string, any, any>>;
+declare const shouldTrackSchema: boolean;
+declare function defineSchema<TSchema extends ZodRawShape, TName extends string, TOptions extends SchemaColumnsOptions<TSchema> = SchemaColumnsOptions<TSchema>>(config: DefineSchemaConfig<TSchema> & {
+  name: TName;
+  options?: TOptions;
+}): SchemaDefinition<TName, Prettify<TSchema & BaseSchema>, ResolveSchemaType<TSchema, TOptions>>;
+interface StoredSchemaColumnsOptions {
+  codecs?: Record<string, ColumnCodec<any, any>>;
+}
+interface SchemaDefinition<TTable extends string, TZod extends ZodRawShape, TData = z$1.infer<z$1.ZodObject<TZod>>> {
+  tableId: Uint8Array;
+  table: TTable;
+  schema: z$1.ZodObject<TZod>;
+  columnsOptions: StoredSchemaColumnsOptions;
+  columns: Record<string, string>;
+  indexes: IndexDefinition[];
+  _dataType?: TData;
+}
+type InferSchema<T extends SchemaDefinition<string, ZodRawShape, any>> = T extends SchemaDefinition<string, ZodRawShape, infer TData> ? TData : never;
+type InsertData<T extends SchemaDefinition<string, ZodRawShape, any>> = T extends SchemaDefinition<string, infer TZod, infer TData> ? { [K in RequiredKeys<TZod> as K extends "id" | "commitTs" ? never : K]: Extract<K, string> extends keyof TData ? TData[Extract<K, string>] : never } & { [K in OptionalKeys<TZod> as K extends "id" | "commitTs" ? never : K]?: Extract<K, string> extends keyof TData ? TData[Extract<K, string>] : never } : never;
+interface Model {
+  table: string;
+  tableId: Uint8Array;
+  columns: Record<string, string>;
+  reverseColumns: Record<string, string>;
+  types: Record<string, string>;
+  codecs: Record<string, ColumnCodec<any, any>>;
+}
+type MaybePromise<T> = T | Promise<T>;
+type ReturnLiveQuery<TLiveQueryFn extends (...args: any[]) => MaybePromise<LiveQueryHandle<any>>> = Awaited<ReturnType<TLiveQueryFn>> extends LiveQueryHandle<infer T> ? T : never;
+type ReturnQuery<TQueryFn extends (...args: any[]) => any> = Awaited<ReturnType<TQueryFn>>;
+type QueryArgs<TQueryFn extends (...args: any[]) => any> = Parameters<TQueryFn>[0];
+type MutationArgs<TMutationFn extends (...args: any[]) => any> = Parameters<TMutationFn>[0];
+type ActionArgs<TActionFn extends (...args: any[]) => any> = Parameters<TActionFn>[0];
+//#endregion
+//#region src/db/query.d.ts
+type FieldValue<S extends SchemaDefinition<string, ZodRawShape>, K> = K extends keyof InferSchema<S> ? InferSchema<S>[K] : never;
+type OrderableValue = number | bigint | string | Date;
+type StringFieldKeys<S extends SchemaDefinition<string, ZodRawShape>> = { [K in keyof InferSchema<S>]: NonNullable<InferSchema<S>[K]> extends string ? K : never }[keyof InferSchema<S>];
+type OrderableFieldKeys<S extends SchemaDefinition<string, ZodRawShape>> = { [K in keyof InferSchema<S>]: NonNullable<InferSchema<S>[K]> extends OrderableValue ? K : never }[keyof InferSchema<S>];
+type JsonFieldKeys<S extends SchemaDefinition<string, ZodRawShape>> = { [K in keyof InferSchema<S>]: NonNullable<InferSchema<S>[K]> extends OrderableValue ? never : NonNullable<InferSchema<S>[K]> extends boolean ? never : NonNullable<InferSchema<S>[K]> extends (object | unknown[]) ? K : unknown extends NonNullable<InferSchema<S>[K]> ? K : never }[keyof InferSchema<S>];
+interface JsonOpOptions {
+  /**
+   * Skip client-side preparation of the value (no JSON-stringify, no key
+   * escaping). The caller is responsible for the exact form the dialect
+   * expects: a JSON path string for jsonHasKey, a JSON-encoded string for
+   * the contains family.
+   */
+  raw?: true;
+}
+interface JsonContainsOptions extends JsonOpOptions {
+  /**
+   * Sub-path into the target JSON to scope the check to. `string` is a
+   * single literal top-level key; `string[]` is a nested literal-key path
+   * compiled to `$."a"."b"`. Mutually exclusive with `pathRaw`.
+   */
+  path?: string | string[];
+  /**
+   * Raw jsonpath expression used verbatim by the dialect (PG `jsonpath`,
+   * MySQL JSON path). Mutually exclusive with `path`.
+   */
+  pathRaw?: string;
+}
+interface JsonHasKeyMultiOptions extends JsonOpOptions {
+  /** Required for the multi-path overload — chooses any vs every. */
+  mode: "one" | "all";
+}
+declare class QueryBuilder<S extends SchemaDefinition<string, ZodRawShape>> {
+  protected ctx: TxContext;
+  protected model: Model;
+  constructor(ctx: TxContext, model: Model);
+  protected getColumnName(key: string): string;
+  select(): SelectQueryBuilder<S, keyof InferSchema<S>>;
+  select<K extends keyof InferSchema<S>>(...columns: K[]): SelectQueryBuilder<S, K>;
+}
+type IdAndCommitTs = {
+  id: string;
+  commitTs: bigint;
+};
+type SelectRow<S extends SchemaDefinition<string, ZodRawShape>, K extends keyof InferSchema<S>, C extends Record<string, unknown>> = Prettify<Pick<InferSchema<S>, Extract<K | "id" | "commitTs", keyof InferSchema<S>>> & C>;
+type OrderDirection = "ASC" | "DESC";
+interface OrderByOptions {
+  direction?: OrderDirection;
+  nulls?: "first" | "last";
+  collate?: string;
+}
+/**
+ * Cursor-based pagination using a timestamp column and a unique ID column.
+ *
+ * Generates a stable cursor predicate:
+ *
+ * DESC (default):
+ * ```sql
+ * WHERE (timeCol < ? OR (timeCol = ? AND idCol < ?))
+ * ORDER BY timeCol DESC, idCol DESC
+ * ```
+ *
+ * ASC:
+ * ```sql
+ * WHERE (timeCol > ? OR (timeCol = ? AND idCol > ?))
+ * ORDER BY timeCol ASC, idCol ASC
+ * ```
+ */
+interface PaginationClause<S extends SchemaDefinition<string, ZodRawShape>, Time extends OrderableFieldKeys<S>, Id extends OrderableFieldKeys<S>> {
+  /** Timestamp column used for cursor pagination. */
+  timeCol: Time;
+  /**
+   * Unique tie-breaker column.
+   *
+   * @default "id"
+   */
+  idCol?: Id;
+  /**
+   * Pagination direction.
+   *
+   * - `"desc"` (default): Newest → oldest.
+   * - `"asc"`: Oldest → newest.
+   *
+   * @default "desc"
+   */
+  direction?: OrderDirection;
+  /**
+   * Maximum number of rows to return.
+   */
+  limit?: number;
+  /**
+   * Cursor returned from the previous page.
+   *
+   * Omit or set to `null` to fetch the first page.
+   */
+  cursor?: {
+    time: FieldValue<S, Time>;
+    id: FieldValue<S, Id>;
+  } | null;
+}
+declare class SelectQueryBuilder<S extends SchemaDefinition<string, ZodRawShape>, K extends keyof InferSchema<S> = never, C extends Record<string, unknown> = {}> {
+  private ctx;
+  private model;
+  private filters;
+  private paginationClause;
+  private orderByClause;
+  private limitVal;
+  private offsetVal;
+  private selectedProps;
+  private computedFields;
+  private commentStr;
+  constructor(ctx: TxContext, model: Model, filters?: ((fb: FilterBuilder<S>) => void)[], orderByClause?: string[] | null, limitVal?: number | null, offsetVal?: number | null, selectedProps?: (keyof InferSchema<S>)[], computedFields?: ComputedField[], commentStr?: string);
+  private getColumnName;
+  private getPropertyName;
+  private mapRowToSchema;
+  where(filterFn: (fb: FilterBuilder<S>) => void): SelectQueryBuilder<S, K, C>;
+  paginate<Time extends OrderableFieldKeys<S>, Id extends OrderableFieldKeys<S>>(clause: PaginationClause<S, Time, Id>): SelectQueryBuilder<S, K, C>;
+  orderBy(column: keyof InferSchema<S> | keyof C, direction?: OrderDirection): SelectQueryBuilder<S, K, C>;
+  orderBy(column: keyof InferSchema<S> | keyof C, options?: OrderByOptions): SelectQueryBuilder<S, K, C>;
+  private buildOrderBySql;
+  orderByRaw(sql: string): SelectQueryBuilder<S, K, C>;
+  limit(n: number): SelectQueryBuilder<S, K, C>;
+  offset(n: number): SelectQueryBuilder<S, K, C>;
+  computed<TField extends string, TZodType extends z$1.ZodTypeAny | undefined = undefined, TDecode extends (value: any) => any = (value: unknown) => unknown>(config: ComputedFieldConfig<TField, ReturnType<TDecode>, Parameters<TDecode>[0], TZodType> & {
+    codec: {
+      decode: TDecode;
+      encode?: (value: ReturnType<TDecode>) => Parameters<TDecode>[0];
+    };
+  }): SelectQueryBuilder<S, K | TField, OverrideField<C, TField, ComputedDataType<ComputedCodec<ReturnType<TDecode>, Parameters<TDecode>[0]>, TZodType>>>;
+  computed<TField extends string, TZodType extends z$1.ZodTypeAny | undefined = undefined>(config: ComputedFieldConfig<TField, unknown, unknown, TZodType> & {
+    codec?: undefined;
+  }): SelectQueryBuilder<S, K | TField, OverrideField<C, TField, ComputedDataType<undefined, TZodType>>>;
+  comment(input: string | Record<string, string>): SelectQueryBuilder<S, K, C>;
+  first(): Promise<SelectRow<S, K, C> | null>;
+  exists(): Promise<boolean>;
+  private static defaultCountType;
+  count(): Promise<number>;
+  count<T extends z$1.ZodType>(parser: T): Promise<z$1.output<T>>;
+  find(id: string): Promise<SelectRow<S, K, C> | null>;
+  get(): Promise<SelectRow<S, K, C>[]>;
+  private buildPredicate;
+}
+declare class FilterBuilder<S extends SchemaDefinition<string, ZodRawShape>> {
+  private columns;
+  private codecs;
+  predicates: Predicate[];
+  constructor(columns: Record<string, string>, codecs: Record<string, ColumnCodec<unknown, unknown>>);
+  private add;
+  private addJsonContains;
+  private getColumnName;
+  private encode;
+  private encodeJson;
+  eq<K extends keyof InferSchema<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  neq<K extends keyof InferSchema<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  gt<K extends OrderableFieldKeys<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  gte<K extends OrderableFieldKeys<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  lt<K extends OrderableFieldKeys<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  lte<K extends OrderableFieldKeys<S>>(key: K, value: FieldValue<S, K>): FilterBuilder<S>;
+  like<K extends StringFieldKeys<S>>(key: K, pattern: string): FilterBuilder<S>;
+  ilike<K extends StringFieldKeys<S>>(key: K, pattern: string): FilterBuilder<S>;
+  contains<K extends StringFieldKeys<S>>(key: K, value: string): FilterBuilder<S>;
+  icontains<K extends StringFieldKeys<S>>(key: K, value: string): FilterBuilder<S>;
+  /**
+   * JSON containment. Targets a JSON/JSONB column and asserts the document
+   * contains the given candidate (object-key subset for objects,
+   * element-subset for arrays — see dialect-specific docs for edge cases).
+   * Pass `{ raw: true }` if `value` is already a JSON-encoded string.
+   * Pass `{ path: ... }` to scope the check to a sub-document of the
+   * target (jsonb_path_query_first on PG, JSON_CONTAINS path arg on MySQL).
+   */
+  jsonContains<K extends JsonFieldKeys<S>>(key: K, value: unknown, opts?: JsonContainsOptions): FilterBuilder<S>;
+  /** Inverse of {@link jsonContains}: column is contained in the given value. */
+  jsonContainedBy<K extends JsonFieldKeys<S>>(key: K, value: unknown, opts?: JsonContainsOptions): FilterBuilder<S>;
+  /**
+   * Key/path existence check on a JSON column.
+   *
+   * - String form (top-level key): `jsonHasKey("meta", "color")`. On PG
+   *   also matches when the column is a string array and `value` is one of
+   *   its elements (PG `?` semantics); MySQL stays strict to object keys.
+   * - Array form (nested path): `jsonHasKey("meta", ["a", "b"])` compiles
+   *   to a path expression `$."a"."b"` on both dialects.
+   * - Raw form: `jsonHasKey("meta", "$.foo[*]", { raw: true })` passes the
+   *   string through as a dialect path expression (PG `jsonb_path_exists`
+   *   jsonpath, MySQL `JSON_CONTAINS_PATH`). Caller owns the syntax.
+   * - Multi-path form: `jsonHasKey("meta", [["a","b"], "color"], { mode: "all" })`
+   *   compiles each entry to a jsonpath and emits PG OR/AND of
+   *   `jsonb_path_exists` or MySQL `JSON_CONTAINS_PATH('all', ...)`.
+   */
+  jsonHasKey<K extends JsonFieldKeys<S>>(key: K, value: string): FilterBuilder<S>;
+  jsonHasKey<K extends JsonFieldKeys<S>>(key: K, value: string[]): FilterBuilder<S>;
+  jsonHasKey<K extends JsonFieldKeys<S>>(key: K, value: string, opts: {
+    raw: true;
+  }): FilterBuilder<S>;
+  jsonHasKey<K extends JsonFieldKeys<S>>(key: K, paths: (string | string[])[], opts: JsonHasKeyMultiOptions): FilterBuilder<S>;
+  jsonHasKey<K extends JsonFieldKeys<S>>(key: K, paths: string[], opts: JsonHasKeyMultiOptions & {
+    raw: true;
+  }): FilterBuilder<S>;
+  /**
+   * Array element containment: target column is a JSON array; the given
+   * `value` (any JSON-encodable type) must appear as one of its elements.
+   * Pass `{ raw: true }` if `value` is already a JSON-encoded string.
+   * Pass `{ path: ... }` to scope the check to a sub-array of the column.
+   */
+  jsonArrayContains<K extends JsonFieldKeys<S>>(key: K, value: unknown, opts?: JsonContainsOptions): FilterBuilder<S>;
+  between<K extends OrderableFieldKeys<S>>(key: K, lo: FieldValue<S, K>, hi: FieldValue<S, K>): FilterBuilder<S>;
+  /**
+   * Set membership: `key` equals any of `values` (SQL `IN`). Each value is
+   * codec-encoded like `eq`. An empty `values` matches no rows. Bound as one
+   * parameter per element, so keep the list within the driver's parameter
+   * limit (chunk very large sets at the call site).
+   */
+  in<K extends keyof InferSchema<S>>(key: K, values: readonly FieldValue<S, K>[]): FilterBuilder<S>;
+  isNull<K extends keyof InferSchema<S>>(key: K): FilterBuilder<S>;
+  notNull<K extends keyof InferSchema<S>>(key: K): FilterBuilder<S>;
+  /**
+   * Compose an OR clause. Each callback fills a fresh sub-FilterBuilder
+   * with predicates that are AND-ed together within that branch; the
+   * branches themselves are OR-ed. Example:
+   *   f.or([
+   *     b => b.eq("tag", "a"),
+   *     b => b.eq("tag", "b").gt("qty", 3),  // (tag=b AND qty>3)
+   *   ])
+   * produces  (tag=a) OR (tag=b AND qty>3).
+   */
+  or(branches: ((fb: FilterBuilder<S>) => void)[]): FilterBuilder<S>;
+}
+declare function buildPredicateSql(predicate: Predicate, params: unknown[], sql: SqlBuilder): string;
+declare function matchesPredicate(row: Record<string, unknown>, predicate: Predicate): boolean;
+declare function jsonContains(target: unknown, candidate: unknown): boolean;
+declare function jsonPathExtract(val: unknown, path: string): unknown;
+declare function jsonPathExists(val: unknown, path: string): boolean;
+//#endregion
+//#region src/db/ephemeral.d.ts
+/**
+ * Default lifetime of an ephemeral entry: 7 days. Long enough that a value set
+ * once (a device's last known position, a presence flag) survives normal
+ * operation, short enough that abandoned keys eventually drain out of Redis on
+ * their own. Override per call via {@link EphemeralSetOptions.ttlSeconds}.
+ */
+declare const EPHEMERAL_DEFAULT_TTL_SECONDS: number;
+/**
+ * Shared stand-in for "this computation read no ephemeral state" — the
+ * overwhelmingly common case. Frozen and reused so neither a `TxContext` nor a
+ * `LiveResult` allocates an array for a query that never touches the store.
+ */
+declare const EMPTY_EPHEMERAL_KEYS: string[];
+/** Thrown by {@link EphemeralReader.get} when the key holds no value. */
+declare class EphemeralKeyNotFoundError extends Error {
+  readonly key: string;
+  constructor(key: string);
+}
+/**
+ * Thrown when a stored value does not match the schema the reader asked for —
+ * corrupt bytes, or (far more likely) a value written by an older deploy under
+ * a shape that has since changed.
+ *
+ * This is a hard error rather than a silent `null` because the two are not the
+ * same thing: `null` means "nothing is here", and quietly conflating a schema
+ * mismatch with absence turns a deploy bug into a blank screen. A caller that
+ * genuinely wants tolerance can express it in the schema itself — `.catch()`,
+ * `.optional()`, or a union — which is strictly more expressive than anything
+ * this layer could decide on its behalf.
+ */
+declare class EphemeralDecodeError extends Error {
+  readonly key: string;
+  constructor(key: string, options?: {
+    cause?: unknown;
+  });
+}
+interface EphemeralSetOptions {
+  /**
+   * Lifetime in seconds. Defaults to {@link EPHEMERAL_DEFAULT_TTL_SECONDS}
+   * (7 days), or to the server-configured default.
+   *
+   * Expiry is silent: when the TTL elapses the value simply disappears and the
+   * next recompute of a subscribed query observes `null`. It does NOT by itself
+   * push an update — call {@link EphemeralWriter.delete} when subscribers need
+   * to see the value go away at a specific moment.
+   */
+  ttlSeconds?: number;
+}
+/**
+ * Read side of the ephemeral store.
+ *
+ * Reached from a query/mutation handler as `ctx.db.ephemeral`, where every read
+ * also records a live-query dependency on the key, and from an action/job as
+ * `ctx.db.ephemeral` on the {@link SupaliveDb} itself (untracked — an action has
+ * no read set).
+ *
+ * Every read takes the Zod schema its value should satisfy. Ephemeral state is
+ * schemaless in Redis — no table, no column types, and its writer may be a
+ * different deploy of your own code — so a `as T` cast here would be a type
+ * that is checked nowhere and true only by convention. Passing the schema makes
+ * the boundary an actual parse.
+ *
+ * The naming mirrors the SQL query builder: {@link find} returns `null` for a
+ * missing key exactly like `query(Schema).find(id)` does, {@link get} is the
+ * "I know it's there" variant that throws, and {@link getOr} supplies a default.
+ */
+interface EphemeralReader {
+  /** Value for `key`, or `null` when it is absent or expired. */
+  find<T>(key: string, schema: ZodType<T>): Promise<T | null>;
+  /** Value for `key`. Throws {@link EphemeralKeyNotFoundError} when absent. */
+  get<T>(key: string, schema: ZodType<T>): Promise<T>;
+  /** Value for `key`, or `fallback` when it is absent or expired. */
+  getOr<T>(key: string, schema: ZodType<T>, fallback: T): Promise<T>;
+  /** Values for `keys`, positionally aligned; `null` for each absent key. */
+  findMany<T>(keys: string[], schema: ZodType<T>): Promise<(T | null)[]>;
+  /** Whether `key` currently holds a value. Does not decode it, so it needs no
+   *  schema — and a value that fails to parse still counts as present. */
+  has(key: string): Promise<boolean>;
+}
+/** Read side plus writes. See {@link EphemeralReader} for the read semantics. */
+interface EphemeralWriter extends EphemeralReader {
+  /** Store `value` under `key`, replacing any existing entry. */
+  set<T>(key: string, value: T, opts?: EphemeralSetOptions): Promise<void>;
+  /** Remove `key`. Invalidates subscribers just like a `set` does. */
+  delete(key: string): Promise<void>;
+}
+/** A single pending write in a `DbWriter`'s buffer. `ttlSeconds: 0` = delete. */
+interface PendingEphemeralWrite {
+  key: string;
+  /** Pre-serialized payload; empty string for a delete. */
+  value: string;
+  ttlSeconds: number;
+}
+/**
+ * Redis-backed store for state that drives live queries but is never persisted
+ * to the database — a device's latest GPS fix, a "typing…" flag, a transient
+ * job progress percentage.
+ *
+ * Unlike a table row, an ephemeral key has no commit log and no snapshot ts, so
+ * it cannot participate in the OCC read set or the commit-log freshness replay.
+ * Instead a query records the plain key strings it read
+ * (`LiveResult.ephemeralKeys`), the sub-manager indexes subscriptions by those
+ * keys, and a write looks subscribers up by exact key match — cheaper than the
+ * write-set scan, because there is no predicate to evaluate.
+ */
+declare class EphemeralStore implements EphemeralWriter {
+  private readonly cache;
+  private readonly defaultTtlSeconds;
+  /**
+   * Fired after a batch of writes lands in Redis, with the affected keys and the
+   * newly allocated global version. The server wires this to the sub-manager's
+   * ephemeral invalidation, mirroring how `SupaliveDb.setOnAfterCommit` drives
+   * write-set invalidation. Left unset outside a server (tests, tooling), where
+   * writes are then purely local.
+   */
+  onAfterWrite?: (keys: string[], version: string) => void;
+  constructor(cache: CacheLayer, opts?: {
+    defaultTtlSeconds?: number;
+  });
+  /** The TTL a `set` without an explicit `ttlSeconds` uses. */
+  get defaultTtl(): number;
+  find<T>(key: string, schema: ZodType<T>): Promise<T | null>;
+  get<T>(key: string, schema: ZodType<T>): Promise<T>;
+  getOr<T>(key: string, schema: ZodType<T>, fallback: T): Promise<T>;
+  findMany<T>(keys: string[], schema: ZodType<T>): Promise<(T | null)[]>;
+  has(key: string): Promise<boolean>;
+  set<T>(key: string, value: T, opts?: EphemeralSetOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  /**
+   * Serialize a `set` into a buffered write WITHOUT touching Redis. Used by
+   * `DbWriter`, which defers ephemeral writes until its transaction commits.
+   */
+  prepareSet<T>(key: string, value: T, opts?: EphemeralSetOptions): PendingEphemeralWrite;
+  /** The `delete` counterpart of {@link prepareSet}. */
+  prepareDelete(key: string): PendingEphemeralWrite;
+  /**
+   * Apply buffered writes atomically, then notify the invalidation hook. The
+   * hook runs only after Redis holds the new values, so any recompute it
+   * triggers is guaranteed to read them.
+   */
+  apply(writes: PendingEphemeralWrite[]): Promise<void>;
+}
+/**
+ * An {@link EphemeralStore} backed by a plain Map instead of Redis — for unit
+ * tests and tooling that construct a `SupaliveDb` without a cache layer.
+ *
+ * It is process-local, so it is NOT a substitute for the real store in any
+ * multi-instance deployment: two servers would each see their own values, and
+ * cross-instance invalidation would push stale data. TTLs are honoured on read
+ * (there is no background expiry), which is enough for the semantics tests care
+ * about.
+ */
+declare function createMemoryEphemeralStore(opts?: {
+  defaultTtlSeconds?: number;
+}): EphemeralStore;
+//#endregion
+//#region src/db/context.d.ts
+declare class TxContext {
+  beginTs: bigint;
+  db: Database;
+  protected readSet: ReadEntry[];
+  protected writeSet: WriteEntry[];
+  /**
+   * Ephemeral keys read by this context, in first-read order and de-duplicated.
+   * Kept separate from {@link readSet} on purpose: an ephemeral key has no
+   * snapshot ts and no commit log, so letting it into the read set would feed
+   * the OCC validator and the commit-log freshness scan a dependency neither
+   * can reason about.
+   *
+   * `null` until the first ephemeral read. The vast majority of queries never
+   * touch the store, and this context is constructed once per query execution —
+   * so the array is allocated on demand rather than on every read path.
+   */
+  protected ephemeralKeys: string[] | null;
+  /** `set`/`delete` calls awaiting a commit — see {@link DbWriter.ephemeral}.
+   *  Lazily allocated, like {@link ephemeralKeys}. */
+  protected ephemeralWrites: PendingEphemeralWrite[] | null;
+  /** Backing store for `ctx.db.ephemeral`. */
+  protected readonly ephemeralStore: EphemeralStore;
+  private models;
+  protected getOrCreateModel(schema: SchemaDefinition<string, ZodRawShape>): Model;
+  constructor(db: Database, beginTs: bigint, ephemeralStore: EphemeralStore);
+  /**
+   * Record a live-query dependency on `key` (idempotent within a context).
+   * @internal — called by the wrappers in db/ephemeral.ts.
+   */
+  internalTrackEphemeralRead(key: string): void;
+  /**
+   * Queue an ephemeral write for the post-commit flush, replacing any earlier
+   * write to the same key so the last write in an attempt wins.
+   * @internal — called by the wrapper in db/ephemeral.ts.
+   */
+  internalBufferEphemeralWrite(write: PendingEphemeralWrite): void;
+  /**
+   * Rebind the read connection (and its snapshot ts). Used by the replica
+   * router when a query handler calls `ctx.usePrimaryConn()`/`useReplicaConn()`.
+   * Must be called BEFORE any read — the readSet/beginTs would otherwise mix
+   * snapshots — so this throws if a read or write has already happened.
+   */
+  useConnection(db: Database, beginTs: bigint): void;
+  internalGetReadSet(): ReadEntry[];
+  internalGetWriteSet(): WriteEntry[];
+  /** Null when this context read no ephemeral state — see {@link ephemeralKeys}. */
+  internalGetEphemeralKeys(): string[] | null;
+  /** Null when this context buffered no ephemeral writes. */
+  internalGetEphemeralWrites(): PendingEphemeralWrite[] | null;
+  /**
+   * Merge a parent procedure's reads into this context's readSet. Used when a
+   * `runMutation` sub-transaction inherits the reads of the procedure that
+   * invoked it, so the sub-tx's OCC validation also fences on those rows.
+   * Entries are shallow-cloned so the two readSets don't alias.
+   */
+  appendInternalReadSet(parentEntries: ReadEntry[]): void;
+  /**
+   * Merge ephemeral dependencies recorded elsewhere into this context. The
+   * counterpart of {@link appendInternalReadSet}: used when a nested query is
+   * served from cache, so the parent still depends on the keys the cached
+   * computation read and re-runs when any of them change.
+   */
+  appendInternalEphemeralKeys(keys: string[]): void;
+  protected findPendingWrite(table: string, id: string): WriteEntry | undefined;
+  protected findPendingInsert(table: string, id: string): WriteEntry | undefined;
+  protected encodeWithCodec(model: Model, property: string, value: unknown): unknown;
+}
+declare class DbReader extends TxContext {
+  private ephemeralApi?;
+  query<S extends SchemaDefinition<string, ZodRawShape>>(schema: S): QueryBuilder<S>;
+  /**
+   * Read ephemeral state — values that drive live queries but are never stored
+   * in the database (a device's latest GPS fix, a presence flag).
+   *
+   * Every read here records a dependency on the key, so a subscribed query
+   * re-runs and pushes automatically when an action or mutation writes it. The
+   * dependency is on the KEY, not the value: reading a key that is currently
+   * absent still subscribes you to it being set later.
+   *
+   * Built on first access — a query that never reaches for ephemeral state
+   * allocates neither the wrapper nor its key list.
+   */
+  get ephemeral(): EphemeralReader;
+}
+declare class DbWriter extends DbReader {
+  private ephemeralWriteApi?;
+  /**
+   * Read AND write ephemeral state. Reads behave exactly as on a
+   * {@link DbReader}; writes are BUFFERED and applied only once the surrounding
+   * mutation commits (see `SupaliveDb.mutation` and
+   * {@link createBufferedEphemeralWriter} for why).
+   */
+  get ephemeral(): EphemeralWriter;
+  insert<S extends SchemaDefinition<string, ZodRawShape>, ID extends string>(schema: S, id: ID, data: InsertData<S>): Promise<void>;
+  update<S extends SchemaDefinition<string, ZodRawShape>, ID extends string>(schema: S, id: ID, data: Partial<Omit<InferSchema<S>, "id" | "commitTs">>): Promise<void>;
+  delete<S extends SchemaDefinition<string, ZodRawShape>, ID extends string>(schema: S, id: ID): Promise<void>;
+}
+//#endregion
+//#region src/db/query_definition.d.ts
+/**
+ * A named, typed query definition produced by defineQuery().
+ * Carries the query function at runtime and the name/params/result types
+ * at compile time — making it the single source of truth for both the
+ * server-side registry and the client-side RPC.
+ */
+interface QueryDefinition<TName extends string, TParams, TResult> {
+  readonly _type: "QueryDefinition";
+  readonly name: TName;
+  readonly fn: (ctx: DbReader, params: TParams) => Promise<TResult>;
+}
+type AnyQueryDef = QueryDefinition<string, any, any>;
+/** Extract the params type from a QueryDefinition. */
+type ParamsOf<D extends AnyQueryDef> = D extends QueryDefinition<any, infer P, any> ? P : never;
+/** Extract the result type from a QueryDefinition. */
+type ResultOf<D extends AnyQueryDef> = D extends QueryDefinition<any, any, infer R> ? R : never;
+/**
+ * Convert a readonly tuple of QueryDefinitions into a Record keyed by their
+ * name literals. This is what makes ClientRpc fully type-safe: each key in
+ * the map carries its own TParams and TResult rather than collapsing to `any`.
+ *
+ * Example:
+ *   const defs = [projectBoardQuery, teamMembersQuery] as const;
+ *   type Map = DefsToMap<typeof defs>;
+ *   // → { projectBoard: typeof projectBoardQuery; teamMembers: typeof teamMembersQuery }
+ */
+type DefsToMap<T extends readonly AnyQueryDef[]> = { [D in T[number] as D["name"]]: D };
+/** For test teardown only — clears the global map between suites. */
+declare function _resetGlobalDefs(): void;
+/**
+ * Create a named, typed query definition.
+ *
+ * The definition is automatically registered in a module-level global so
+ * the server can call registry.defineAll() instead of listing every query
+ * explicitly. On the client, pass the definition to createClientRpc() to
+ * get a fully typed subscribe() call.
+ *
+ * Usage:
+ *   export const projectBoardQuery = defineQuery(
+ *     "projectBoard",
+ *     async (ctx, params: { projectId: string }) => {
+ *       return ctx.query(Tasks)
+ *         .select()
+ *         .where(f => f.eq("projectId", params.projectId))
+ *         .get();
+ *     }
+ *   );
+ */
+declare function defineQuery<TName extends string, TParams, TResult>(name: TName, fn: (ctx: DbReader, params: TParams) => Promise<TResult>): QueryDefinition<TName, TParams, TResult>;
+//#endregion
+//#region src/db/realtime_db.d.ts
+declare class SupaliveDb {
+  readonly impl: Database;
+  readonly ephemeral: EphemeralStore;
+  readonly replica?: SupaliveDb | undefined;
+  /**
+   * @param impl      the PRIMARY (writer) connection — all mutations, the OCC
+   *                  commit-ts source, and cache-freshness commit-log scans run here.
+   * @param ephemeral Redis-backed store behind `ctx.db.ephemeral` (db/ephemeral.ts).
+   *                  Required: it is reachable from every handler context, so a
+   *                  db that could be missing one would push the failure out to
+   *                  request time. A replica SHARES the primary's store —
+   *                  ephemeral state lives in Redis rather than in either
+   *                  connection, so read routing must not change what it sees.
+   * @param replica   optional read replica for query/action reads (see the
+   *                  routing in one-shot-query.ts). Undefined → reads use primary.
+   */
+  constructor(impl: Database, ephemeral: EphemeralStore, replica?: SupaliveDb | undefined);
+  static create(config: {
+    db: Database; /** See the constructor: shared with the replica, never per-connection. */
+    ephemeral: EphemeralStore;
+    replica?: Database;
+  }): SupaliveDb;
+  /** True when a distinct read replica is configured. */
+  get hasReplica(): boolean;
+  /**
+   * Register a hook fired after every batch of ephemeral writes lands in Redis.
+   * The ephemeral twin of {@link setOnAfterCommit}: the server uses it to drive
+   * subscription invalidation for writes from any source — an action, a job, or
+   * a mutation's post-commit flush.
+   */
+  setOnAfterEphemeralWrite(cb: (keys: string[], version: string) => void): void;
+  protected onAfterCommit?: (writeSet: WriteEntry[], commitTs: CommitTs) => void;
+  /**
+   * Register a hook fired once after every successful `mutation()` commit
+   * (never on an OCC conflict/rollback), with the committed writeSet and its
+   * commitTs. The server uses this to drive subscription invalidation for ALL
+   * mutation sources — client WS calls, actions, jobs, and the internal caller —
+   * so a server-side write pushes live updates just like a client write does.
+   * Non-server consumers (migration tooling, tests) leave it unset (no-op).
+   */
+  setOnAfterCommit(cb: (writeSet: WriteEntry[], commitTs: CommitTs) => void): void;
+  /**
+   * One-shot read against an EXPLICIT connection + snapshot ts (rather than this
+   * db's own latest). Used by the replica router: the caller pre-resolves the
+   * default read connection (replica for queries) and hands the handler a
+   * `DbReader` it can rebind via `useConnection` (ctx.usePrimaryConn/…). The
+   * returned `ts` is the FINAL bound connection's snapshot, so the cache entry is
+   * stamped with the ts actually read at.
+   */
+  queryInternalOn<T>(read: {
+    impl: Database;
+    beginTs: bigint;
+  }, fn: (ctx: DbReader) => Promise<T>): Promise<LiveResult<T>>;
+  query<T>(fn: (ctx: DbReader) => Promise<T>): Promise<T>;
+  /**
+   * Compute a query once at the latest snapshot, returning the result together
+   * with the snapshot `ts` and the tracked `readSet`. This is a plain one-shot
+   * evaluation — it registers NO live subscription; the `readSet`/`ts` are
+   * returned purely so the caller (e.g. the one-shot query cache) can store
+   * freshness metadata. Use this for cached one-shot query calls (WS `call`,
+   * HTTP RPC). `liveQuery` is the same computation under the subscription path's
+   * name and simply delegates here.
+   */
+  queryInternal<T>(fn: (ctx: DbReader) => Promise<T>): Promise<LiveResult<T>>;
+  liveQuery<T>(fn: (ctx: DbReader) => Promise<T>): Promise<LiveResult<T>>;
+  mutation<T>(fn: (ctx: DbWriter) => Promise<T>, retryPolicy?: RetryPolicy): Promise<MutationResult<T>>;
+}
+declare const sleep: (ms: number) => Promise<void>;
+//#endregion
+//#region src/jobs/scheduler.d.ts
+/** A recurring job to keep synced on the scheduler side. */
+interface ScheduledJobDef {
+  /** Job procedure name (also the last path segment of its endpoint). */
+  name: string;
+  /** Cron expression, e.g. `"0 3 * * *"`. */
+  cron: string;
+}
+/** Options for a precise, one-shot job run. */
+interface EnqueueOptions {
+  /** Run after this many seconds from now. */
+  delaySeconds?: number;
+  /** Run at this absolute time. Overrides `delaySeconds`. */
+  runAt?: Date;
+  /**
+   * Idempotency key. If two enqueues share the same id within the provider's
+   * dedup window, only the first is delivered. Use it to make "schedule the
+   * expiry of X" safe to call more than once.
+   */
+  dedupeId?: string;
+}
+/** Handle returned by {@link JobScheduler.enqueue}; pass its `id` to `cancel`. */
+interface ScheduleHandle {
+  id: string;
+}
+/** The pieces of an inbound webhook the scheduler needs to authenticate it. */
+interface IncomingJobRequest {
+  /** Job name parsed from the request path. */
+  name: string;
+  /** Raw (unparsed) request body — signatures are computed over these bytes. */
+  rawBody: string;
+  /** Request headers, keys lowercased. */
+  headers: Record<string, string | undefined>;
+  /** Full request URL the webhook was delivered to. */
+  url: string;
+}
+/**
+ * Pluggable scheduler. The server owns exactly one instance and uses it for
+ * both directions:
+ *   • inbound  — `verify` authenticates a webhook before the job runs.
+ *   • outbound — `syncSchedules` (recurring, at startup) and `enqueue`/`cancel`
+ *                (precise one-shots, at runtime) drive the provider.
+ *
+ * Both dev and production implementations POST to the same HTTP job endpoint,
+ * so the server's dispatch path is exercised identically in every environment.
+ */
+interface JobScheduler {
+  /** Authenticate an inbound webhook. Return false (or throw) to reject. */
+  verify(req: IncomingJobRequest): Promise<boolean>;
+  /**
+   * Make the provider's recurring schedules match `jobs` exactly (create,
+   * update, and remove stale ones). Called once at server startup.
+   * `endpointFor(name)` yields the absolute URL the provider should POST to.
+   */
+  syncSchedules(jobs: ScheduledJobDef[], endpointFor: (name: string) => string): Promise<void>;
+  /** Enqueue a precise one-shot run of `name` with `body` at `endpoint`. */
+  enqueue(name: string, body: unknown, endpoint: string, opts?: EnqueueOptions): Promise<ScheduleHandle>;
+  /** Cancel a previously enqueued one-shot by its handle id. */
+  cancel(handleId: string): Promise<void>;
+}
+interface DevSchedulerOptions {
+  /**
+   * How often, in ms, to fire each recurring job in dev. Dev intentionally
+   * ignores exact cron timing (that is the production scheduler's job); it
+   * just fires often enough to exercise the handler. Default 60_000.
+   */
+  recurringIntervalMs?: number;
+  /**
+   * Override the HTTP client (for tests). Defaults to the global `fetch`.
+   */
+  fetchImpl?: typeof fetch;
+}
+/**
+ * In-process scheduler for local development and tests. Recurring jobs fire on
+ * a fixed interval; one-shots fire on an exact `setTimeout` (so precise timing
+ * is faithfully testable). Every fire POSTs to the real HTTP job endpoint, and
+ * `verify` accepts everything — there is no signing in dev.
+ */
+declare class DevScheduler implements JobScheduler {
+  private readonly intervalMs;
+  private readonly fetchImpl;
+  private intervals;
+  private timeouts;
+  constructor(opts?: DevSchedulerOptions);
+  verify(_req: IncomingJobRequest): Promise<boolean>;
+  syncSchedules(jobs: ScheduledJobDef[], endpointFor: (name: string) => string): Promise<void>;
+  enqueue(name: string, body: unknown, endpoint: string, opts?: EnqueueOptions): Promise<ScheduleHandle>;
+  cancel(handleId: string): Promise<void>;
+  /** Stop every dev timer (call on server shutdown / in test teardown). */
+  stop(): void;
+  private post;
+}
+interface QStashSchedulerOptions {
+  /** QStash Base url (`QSTASH_BASE_URL`). */
+  baseUrl: string;
+  /** QStash REST token (`QSTASH_TOKEN`). */
+  token: string;
+  /** Current signing key for webhook verification (`QSTASH_CURRENT_SIGNING_KEY`). */
+  currentSigningKey: string;
+  /** Next signing key, for zero-downtime key rotation (`QSTASH_NEXT_SIGNING_KEY`). */
+  nextSigningKey: string;
+  devMode: boolean;
+}
+/**
+ * Production scheduler backed by Upstash QStash. Externalizes the timer so a
+ * horizontally-scaled deployment fires each cron tick exactly once (QStash
+ * calls one HTTP endpoint), with at-least-once retries and signed webhooks.
+ */
+declare class QStashScheduler implements JobScheduler {
+  private readonly client;
+  private readonly receiver;
+  constructor(opts: QStashSchedulerOptions);
+  verify(req: IncomingJobRequest): Promise<boolean>;
+  syncSchedules(jobs: ScheduledJobDef[], endpointFor: (name: string) => string): Promise<void>;
+  enqueue(name: string, body: unknown, endpoint: string, opts?: EnqueueOptions): Promise<ScheduleHandle>;
+  cancel(handleId: string): Promise<void>;
+}
+/**
+ * Thin app-facing handle for scheduling precise one-shots from inside
+ * procedures. The server builds one (via `getJobClient()`) that already knows
+ * how to turn a job name into its endpoint, so callers just say
+ * `jobs.enqueue("expireSpendAuth", { id }, { runAt })`.
+ */
+declare class JobClient {
+  private readonly scheduler;
+  private readonly endpointFor;
+  constructor(scheduler: JobScheduler, endpointFor: (name: string) => string);
+  enqueue(name: string, body: unknown, opts?: EnqueueOptions): Promise<ScheduleHandle>;
+  cancel(handleId: string): Promise<void>;
+}
+//#endregion
+//#region src/router/procedure.d.ts
+/**
+ * Minimal request-scoped logger exposed as `ctx.log`. Structurally satisfied by
+ * a pino logger, so the server hands its own child logger straight through; the
+ * interface keeps handler code decoupled from pino. Bound with `reqId`, the
+ * procedure name, and (when tracing is enabled) the `traceId`, so every line a
+ * handler writes correlates to its request and trace.
+ */
+interface HandlerLogger {
+  debug: pino.LogFn;
+  info: pino.LogFn;
+  warn: pino.LogFn;
+  error: pino.LogFn;
+}
+/**
+ * Observability handles present on a handler context. `log` is ALWAYS present:
+ * the server binds a request-correlated logger, and direct internal-caller
+ * invocations build a per-procedure child logger from the caller's observability —
+ * handlers never null-check it.
+ */
+interface HandlerObservability {
+  /** Logger correlated to this operation — request-scoped (reqId + trace id) on
+   *  the server path, a per-procedure child logger on internal-caller paths. */
+  log: HandlerLogger;
+  /** The active OpenTelemetry span for this operation. Add attributes/events or
+   *  parent child spans off it. A non-recording no-op span when tracing is off. */
+  span?: Span;
+}
+/**
+ * Query context passed to query handlers.
+ * Contains database reader and user-defined server context.
+ */
+/** Options for the per-handler connection-routing methods (see {@link QueryCtx}). */
+interface ConnOpts {
+  /**
+   * Force the PRIMARY (writer) connection even inside a query/action —
+   * read-your-writes. On `useReplicaConn` this overrides the replica choice.
+   */
+  readOwnWrite?: boolean;
+}
+interface QueryCtx<TContext = unknown> extends HandlerObservability {
+  /** Database reader for queries */
+  db: DbReader;
+  /** User-defined server context (auth, requestId, etc.) */
+  serverCtx?: TContext;
+  /**
+   * Route this query's reads to the PRIMARY (writer) connection. Must be called
+   * BEFORE any read (throws otherwise). A no-op when reads already run on primary
+   * (no replica configured, or a primary-only path like a live query).
+   */
+  usePrimaryConn(opts?: ConnOpts): void;
+  /**
+   * Route this query's reads to the read REPLICA, if one is configured. Must be
+   * called BEFORE any read. `{ readOwnWrite: true }` forces the PRIMARY instead.
+   */
+  useReplicaConn(opts?: ConnOpts): void;
+}
+/**
+ * Mutation context passed to mutation handlers.
+ * Contains database writer and user-defined server context.
+ */
+interface MutationCtx<TContext = unknown> extends HandlerObservability {
+  /** Database writer for mutations (includes insert/update/delete) */
+  db: DbWriter;
+  /** User-defined server context (auth, requestId, etc.) */
+  serverCtx?: TContext;
+  /**
+   * No-op on a mutation — writes (and their reads) always run on the primary.
+   * Present so a `MutationCtx` stays structurally assignable to `QueryCtx`, i.e.
+   * a mutation can reuse a `(ctx: QueryCtx) => …` read helper.
+   */
+  usePrimaryConn(opts?: ConnOpts): void;
+  /** No-op on a mutation (always primary). See {@link usePrimaryConn}. */
+  useReplicaConn(opts?: ConnOpts): void;
+}
+/**
+ * Action context passed to action handlers.
+ *
+ * Actions are the "external I/O" tier: they hold the full {@link SupaliveDb}
+ * (queries + mutations) and are the ONLY context that also carries side-effect
+ * services — {@link ObjectStorage} for uploads/downloads and a {@link JobClient}
+ * for scheduling precise one-shots. Queries/mutations stay pure (db only) so
+ * they remain cacheable and transaction-scoped.
+ */
+interface ActionCtx<TContext = unknown> extends HandlerObservability {
+  /** Full database interface for queries and mutations */
+  db: SupaliveDb;
+  /** Object storage, when the server was configured with one (see
+  * `SupaliveServerConfig.storage`); `undefined` otherwise. The usual home
+  * for upload/download presigning. */
+  storage: ObjectStorage;
+  /** Job scheduler client for enqueueing precise one-shots, when the server
+   * was configured with a `scheduler`; `undefined` otherwise. Scheduling is
+   * network I/O, so it belongs in actions, never inside a DB transaction. */
+  scheduler: JobClient;
+  /** User-defined server context (auth, requestId, etc.) */
+  serverCtx?: TContext;
+}
+/**
+ * Job context passed to job handlers. Structurally identical to
+ * {@link ActionCtx}: a job is a server-only procedure that runs
+ * non-transactionally against the full {@link SupaliveDb} and may perform
+ * external work, but it is triggered by the scheduler over HTTP (a cron tick
+ * or a precise one-shot) rather than by a connected client. `serverCtx` is
+ * the system context built by the server's `jobContext` factory.
+ */
+interface JobCtx<TContext = unknown> extends HandlerObservability {
+  /** Full database interface for queries and mutations */
+  db: SupaliveDb;
+  /** Object storage (R2 / S3) for server-side reads/writes from a job */
+  storage: ObjectStorage;
+  /** Job client for scheduling precise one-shots from inside a job */
+  scheduler: JobClient;
+  /** System server context built by the server for scheduler-triggered runs */
+  serverCtx?: TContext;
+}
+/**
+ * Context handed to `caller.<proc>.runQuery` / `.runMutation` when invoking one
+ * procedure from inside another. Pass the caller handler's own `ctx` — its `db`
+ * carries the parent's live transaction (a {@link DbReader}/{@link DbWriter}) or,
+ * inside an action, the full {@link SupaliveDb}. The caller uses this to decide
+ * whether the nested call joins the parent's snapshot (queries) or runs as an
+ * independent sub-transaction (mutations).
+ */
+interface ParentCtx<TContext = unknown> {
+  db: DbReader | DbWriter | SupaliveDb;
+  serverCtx?: TContext | undefined;
+  /**
+   * The parent handler's own logger, carried through to a nested
+   * `runQuery`/`runMutation` so the nested call logs under the SAME logger as
+   * its parent (reqId/trace correlation preserved).
+   */
+  log: HandlerLogger;
+  /**
+   * The parent handler's own span, carried through to a nested
+   * `runQuery`/`runMutation`. Used ONLY as an explicit fallback parent: the
+   * nested call normally links implicitly through the ambient OTEL context
+   * (the parent handler already runs inside its operation span's context).
+   * This span is consulted only when the ambient context is root — e.g. a
+   * detached/fire-and-forget internal call.
+   */
+  span?: Span;
+}
+/**
+ * The slice of the server's {@link Observability} an internal caller needs to
+ * build per-call loggers (see `createCaller().init({ obs })`). Structural, so an
+ * `Observability` instance satisfies it without the caller depending on it.
+ */
+interface CallerObservability {
+  lazyChildLogger(fields: Record<string, unknown>): HandlerLogger;
+}
+type QueryFn<TInput, TResult, TContext = unknown> = (ctx: QueryCtx<TContext>, input: TInput) => Promise<TResult>;
+type MutationFn<TInput, TResult, TContext = unknown> = (ctx: MutationCtx<TContext>, input: TInput) => Promise<TResult>;
+type ActionFn<TInput, TResult, TContext = unknown> = (ctx: ActionCtx<TContext>, input: TInput) => Promise<TResult>;
+type JobFn<TInput, TResult, TContext = unknown> = (ctx: JobCtx<TContext>, input: TInput) => Promise<TResult>;
+/**
+ * Per-procedure override for the cache/subscription segmentation key.
+ *
+ *   omitted | undefined  → fall back to `config.getUserId(serverCtx)` (default)
+ *   false               → no identity in hash; cache/sub shared across all users
+ *   string              → a static identity literal (e.g. "public" or a tenant id)
+ *   function            → compute from serverCtx + input (sync)
+ *
+ * When the result of a query is identical regardless of who calls it, set
+ * this to a literal (or `false`) so a single cache entry serves everyone.
+ *
+ * The function form intentionally takes `serverCtx` (not the full `QueryCtx`)
+ * because identity is resolved before any DB read is issued.
+ */
+type QueryIdentitySpec<TInput, TContext> = false | string | ((serverCtx: TContext, input: TInput) => string | null | undefined);
+interface BaseProcedure<TInput, TResult, TType extends "query" | "mutation" | "action" | "job", TContext = unknown, TInternal extends boolean = boolean> {
+  readonly _type: "procedure";
+  readonly procedureType: TType;
+  readonly inputSchema: ZodType<TInput>;
+  readonly outputSchema?: ZodType<any>;
+  readonly fn: QueryFn<TInput, TResult, TContext> | MutationFn<TInput, TResult, TContext> | ActionFn<TInput, TResult, TContext> | JobFn<TInput, TResult, TContext>;
+  readonly internal: TInternal;
+}
+interface QueryProcedure<TInput, TResult, TContext = unknown, TInternal extends boolean = boolean> extends BaseProcedure<TInput, TResult, "query", TContext, TInternal> {
+  readonly procedureType: "query";
+  readonly fn: QueryFn<TInput, TResult, TContext>;
+  readonly queryIdentity?: QueryIdentitySpec<TInput, TContext>;
+}
+interface MutationProcedure<TInput, TResult, TContext = unknown, TInternal extends boolean = boolean> extends BaseProcedure<TInput, TResult, "mutation", TContext, TInternal> {
+  readonly procedureType: "mutation";
+  readonly fn: MutationFn<TInput, TResult, TContext>;
+}
+interface ActionProcedure<TInput, TResult, TContext = unknown, TInternal extends boolean = boolean> extends BaseProcedure<TInput, TResult, "action", TContext, TInternal> {
+  readonly procedureType: "action";
+  readonly fn: ActionFn<TInput, TResult, TContext>;
+}
+/**
+ * A scheduler-triggered, server-only procedure. Runs like an action (full
+ * db, non-transactional, may do external work) but is dispatched by the
+ * server's HTTP job endpoint on a cron tick or a precise one-shot rather
+ * than over the client WebSocket. Always {@link internal}: true, so it is
+ * never reachable via `call`/`subscribe`.
+ */
+interface JobProcedure<TInput, TResult, TContext = unknown> extends BaseProcedure<TInput, TResult, "job", TContext, true> {
+  readonly procedureType: "job";
+  readonly fn: JobFn<TInput, TResult, TContext>;
+  /**
+   * Cron expression for a recurring job (e.g. `"0 3 * * *"`). Declared crons
+   * are synced to the scheduler at server startup. Omit for a job that is
+   * only ever invoked as a precise one-shot via the scheduler API.
+   */
+  readonly cron?: string;
+}
+type AnyProcedure<TContext = unknown> = QueryProcedure<any, any, TContext> | MutationProcedure<any, any, TContext> | ActionProcedure<any, any, TContext> | JobProcedure<any, any, TContext>;
+interface QueryConfig<TInput, TResult, TContext = unknown> {
+  /** Zod schema for input validation */
+  args: ZodType<TInput>;
+  /** The query handler function */
+  handler: QueryFn<TInput, TResult, TContext>;
+  /** Mark as internal (server-only). Default: false */
+  internal?: boolean;
+  /**
+   * Optional Zod schema describing return-type overrides for codegen.
+   * Only the fields you specify are overridden; everything else is inferred
+   * from the handler's TypeScript return type. Use `.modelName("Name")`
+   * on a Zod object to rename the generated model class.
+   */
+  returns?: ZodType<any>;
+  /**
+   * Override the cache/subscription segmentation key for this procedure.
+   * See {@link QueryIdentitySpec}. Omit to keep the default (per-user) behavior.
+   */
+  queryIdentity?: QueryIdentitySpec<TInput, TContext>;
+}
+interface MutationConfig<TInput, TResult, TContext = unknown> {
+  /** Zod schema for input validation */
+  args: ZodType<TInput>;
+  /** The mutation handler function */
+  handler: MutationFn<TInput, TResult, TContext>;
+  /** Mark as internal (server-only). Default: false */
+  internal?: boolean;
+  /**
+   * Optional Zod schema describing return-type overrides for codegen.
+   * Only the fields you specify are overridden; everything else is inferred
+   * from the handler's TypeScript return type.
+   */
+  returns?: ZodType<any>;
+}
+interface ActionConfig<TInput, TResult, TContext = unknown> {
+  /** Zod schema for input validation */
+  args: ZodType<TInput>;
+  /** The action handler function */
+  handler: ActionFn<TInput, TResult, TContext>;
+  /** Mark as internal (server-only). Default: false */
+  internal?: boolean;
+  /**
+   * Optional Zod schema describing return-type overrides for codegen.
+   * Only the fields you specify are overridden; everything else is inferred
+   * from the handler's TypeScript return type.
+   */
+  returns?: ZodType<any>;
+}
+interface JobConfig<TInput, TResult, TContext = unknown> {
+  /** Zod schema for the job payload */
+  args: ZodType<TInput>;
+  /** The job handler function */
+  handler: JobFn<TInput, TResult, TContext>;
+  /**
+   * Cron expression for a recurring schedule (e.g. `"0 3 * * *"`). Omit for a
+   * job that is only invoked as a precise one-shot.
+   */
+  cron?: string;
+}
+/** Extract input type from a procedure */
+type InputOf<T> = T extends BaseProcedure<infer I, any, any, any> ? I : never;
+/** Extract output type from a procedure */
+type OutputOf<T> = T extends BaseProcedure<any, infer O, any, any> ? O : never;
+/** Extract procedure type (query/mutation) */
+type TypeOf<T> = T extends BaseProcedure<any, any, infer Type, any> ? Type : never;
+/** Extract server context type from a procedure */
+type ContextOf<T> = T extends BaseProcedure<any, any, any, infer C> ? C : never;
+/**
+ * Create a query builder with a pre-defined context type.
+ * This allows you to define the context type once and have it inferred
+ * automatically in all your query handlers.
+ *
+ * @example
+ * // Define your server context
+ * interface ServerContext {
+ *   auth: { userId: string };
+ *   requestId: string;
+ * }
+ *
+ * // Create a typed query builder
+ * const query = createQueryBuilder<ServerContext>();
+ *
+ * // Use it - context type is automatically inferred!
+ * const getUser = query({
+ *   args: z.object({ id: z.string() }),
+ *   handler: async (ctx, { id }) => {
+ *     // ctx.db for database queries
+ *     const user = await ctx.db.query(UsersSchema).find(id);
+ *     // ctx.context for server context
+ *     console.log(ctx.context.requestId);
+ *     return user;
+ *   }
+ * });
+ */
+declare function createQueryBuilder<TContext = unknown>(): <TInput, TResult, const TInternal extends boolean = false>(config: QueryConfig<TInput, TResult, TContext> & {
+  internal?: TInternal;
+}) => QueryProcedure<TInput, TResult, TContext, TInternal>;
+/**
+ * Create a mutation builder with a pre-defined context type.
+ * This allows you to define the context type once and have it inferred
+ * automatically in all your mutation handlers.
+ *
+ * @example
+ * // Define your server context
+ * interface ServerContext {
+ *   auth: { userId: string };
+ *   requestId: string;
+ * }
+ *
+ * // Create a typed mutation builder
+ * const mutation = createMutationBuilder<ServerContext>();
+ *
+ * // Use it - context type is automatically inferred!
+ * const createUser = mutation({
+ *   args: z.object({ name: z.string() }),
+ *   handler: async (ctx, { name }) => {
+ *     // ctx.db for mutations
+ *     await ctx.db.insert(UsersSchema, id, { name });
+ *     // ctx.context for server context
+ *     console.log(ctx.context.requestId);
+ *     return { success: true };
+ *   }
+ * });
+ */
+declare function createMutationBuilder<TContext = unknown>(): <TInput, TResult, const TInternal extends boolean = false>(config: MutationConfig<TInput, TResult, TContext> & {
+  internal?: TInternal;
+}) => MutationProcedure<TInput, TResult, TContext, TInternal>;
+/**
+ * Create an action builder with a pre-defined context type.
+ * Actions have access to the full SupaliveDb for both queries and mutations.
+ *
+ * @example
+ * // Define your server context
+ * interface ServerContext {
+ *   auth: { userId: string };
+ *   requestId: string;
+ * }
+ *
+ * // Create a typed action builder
+ * const action = createActionBuilder<ServerContext>();
+ *
+ * // Use it - context type is automatically inferred!
+ * const processOrder = action({
+ *   args: z.object({ orderId: z.string() }),
+ *   handler: async (ctx, { orderId }) => {
+ *     // ctx.db for full database access
+ *     const order = await ctx.db.query(async (db) => {
+ *       return db.query(OrdersSchema).find(orderId);
+ *     });
+ *     await ctx.db.mutation(async (db) => {
+ *       await db.update(OrdersSchema, orderId, { status: "processed" });
+ *     });
+ *     // ctx.context for server context
+ *     console.log(ctx.context.requestId);
+ *     return { success: true };
+ *   }
+ * });
+ */
+declare function createActionBuilder<TContext = unknown>(): <TInput, TResult, const TInternal extends boolean = false>(config: ActionConfig<TInput, TResult, TContext> & {
+  internal?: TInternal;
+}) => ActionProcedure<TInput, TResult, TContext, TInternal>;
+/**
+ * Create a job builder with a pre-defined context type. A job is a
+ * server-only procedure invoked by the scheduler over HTTP — either on its
+ * declared `cron` schedule or as a precise one-shot enqueued via the
+ * server's job API. Jobs run like actions (full db, non-transactional) and
+ * are always internal, so they are never reachable from a client.
+ *
+ * @example
+ * const job = createJobBuilder<ServerContext>();
+ *
+ * export const cleanupOtps = job({
+ *   cron: "0 * * * *", // hourly
+ *   args: z.object({}),
+ *   handler: async (ctx) => {
+ *     await ctx.db.mutation(async (db) => { ... });
+ *     return { ok: true };
+ *   },
+ * });
+ */
+declare function createJobBuilder<TContext = unknown>(): <TInput, TResult>(config: JobConfig<TInput, TResult, TContext>) => JobProcedure<TInput, TResult, TContext>;
+//#endregion
+//#region src/router/router.d.ts
+/**
+ * A router maps procedure names (keys) to their definitions.
+ * This is the type that's exported from your app and used by the client.
+ */
+type Router<TProcedures extends Record<string, AnyProcedure<TContext>>, TContext = unknown> = {
+  _type: "router";
+  procedures: TProcedures;
+  contextName: string;
+};
+/**
+ * Inferred AppRouter type from router() call.
+ * Captures the full procedure map for client type inference.
+ */
+type AppRouter<TProcedures extends Record<string, AnyProcedure<TContext>> = Record<string, AnyProcedure>, TContext = unknown> = Router<TProcedures, TContext>;
+/** Get query procedures only from a router */
+type QueryProcedures<T extends Record<string, AnyProcedure>> = { [K in keyof T as T[K] extends {
+  procedureType: "query";
+} ? K : never]: T[K] };
+/** Get mutation procedures only from a router */
+type MutationProcedures<T extends Record<string, AnyProcedure>> = { [K in keyof T as T[K] extends {
+  procedureType: "mutation";
+} ? K : never]: T[K] };
+/** Get action procedures only from a router */
+type ActionProcedures<T extends Record<string, AnyProcedure>> = { [K in keyof T as T[K] extends {
+  procedureType: "action";
+} ? K : never]: T[K] };
+/** Get job procedures only from a router */
+type JobProcedures<T extends Record<string, AnyProcedure>> = { [K in keyof T as T[K] extends {
+  procedureType: "job";
+} ? K : never]: T[K] };
+/** Get public (non-internal) procedures - for client type safety */
+type PublicProcedures<T extends Record<string, AnyProcedure>> = Pick<T, { [K in keyof T]: T[K] extends {
+  internal: true;
+} ? never : K }[keyof T]>;
+/** Extract procedure names from a router */
+type ProcedureNames<T extends Router<any>> = T extends Router<infer P> ? keyof P : never;
+type RouterConfig<T> = {
+  procedures: T;
+  contextName?: string;
+};
+/**
+* Create a router from procedure definitions.
+* Procedure names are inferred from the object keys.
+*
+* @example
+* const appRouter = router({
+*   procedures: {
+*     getUser,
+*     createUser,
+*     internalGetAll,
+*   },
+* });
+*
+* export type AppRouter = typeof appRouter;
+*/
+declare function router<TProcedures extends Record<string, AnyProcedure<any>>, TContext = unknown>(config: RouterConfig<TProcedures>): Router<TProcedures, TContext>;
+interface RegisteredProcedure<TContext = unknown> {
+  name: string;
+  type: "query" | "mutation" | "action" | "job";
+  internal: boolean;
+  inputSchema: AnyProcedure<TContext>["inputSchema"];
+  fn: AnyProcedure<TContext>["fn"];
+  /** Only present for `type === "query"`. See `QueryIdentitySpec`. */
+  queryIdentity?: false | string | ((serverCtx: TContext | undefined, input: unknown) => string | null | undefined);
+  /** Only present for `type === "job"`. Cron expression for recurring jobs. */
+  cron?: string;
+}
+declare function getContextRegistry(inContext: string): ContextRegistry;
+declare class ContextRegistry {
+  procedureRegistry: Map<string, RegisteredProcedure<any>>;
+  internalProcedureNames: Set<string>;
+  registerProcedure<TContext>(name: string, proc: AnyProcedure<TContext>): void;
+  /** Get a registered procedure by name (runtime lookup) */
+  getProcedure<TContext = unknown>(name: string): RegisteredProcedure<TContext> | undefined;
+  /** Get all registered procedure names */
+  getProcedureNames(): string[];
+  /** Get all registered procedures */
+  getAllProcedures(): Map<string, RegisteredProcedure>;
+  /** Get all registered job procedures (server-only, scheduler-triggered). */
+  getJobProcedures(): RegisteredProcedure[];
+  /** Clear the registry (for testing only) */
+  clearRegistry(): void;
+  markInternalProcedure(name: string): void;
+  isInternalProcedure(name: string): boolean;
+  clearInternalProcedures(): void;
+}
+//#endregion
+//#region src/client/ws_client_manager.d.ts
+declare class RPCError extends Error {
+  code?: string;
+  constructor(message: string, code?: string);
+}
+type ClientLogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/** Minimal logger sink the client writes lifecycle/diagnostic lines to. Pass a
+ *  custom implementation via {@link WSClientOptions.logger} to route logs into
+ *  your app's logger; otherwise a console sink gated by
+ *  {@link WSClientOptions.logLevel} is used. */
+interface ClientLogger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+/** A structured lifecycle event, for feeding client metrics without parsing logs. */
+interface ClientEvent {
+  type: "connecting" | "connected" | "disconnected" | "reconnecting" | "error";
+  /** Reason/detail (e.g. reconnect trigger, close reason). */
+  detail?: string;
+  /** Reconnect attempt number, when `type === "reconnecting"`. */
+  attempt?: number;
+}
+/** Console-backed logger that drops anything below `level`. `"silent"` mutes all. */
+declare function createConsoleLogger(level?: ClientLogLevel): ClientLogger;
+interface HeartbeatOptions {
+  /**
+   * Close + reconnect when no server message arrives for this long. The
+   * server emits `{type:"ping"}` every ~15s of channel idle, so anything
+   * larger than ~30s leaves comfortable headroom. Default 60_000.
+   */
+  serverInactivityMs?: number;
+}
+interface SendThrottleOptions {
+  /** Yield the event loop every N `call()` invocations. 0 disables. Default 100. */
+  everyN?: number;
+  /** Length of the yield in ms. Default 10. */
+  delayMs?: number;
+}
+interface WSClientOptions {
+  /** WebSocket URL (e.g. ws://localhost:3000/ws) */
+  url: string;
+  /** Auth token to send after connection */
+  token?: () => Promise<string | undefined>;
+  /** Optional: reconnection timeout in ms (default: 180000 = 3 minutes) */
+  reconnectionTimeout?: number;
+  /** Reconnection options */
+  reconnect?: {
+    /** Enable automatic reconnection (default: true) */enabled?: boolean; /** Max reconnection attempts (default: 5) */
+    maxAttempts?: number; /** Delay between attempts in ms (default: 1000) */
+    delay?: number; /** Exponential backoff multiplier (default: 1.5) */
+    backoff?: number;
+  };
+  /** Server-inactivity watchdog. See {@link HeartbeatOptions.serverInactivityMs}. */
+  heartbeat?: HeartbeatOptions;
+  /**
+   * Yields the event loop for `delayMs` ms after every `everyN`
+   * `call()` invocations. Useful for keeping React renders / GC tasks
+   * scheduled during long synchronous bursts of mutations/actions; the
+   * heartbeat does not depend on this (the server drives it).
+   * Default `{ everyN: 100, delayMs: 10 }`. Set `everyN: 0` to disable.
+   */
+  throttle?: SendThrottleOptions;
+  /** Called when connection is established */
+  onConnect?: () => void;
+  /** Called when connection is lost */
+  onDisconnect?: () => void;
+  /** Called on connection error */
+  onError?: (error: Error) => void;
+  /**
+   * Custom log sink. When set, it receives all lifecycle/diagnostic lines and
+   * `logLevel` is ignored (filtering is the sink's responsibility). When unset,
+   * a console sink gated by {@link logLevel} is used.
+   */
+  logger?: ClientLogger;
+  /** Level for the default console logger. Default `"warn"` (quiet). */
+  logLevel?: ClientLogLevel;
+  /** Optional structured lifecycle events, for client-side metrics. */
+  onEvent?: (event: ClientEvent) => void;
+  /**
+   * OpenTelemetry-agnostic trace propagation. Return the current W3C
+   * `traceparent` for the active client span (e.g. from `@opentelemetry/api`'s
+   * propagation) and it is sent on every `call`/`subscribe`; the server
+   * continues the trace. Return `undefined` (the default — no hook) to send
+   * nothing. Called per outbound request.
+   */
+  getTraceparent?: () => string | undefined | null;
+}
+/**
+ * Public state of the client, surfaced to consumers (React provider, etc.).
+ * - "connecting" — initial connect or reconnect handshake in flight
+ * - "authenticating" — connected, waiting for auth result
+ * - "ready" — connected and auth resolved (authenticated, anonymous, or
+ *   explicitly failed — i.e. ready to send calls)
+ * - "disconnected" — currently offline (may auto-retry)
+ */
+type ClientPublicState = "disconnected" | "connecting" | "authenticating" | "ready";
+declare class WsClientManager {
+  private ws;
+  private options;
+  private lastSuccessfulConnectionTime;
+  private reconnectionTimeout;
+  private requestId;
+  private pendingRequests;
+  /**
+   * Single source of truth for live subscriptions.
+   *
+   * Keying:
+   *   - In-flight subscribe (no subId yet): `_pending:<requestId>`.
+   *   - Established: the server-returned canonical `subId`.
+   *
+   * Routing `sub:update` / `sub:gone` is O(1) (`get(subId)`). Subscribe-time
+   * dedup scans `values()` for a matching `localKey` (O(N)), which is cheap
+   * since subscribes happen on component mounts, not in the hot path.
+   */
+  private subscriptions;
+  private queuedCalls;
+  private reconnectAttempts;
+  private reconnectTimer;
+  private connectionState;
+  private authState;
+  /**
+   * Authenticated user id from `auth:success`. Distinct from `queryIdentity`
+   * (server-side cache/sub segmentation key); this is just "who am I logged
+   * in as" for app display purposes. Null while unauthenticated / anonymous.
+   */
+  private authUserId;
+  private explicitlyClosed;
+  private stateListeners;
+  private lastPublicState;
+  private highWaterTs;
+  private serverInactivityMs;
+  private lastServerMessageAt;
+  private inactivityTimer;
+  private pendingConnectResolve;
+  private pendingConnectReject;
+  private throttleEveryN;
+  private throttleDelayMs;
+  private throttleCounter;
+  private throttling;
+  private visibilityListener;
+  private onlineListener;
+  private readonly log;
+  constructor(options: WSClientOptions);
+  /**
+   * Subscribe to client state transitions. Returns an unsubscribe fn.
+   * The listener is called immediately with the current state.
+   */
+  onState(listener: (s: ClientPublicState) => void): () => void;
+  /** Current public state. */
+  getPublicState(): ClientPublicState;
+  /**
+   * Connect to the WebSocket server.
+   * Returns a promise that resolves when connected and authenticated.
+   */
+  connect(): Promise<void>;
+  /**
+   * Disconnect from the server.
+   */
+  disconnect(): void;
+  /**
+   * Check if connected and authenticated.
+   */
+  isReady(): boolean;
+  /**
+   * Check if authenticated.
+   */
+  isAuthenticated(): boolean;
+  /**
+   * Check if anonymouse.
+   */
+  isAnonymouse(): boolean;
+  /**
+   * The authenticated user's id (from `auth:success`), or null when
+   * unauthenticated / anonymous. Useful for "Logged in as …" display.
+   *
+   * Not to be confused with server-side `queryIdentity`, which is the
+   * cache/subscription segmentation key (resolved entirely on the server).
+   */
+  getAuthUserId(): string | null;
+  /**
+   * Call a procedure (query, mutation, or action).
+   *
+   * If the client is not ready (disconnected or still authenticating), the
+   * call is FIFO-queued and dispatched on the next ready state. The promise
+   * still resolves with the eventual server response.
+   *
+   * Pass `onSend` to be notified when the call actually leaves the queue
+   * (used by `useMutation` to flip `state` from "queued" → "loading").
+   */
+  call(procedure: string, input: unknown, options?: {
+    onSend?: () => void;
+  }): Promise<unknown>;
+  /**
+   * Throttle drain loop. Each iteration: sleep `throttleDelayMs`, then
+   * dispatch up to `throttleEveryN` queued items. Exits as soon as the
+   * queue drains inside a single batch (burst over, back to direct
+   * dispatch on the next `call()`) or the connection goes away
+   * (reconnect path will restart us via `flushQueuedCalls`).
+   */
+  private runThrottleLoop;
+  /**
+   * Issue the call against an established connection. Caller must ensure
+   * `isReady()` before invoking.
+   */
+  private dispatchCall;
+  /** Advance the read high-water from a server-returned `ts` (monotonic). */
+  private advanceHighWater;
+  /**
+   * Flush queued calls in FIFO order. Called once `isReady()` becomes
+   * true. With the throttle enabled, dispatch the first batch
+   * synchronously then hand off to the drain loop so a large
+   * post-reconnect flush respects backpressure instead of dumping 10k
+   * frames in one tick.
+   */
+  private flushQueuedCalls;
+  /**
+   * Re-send `subscribe` for every existing subscription. The subId for each
+   * may legitimately change (e.g. `queryIdentity` was a function of user
+   * identity and the user changed during the disconnect), so we re-key the
+   * unified `subscriptions` Map: snapshot every record, drop them from the
+   * Map, then reinsert under a fresh `_pending:<reqId>` key. Each pending
+   * request's `resolve` rekeys the parked record under the new server-issued
+   * subId so subsequent `sub:update` frames route to the existing
+   * `onUpdate` callback (which the React handle is still holding).
+   */
+  private resubscribeAll;
+  /**
+   * Subscribe to a live query.
+   *
+   * The client does not compute the subId locally — it sends the
+   * (procedure, input) pair and receives the canonical subId on the
+   * subscribe response. This lets the server's per-procedure
+   * `queryIdentity` override be authoritative without forcing the client
+   * to mirror any of the resolution logic.
+   *
+   * Returns the server-assigned subId and an unsubscribe function.
+   */
+  subscribe(procedure: string, input: unknown, serializedInput: string, onUpdate: (data: unknown) => void, onGone?: (reason: string | undefined) => void): Promise<{
+    subId: string;
+    unsubscribe: () => void;
+  }>;
+  private findSubByLocalKey;
+  /** Resolve every joiner waiting on this Subscription with the canonical subId. */
+  private resolveJoiners;
+  /** Reject every joiner waiting on this Subscription with the given error. */
+  private rejectJoiners;
+  private unsubscribeByLocalKey;
+  private handleMessage;
+  /**
+   * Called once the client transitions to a "ready" state on a fresh
+   * connection. Replays live-query subscriptions and flushes any queued
+   * calls in FIFO order.
+   */
+  private afterReady;
+  private handleResponse;
+  private handleSubscriptionUpdate;
+  /**
+   * Handles a `sub:gone` message: the server no longer tracks this
+   * subscription (e.g. it was fully unregistered while we were disconnected
+   * from the sub-manager). Notify the handle and drop the local entry so a
+   * re-subscribe is required to receive further updates.
+   */
+  private handleSubscriptionGone;
+  private handleClose;
+  private handleError;
+  private startInactivityWatchdog;
+  private stopInactivityWatchdog;
+  /**
+   * Close the current WebSocket and schedule a reconnect via `handleClose`.
+   *
+   * Atomically swaps the old socket's event handlers to no-ops BEFORE
+   * `close()` so a frame in flight at the moment of close cannot fire
+   * `handleMessage` into a half-cleaned state — that was the source of
+   * the "browser says socket is alive but client says disconnected" race.
+   */
+  private closeAndReconnect;
+  private installEnvironmentListeners;
+  private removeEnvironmentListeners;
+  private scheduleReconnect;
+  private computePublicState;
+  private emitState;
+  /** Fire the optional structured lifecycle event; never lets a throwing hook
+   *  break the client. */
+  private emitEvent;
+  private ensureConnected;
+  private send;
+  /** Current W3C traceparent from the optional hook, or undefined. */
+  private traceparent;
+  private cleanup;
+  private generateRequestId;
+}
+//#endregion
+//#region src/db/types_client_rpc.d.ts
+interface ErrorMessage {
+  type: "error";
+  id?: string;
+  error: string;
+  code?: string;
+}
+declare const AuthMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"auth">;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+declare const CallMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"call">;
+  id: z.ZodString;
+  procedure: z.ZodString;
+  input: z.ZodUnknown;
+  minTs: z.ZodOptional<z.ZodString>;
+  trace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SubscribeMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"subscribe">;
+  id: z.ZodString;
+  procedure: z.ZodString;
+  input: z.ZodUnknown;
+  trace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const UnsubscribeMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"unsubscribe">;
+  subId: z.ZodString;
+}, z.core.$strip>;
+declare const ClientMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+  type: z.ZodLiteral<"auth">;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"call">;
+  id: z.ZodString;
+  procedure: z.ZodString;
+  input: z.ZodUnknown;
+  minTs: z.ZodOptional<z.ZodString>;
+  trace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"subscribe">;
+  id: z.ZodString;
+  procedure: z.ZodString;
+  input: z.ZodUnknown;
+  trace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"unsubscribe">;
+  subId: z.ZodString;
+}, z.core.$strip>]>;
+type AuthMessage = z.infer<typeof AuthMessageSchema>;
+type CallMessage = z.infer<typeof CallMessageSchema>;
+type SubscribeMessage = z.infer<typeof SubscribeMessageSchema>;
+type UnsubscribeMessage = z.infer<typeof UnsubscribeMessageSchema>;
+type ClientMessage = z.infer<typeof ClientMessageSchema>;
+declare const ConnectedMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"connected">;
+  sessionId: z.ZodString;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const AuthSuccessMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"auth:success">;
+  userId: z.ZodString;
+  extra: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const AuthFailedMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"auth:failed">;
+  message: z.ZodString;
+  extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ResponseMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"response">;
+  id: z.ZodString;
+  success: z.ZodBoolean;
+  data: z.ZodOptional<z.ZodUnknown>;
+  error: z.ZodOptional<z.ZodString>;
+  code: z.ZodOptional<z.ZodString>;
+  subId: z.ZodOptional<z.ZodString>;
+  ts: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const SubscriptionUpdateMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"sub:update">;
+  subId: z.ZodString;
+  data: z.ZodUnknown;
+  dataHash: z.ZodOptional<z.ZodString>;
+  ts: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Notifies a client that a subscription is no longer tracked on the server
+ * and will not receive further updates. Sent when, during a sub-manager
+ * recovery cycle, the registration record could not be found (e.g. another
+ * app-server instance fully unregistered the sub while we were disconnected).
+ * The client may choose to re-subscribe or surface the state to the user.
+ */
+declare const SubscriptionGoneMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"sub:gone">;
+  subId: z.ZodString;
+  reason: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Server-driven liveness signal. Sent when the channel has been idle for
+ * the configured app-ping interval (default 15s) and again after every
+ * outbound message. Pure no-op for the client: receiving any message
+ * (including this one) resets the client's inactivity watchdog. The client
+ * does NOT reply.
+ */
+declare const ServerPingMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"ping">;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ServerMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+  type: z.ZodLiteral<"connected">;
+  sessionId: z.ZodString;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"auth:success">;
+  userId: z.ZodString;
+  extra: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"auth:failed">;
+  message: z.ZodString;
+  extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"response">;
+  id: z.ZodString;
+  success: z.ZodBoolean;
+  data: z.ZodOptional<z.ZodUnknown>;
+  error: z.ZodOptional<z.ZodString>;
+  code: z.ZodOptional<z.ZodString>;
+  subId: z.ZodOptional<z.ZodString>;
+  ts: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"sub:update">;
+  subId: z.ZodString;
+  data: z.ZodUnknown;
+  dataHash: z.ZodOptional<z.ZodString>;
+  ts: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"sub:gone">;
+  subId: z.ZodString;
+  reason: z.ZodOptional<z.ZodString>;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"ping">;
+  build: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+type ConnectedMessage = z.infer<typeof ConnectedMessageSchema>;
+type AuthSuccessMessage = z.infer<typeof AuthSuccessMessageSchema>;
+type AuthFailedMessage = z.infer<typeof AuthFailedMessageSchema>;
+type ResponseMessage = z.infer<typeof ResponseMessageSchema>;
+type SubscriptionUpdateMessage = z.infer<typeof SubscriptionUpdateMessageSchema>;
+type SubscriptionGoneMessage = z.infer<typeof SubscriptionGoneMessageSchema>;
+type ServerPingMessage = z.infer<typeof ServerPingMessageSchema>;
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+declare class AuthenticationError extends Error {
+  extra: Record<string, unknown>;
+  constructor(message: string, extra?: Record<string, unknown>);
+}
+/**
+ * Helper type to check if a procedure is internal.
+ */
+type IsInternal<T> = T extends {
+  internal: infer I;
+} ? (I extends true ? true : false) : false;
+interface Context$1 {
+  requestId: string;
+  /** Authenticated user info */
+  user: {
+    userId: string;
+  };
+}
+//#endregion
+//#region src/client/client.d.ts
+interface ClientOptions {
+  /** WebSocket URL (e.g. ws://localhost:3000/ws) */
+  url: string;
+  /** Auth Info callback */
+  token?: () => Promise<string>;
+  /** Optional: reconnection timeout in ms (default: 180000 = 3 minutes) */
+  reconnectionTimeout?: number;
+  /** Reconnection options */
+  reconnect?: WSClientOptions["reconnect"];
+  /**
+   * Inactivity watchdog. The client never sends a ping itself; the server
+   * emits `{type:"ping"}` while idle and we close+reconnect if no inbound
+   * message arrives within `serverInactivityMs` (default 60s).
+   */
+  heartbeat?: WSClientOptions["heartbeat"];
+  /**
+   * Yields the event loop for `delayMs` after every `everyN` `call()`
+   * invocations. Useful for keeping React renders / GC tasks scheduled
+   * during long synchronous bursts; not load-bearing for the heartbeat.
+   * Default `{ everyN: 100, delayMs: 10 }`. Set `everyN: 0` to disable.
+   */
+  throttle?: WSClientOptions["throttle"];
+  /** Custom log sink; when set, `logLevel` is ignored. See {@link WSClientOptions.logger}. */
+  logger?: WSClientOptions["logger"];
+  /** Level for the default console logger. Default `"warn"` (quiet). */
+  logLevel?: WSClientOptions["logLevel"];
+  /** Optional structured lifecycle events, for client-side metrics. */
+  onEvent?: WSClientOptions["onEvent"];
+  /** OpenTelemetry-agnostic W3C `traceparent` provider; see {@link WSClientOptions.getTraceparent}. */
+  getTraceparent?: WSClientOptions["getTraceparent"];
+  onConnect?: () => void;
+  onDisConnect?: () => void;
+}
+/**
+ * Public state of a live query subscription, exposed via `getState()` and
+ * `onState()` on the handle so React (or any UI) can render a consistent
+ * snapshot via `useSyncExternalStore`.
+ *
+ * - "connecting" — initial subscribe in flight
+ * - "success"    — subscribed, last server data is in `data`
+ * - "stale"      — was successful, transport dropped; keeping last `data`
+ *                  until the resubscribe completes
+ * - "loading"    — `refetch()` triggered an explicit re-subscribe
+ * - "error"      — subscribe failed or server sent `sub:gone`
+ */
+type LiveQueryStatus = "connecting" | "success" | "stale" | "loading" | "error";
+interface LiveQueryState<T> {
+  data: T | undefined;
+  status: LiveQueryStatus;
+  error: Error | null;
+}
+interface LiveQueryHandle<T> {
+  /** Get current cached data (legacy convenience getter). */
+  get(): T | undefined;
+  /** Snapshot of `{ data, status, error }`. Stable between updates. */
+  getState(): LiveQueryState<T>;
+  /**
+   * Listen for state changes (data, status or error). Returns an
+   * unsubscribe function that removes only this listener — the underlying
+   * server subscription stays alive as long as any listener is attached.
+   *
+   * Suitable for `useSyncExternalStore`.
+   */
+  onState(listener: () => void): () => void;
+  /** Listen for data-only changes. Returns listener-removal fn. */
+  onData(callback: (data: T) => void): () => void;
+  /** Force a re-subscribe round-trip. */
+  refetch(): void;
+  /** Unsubscribe from the server (drops listeners too). */
+  unsubscribe(): void;
+}
+/**
+ * Create a fully typed RPC client with WebSocket transport.
+ */
+declare function createClient<AppRouter extends Router<Record<string, AnyProcedure<TContext>>, TContext>, TContext = unknown, TProcedures extends Record<string, AnyProcedure<TContext>> = AppRouter["procedures"]>(options: ClientOptions): ClientFromProcedures<TProcedures, TContext> & WSClientMethods;
+/**
+ * WebSocket client methods.
+ */
+interface WSClientMethods {
+  /** Connect to the WebSocket server */
+  connect(): Promise<void>;
+  /** Disconnect from the server */
+  disconnect(): void;
+  /** Check if connected and authenticated */
+  isReady(): boolean;
+  /** Check if authenticated */
+  isAuthenticated(): boolean;
+  /** Check if anonymouse */
+  isAnonymouse(): boolean;
+  /**
+   * The authenticated user id reported by the server on `auth:success`, or
+   * null when anonymous/unauthenticated. This is the auth-tier identity,
+   * NOT the server-side `queryIdentity` (which is the cache/subscription
+   * segmentation key and is not exposed to the client).
+   */
+  getAuthUserId(): string | null;
+  /** Subscribe to client connection state transitions. Returns unsubscribe fn. */
+  onState(listener: (s: ClientPublicState) => void): () => void;
+  /** Snapshot of the current public state. */
+  getPublicState(): ClientPublicState;
+}
+/**
+ * Client type from procedures.
+ * Filters internal procedures and creates appropriate methods.
+ * Query procedures get an additional liveQuery() method for real-time subscriptions.
+ */
+type ClientFromProcedures<TProcedures extends Record<string, AnyProcedure<TContext>>, TContext = unknown> = { [K in keyof TProcedures as IsInternal<TProcedures[K]> extends true ? never : K]: TProcedures[K] extends {
+  procedureType: "query";
+} ? {
+  query: (input: InputOf<TProcedures[K]>) => Promise<OutputOf<TProcedures[K]>>;
+  liveQuery: (input: InputOf<TProcedures[K]>) => LiveQueryHandle<OutputOf<TProcedures[K]>>;
+} : TProcedures[K] extends {
+  procedureType: "mutation";
+} ? {
+  mutate: (input: InputOf<TProcedures[K]>, opts?: CallOptions) => Promise<OutputOf<TProcedures[K]>>;
+} : TProcedures[K] extends {
+  procedureType: "action";
+} ? {
+  action: (input: InputOf<TProcedures[K]>, opts?: CallOptions) => Promise<OutputOf<TProcedures[K]>>;
+} : never };
+/**
+ * Optional call options forwarded to the transport layer.
+ */
+interface CallOptions {
+  /**
+   * Fired the first time the request leaves the queue and is actually
+   * sent on the wire. If the call was already sent immediately (client
+   * was ready at call time), this is invoked synchronously.
+   *
+   * Used by `useMutation` to flip `state` from "queued" → "loading".
+   */
+  onSend?: () => void;
+}
+//#endregion
+//#region src/client/caller_client.d.ts
+interface CallerOptions<TContext = unknown> {
+  isInternal?: boolean;
+  inContext: string;
+}
+/**
+ * Create a server-side caller that bypasses HTTP/WebSocket.
+ *
+ * For in-memory calls, input validation is skipped (data is already a JS object).
+ * Query procedures also get a liveQuery() method for server-side use.
+ *
+ * `init` requires the shared Redis-backed query cache, so every read path —
+ * `query`, `runQuery`, and `liveQuery` — behaves like a normal client procedure
+ * call: it checks cache freshness first and only falls back to executing the
+ * query on a miss/stale entry (see runCachedQuery and runCachedQueryInParent).
+ * `runQuery` keeps joining the parent snapshot/readSet (or opening a fresh
+ * routed read for action/job parents), so nested reads stay consistent with the
+ * parent and mutations keep reads-your-writes.
+ */
+declare function createCaller<AppRouter extends Router<Record<string, AnyProcedure<TContext>>, TContext>, TContext = unknown, TProcedures extends Record<string, AnyProcedure<TContext>> = AppRouter["procedures"]>(options: CallerOptions<any>): CallerFromProcedures<TProcedures, TContext>;
+/**
+ * Caller type from procedures (includes internal procedures).
+ * Query procedures also have liveQuery() for server-side use.
+ */
+type CallerFromProcedures<TProcedures extends Record<string, AnyProcedure<TContext>>, TContext = unknown> = { [K in keyof TProcedures]: TProcedures[K] extends {
+  procedureType: "query";
+} ? {
+  query: (input: InputOf<TProcedures[K]>, serverCtx: TContext) => Promise<OutputOf<TProcedures[K]>>;
+  liveQuery: (input: InputOf<TProcedures[K]>, serverCtx: TContext) => Promise<LiveResult<OutputOf<TProcedures[K]>>>;
+  runQuery: (input: InputOf<TProcedures[K]>, ctx: ParentCtx<TContext>) => Promise<OutputOf<TProcedures[K]>>;
+} : TProcedures[K] extends {
+  procedureType: "mutation";
+} ? {
+  mutate: (input: InputOf<TProcedures[K]>, serverCtx: TContext) => Promise<OutputOf<TProcedures[K]>>;
+  runMutation: (input: InputOf<TProcedures[K]>, ctx: ParentCtx<TContext>) => Promise<OutputOf<TProcedures[K]>>;
+} : TProcedures[K] extends {
+  procedureType: "action";
+} ? {
+  action: (input: InputOf<TProcedures[K]>, serverCtx: TContext) => Promise<OutputOf<TProcedures[K]>>;
+} : TProcedures[K] extends {
+  procedureType: "job";
+} ? {
+  run: (input: InputOf<TProcedures[K]>, serverCtx: TContext) => Promise<OutputOf<TProcedures[K]>>;
+} : never } & {
+  init: (config: CallerClientInitConfig<TContext>) => Promise<void>;
+};
+type CallerClientInitConfig<TContext = unknown> = {
+  db: SupaliveDb;
+  storage: ObjectStorage;
+  scheduler: JobClient;
+  /**
+   * Observability so standalone internal calls log under the configured logger
+   * (a per-procedure child). Required — a caller with no running server (e.g. a
+   * CLI seed) passes a console-backed shim. Nested runQuery/runMutation always
+   * inherit the parent handler's log instead.
+   */
+  obs: CallerObservability;
+  /**
+   * Shared query cache (Redis-backed) — REQUIRED. Every caller read path
+   * (`query`, `runQuery`, `liveQuery`) goes cache-first with the SAME
+   * identity/freshness model as a client one-shot (see runCachedQuery /
+   * runCachedQueryInParent) and writes recomputed results back.
+   */
+  cache: CacheLayer;
+  /**
+   * Oldest retained commit-log ts (retention watermark) — the guard for the
+   * cache-freshness scan. The running server passes the live sub-manager
+   * watermark; a CLI seed (no server, nothing pruned) passes `() => 0n`.
+   */
+  getMinRetainedTs: () => bigint;
+  /**
+   * Same identity resolver as the server (`SupaliveServerConfig.getUserId`), so
+   * internal cache keys segment identically to client WS/HTTP queries — a
+   * nested/standalone call shares cache entries with the equivalent client
+   * query. Return `null` for anonymous (the cache's anonymous identity
+   * segment).
+   */
+  getUserId: (ctx: TContext | undefined) => string | null;
+};
+/**
+ * Caller type from router.
+ */
+type CallerFromRouter<TRouter extends Router<any, any>> = CallerFromProcedures<TRouter["procedures"]>;
+//#endregion
+export { ActionProcedures as $, shouldTrackSchema as $n, PredicateSchema as $r, ResultOf as $t, ResponseMessage as A, ComputedDataType as An, UpdateSubscriptionReadSetResult as Ar, QueryFn as At, SubscriptionUpdateMessage as B, OverrideField as Bn, DEFAULT_RETRY as Br, IncomingJobRequest as Bt, ClientMessage as C, jsonContains as Cn, UnregisterSubscriptionParams as Cr, MutationConfig as Ct, Context$1 as D, ActionArgs as Dn, UnregisterSubscriptionsResult as Dr, OutputOf as Dt, ConnectedMessageSchema as E, matchesPredicate as En, UnregisterSubscriptionsParams as Er, MutationProcedure as Et, ServerPingMessageSchema as F, IndexDefinition as Fn, CachedPgMetadataSchema as Fr, createMutationBuilder as Ft, ClientLogLevel as G, SchemaCodecs as Gn, NO_RETRY as Gr, ScheduleHandle as Gt, UnsubscribeMessage as H, QueryArgs as Hn, LeafPredicateSchema as Hr, JobScheduler as Ht, SubscribeMessage as I, InferSchema as In, CommitLogEntry as Ir, createQueryBuilder as It, HeartbeatOptions as J, SchemaDefinition as Jn, OrPredicate as Jr, sleep as Jt, ClientLogger as K, SchemaColumnMapping as Kn, OccAbortError as Kr, ScheduledJobDef as Kt, SubscribeMessageSchema as L, InsertData as Ln, CommitTs as Lr, DevScheduler as Lt, ServerMessage as M, ComputedFieldConfig as Mn, AndPredicateSchema as Mr, TypeOf as Mt, ServerMessageSchema as N, DeclarativeIndex as Nn, BigIntSchema as Nr, createActionBuilder as Nt, ErrorMessage as O, ColumnCodec as On, UpdateSubscriptionReadSetParams as Or, QueryConfig as Ot, ServerPingMessage as P, DefineSchemaConfig as Pn, CachedPgMetadata as Pr, createJobBuilder as Pt, createConsoleLogger as Q, schemaRegistry as Qn, Predicate as Qr, QueryDefinition as Qt, SubscriptionGoneMessage as R, Model as Rn, CompareOperator as Rr, DevSchedulerOptions as Rt, CallMessageSchema as S, normalizeToBytes as Si, buildPredicateSql as Sn, RegisterSubscriptionResult as Sr, JobProcedure as St, ConnectedMessage as T, jsonPathExtract as Tn, UnregisterSubscriptionResult as Tr, MutationFn as Tt, UnsubscribeMessageSchema as U, ReturnLiveQuery as Un, LiveResult as Ur, QStashScheduler as Ut, SubscriptionUpdateMessageSchema as V, Prettify as Vn, LeafPredicate as Vr, JobClient as Vt, ClientEvent as W, ReturnQuery as Wn, MutationResult as Wr, QStashSchedulerOptions as Wt, WSClientOptions as X, defineComputedField as Xn, PointRead as Xr, DefsToMap as Xt, RPCError as Y, StoredSchemaColumnsOptions as Yn, OrPredicateSchema as Yr, AnyQueryDef as Yt, WsClientManager as Z, defineSchema as Zn, PointReadSchema as Zr, ParamsOf as Zt, AuthMessageSchema as _, WriteEntrySchema as _i, JsonOpOptions as _n, InvalidateWritesetParams as _r, HandlerLogger as _t, createCaller as a, RangeRead as ai, EMPTY_EPHEMERAL_KEYS as an, LazyCommitTsParam as ar, PublicProcedures as at, AuthenticationError as b, bytesFromJson as bi, PaginationClause as bn, RegisterSubscriptionParams as br, JobCtx as bt, ClientOptions as c, RawPointReadSchema as ci, EphemeralKeyNotFoundError as cn, RawClient as cr, Router as ct, LiveQueryStatus as d, RawReadEntry as di, EphemeralStore as dn, CacheLayer as dr, ActionConfig as dt, QueryCacheEntry as ei, _resetGlobalDefs as en, tableNameToId as er, AppRouter as et, WSClientMethods as f, RawReadEntrySchema as fi, EphemeralWriter as fn, IORedisClient as fr, ActionCtx as ft, AuthMessage as g, WriteEntry as gi, JsonHasKeyMultiOptions as gn, InvalidateEphemeralResult as gr, ContextOf as gt, AuthFailedMessageSchema as h, RetryConfig as hi, JsonContainsOptions as hn, InvalidateEphemeralParamsSchema as hr, AnyProcedure as ht, CallerOptions as i, QuerySpec as ii, TxContext as in, DbType as ir, ProcedureNames as it, ResponseMessageSchema as j, ComputedField as jn, AndPredicate as jr, QueryProcedure as jt, IsInternal as k, ComputedCodec as kn, UpdateSubscriptionReadSetParamsSchema as kr, QueryCtx as kt, LiveQueryHandle as l, RawRangeRead as li, EphemeralReader as ln, SqlBuilder as lr, getContextRegistry as lt, AuthFailedMessage as m, ReadEntrySchema as mi, IdAndCommitTs as mn, InvalidateEphemeralParams as mr, ActionProcedure as mt, CallerFromProcedures as n, QueryCacheMetadata as ni, DbReader as nn, Database as nr, JobProcedures as nt, CallOptions as o, RangeReadSchema as oi, EPHEMERAL_DEFAULT_TTL_SECONDS as on, PooledClient as or, QueryProcedures as ot, createClient as p, ReadEntry as pi, createMemoryEphemeralStore as pn, AffectedSubscription as pr, ActionFn as pt, ClientPublicState as q, SchemaColumnsOptions as qn, OccConflictError as qr, SupaliveDb as qt, CallerFromRouter as r, QueryCacheMetadataSchema as ri, DbWriter as rn, DbQueryResult as rr, MutationProcedures as rt, ClientFromProcedures as s, RawPointRead as si, EphemeralDecodeError as sn, PreparedQueries as sr, RegisteredProcedure as st, CallerClientInitConfig as t, QueryCacheEntrySchema as ti, defineQuery as tn, CoreInitLockCtx as tr, ContextRegistry as tt, LiveQueryState as u, RawRangeReadSchema as ui, EphemeralSetOptions as un, TxDatabase as ur, router as ut, AuthSuccessMessage as v, WriteOp as vi, OrderByOptions as vn, InvalidateWritesetParamsSchema as vr, HandlerObservability as vt, ClientMessageSchema as w, jsonPathExists as wn, UnregisterSubscriptionParamsSchema as wr, MutationCtx as wt, CallMessage as x, normalizeIdToBytes as xi, QueryBuilder as xn, RegisterSubscriptionParamsSchema as xr, JobFn as xt, AuthSuccessMessageSchema as y, WriteOpSchema as yi, OrderDirection as yn, InvalidateWritesetResult as yr, JobConfig as yt, SubscriptionGoneMessageSchema as z, MutationArgs as zn, CompareOperatorSchema as zr, EnqueueOptions as zt };
+//# sourceMappingURL=index-CzW0TkpK.d.ts.map