@lunora/do 1.0.0-alpha.109 → 1.0.0-alpha.110

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { SchemaLike, DatabaseWriterLike, CrossShardReadArgs, CdcChange, FilterClause, ExportRow, MigrationDirection, ReactiveCache, ShapeProbeCounters, GlobalPollCounters, ReactiveCacheOptions, ShardSocketLike, TransactionHeadroomTracker, LifecycleDispatchInfo, MigrationRunResult, SearchBackfillProgress, TableIndexInfo, ColumnMeta, AdvisoryFinding, AdvisorProcedure, RlsPoliciesResult, MaskPoliciesResult, StorageRulesResult, StudioFeaturesResult, FlagsResult, SubscriptionIdentity, QueuesResult, WorkflowsResult, ImportShardResult, ShardRankPageResult, SubscriptionQuery, ShapeSubscriptionQuery, MutationDelta, KeyRange, ResolvedShape, ShapeRow, TtlSweepSpec, TransactionLimits, IndexKeyEntry, SqlExec, CdcChangeKey } from '@lunora/shard-engine';
+import { SchemaLike, DatabaseWriterLike, CrossShardReadArgs, CdcChange, FilterClause, ExportRow, MigrationDirection, ReadFootprint, DependencyTracker, ReactiveCache, ShapeProbeCounters, GlobalPollCounters, ReactiveCacheOptions, ShardSocketLike, TransactionHeadroomTracker, LifecycleDispatchInfo, MigrationRunResult, SearchBackfillProgress, TableIndexInfo, ColumnMeta, AdvisoryFinding, AdvisorProcedure, RlsPoliciesResult, MaskPoliciesResult, StorageRulesResult, StudioFeaturesResult, FlagsResult, SubscriptionIdentity, QueuesResult, WorkflowsResult, ImportShardResult, ShardRankPageResult, SubscriptionQuery, ShapeSubscriptionQuery, MutationDelta, KeyRange, ResolvedShape, ShapeRow, TtlSweepSpec, TransactionLimits, IndexKeyEntry, SqlExec, CdcChangeKey } from '@lunora/shard-engine';
 export { type AdvisorProcedure, type AdvisoryFinding, type AggregateIndexDefinitionLike, type DataMigrationLike, type DatabaseWriterLike, type ExportRow, type ExternalSourceLike, type FlagsResult, type ImportShardResult, type KeyRange, type MaskPoliciesResult, type MigrationRunResult, type MutationDelta, type QueuesResult, REPROJECTION_MIGRATION_PREFIX, type RankIndexDefinitionLike, type RlsPoliciesResult, type SchedulerLike, type SchemaLike, type SearchBackfillProgress, type ShardRankPageResult, type SourceClientLike, type SqlExec, type StorageRulesResult, type StudioFeaturesResult, type SystemReaderStorageLike, type TransactionHeadroomTracker, UNVOUCHABLE_DEP, type ValidatorLike, type WhereInput, type WorkflowsResult, type WriteHook, applyCdcChanges, assertShapeShardable, backfillSearchIndexes, buildReprojectionMigration, clearMemoryTables, countLegacyRows, createReadFootprint, createShardCtxDb, exportShardRows, importShardRows, isSourceDue, markUnvouchableReads, pullExternalSourceIncrementalTick, pullExternalSourceTick, reprojectionMigrationId, reprojectionTables, runDataMigration, runShardMigrations, subscriptionListDeltas } from '@lunora/shard-engine';
-import { DatabaseInstrumentation, MetricHistoryOptions, LogEventInput, ContextLogLevel, TraceAnchor, ContextTracer, ContextFetch, ContextMetrics } from '@lunora/observability';
+import { ContextLogLevel, DatabaseInstrumentation, MetricHistoryOptions, LogEventInput, TraceAnchor, ContextTracer, ContextFetch, ContextMetrics } from '@lunora/observability';
 import { DrizzleSqliteDODatabase } from 'drizzle-orm/durable-sqlite';
 export { type ShardPlatform, type WorkerPlatform, type WorkerPlatformOptions, createShardAlarms, createShardDirectory, createShardHost, createShardKvStore, createShardPlatform, createSocketHost, createWorkerPlatform } from '@lunora/platform-cloudflare';
 /**
@@ -744,24 +744,95 @@ type ClientMutationClass = {
   kind: "already" | "gap" | "next";
 };
 /**
- * Optional shard-level configuration passed through `super(state, env, …)`.
- * Reserved as a bag rather than positional args so subclasses don't break
- * when new knobs land. Today the only knob is the reactive cache; future
- * additions should keep the same shape (per-feature options object).
+ * The read-set / cache-hit attribution for ONE `/rpc` dispatch, filled in by
+ * {@link ShardDO.runCachedQuery} and read back by {@link ShardDO.recordRequestLog}.
+ *
+ * A mutable object THREADED BY VALUE rather than a `currentRequest*` field on
+ * the instance, for the same reason `dispatchHeadroom` and `dispatchTrace`
+ * already are: a Durable Object serves concurrent `/rpc` dispatches, and every
+ * one of these values is written after the handler's awaits. Off a shared field
+ * they were whatever the LAST dispatch to resolve wrote — so the request log
+ * filed one request's cache hit and read tables under another's, and a sibling's
+ * prologue/epilogue could blank them out entirely. Both fields stay `undefined`
+ * when the dispatch never reached the cache (a write/action, a cache-less shard,
+ * or a query that fell through the re-entry guard) — the request log renders
+ * that as "unknown" rather than asserting a read set.
+ */
+interface QueryAttribution {
+  cacheHit?: boolean;
+  readTables?: Set<string>;
+}
+/**
+ * The reactive-cache read capture for ONE query dispatch: the dependency
+ * tracker the cache indexes the entry by, plus the range footprint its
+ * range-precise invalidation reads.
+ *
+ * Minted by {@link ShardDO.runCachedQuery} and threaded BY VALUE — handed to
+ * its `run` callback, on through `handleRpc`'s fourth parameter, and into the
+ * generated `buildCtx`, which binds it into the ctx-db read hooks via
+ * {@link ShardDO.getCtxDbReadHook} / {@link ShardDO.getCtxDbReadRangeHook}. It
+ * is NOT an instance field: a Durable Object serves concurrent `/rpc`
+ * dispatches, and a shared field holds one capture for all of them — the second
+ * query's reads would land in the first one's dep set and the second would be
+ * skipped by the re-entry guard entirely (never read from the cache, never
+ * stored).
+ *
+ * `AsyncLocalStorage` would carry it implicitly, but workerd only enables ALS
+ * under `nodejs_compat` and shard DOs run the slimmer `sqlite_compat` profile —
+ * see the header of `@lunora/shard-engine`'s `dependency-tracker.ts`.
+ */
+interface QueryReadScope {
+  /** Range footprint for this dispatch — the `onReadRange` channel. */
+  footprint: ReadFootprint;
+  /** Dependency tracker for this dispatch — the `onRead` channel. */
+  tracker: DependencyTracker;
+}
+/**
+ * Shard-level configuration passed through `super(state, env, …)` by the
+ * generated subclass, which sources every key from the app's
+ * `createShardDO(config)` argument. A bag rather than positional args so
+ * subclasses don't break when a knob lands.
  */
 interface ShardDOOptions {
+  /**
+   * Whether every writer this shard builds spreads {@link ShardDO.ctxDbTuning}.
+   * The emitter sets it, because it is the only thing that can see inside the
+   * generated `buildCtx` and the admin/maintenance writers to know.
+   *
+   * Left unset (a hand-written subclass), {@link ShardDO.recordChangedTable}
+   * keeps its coarse per-table invalidation backstop, so a writer that never
+   * received the cache cannot serve a pre-write read. Set wrongly, it would
+   * disable that backstop — which is why it is declared rather than inferred
+   * from a call to the accessor.
+   */
+  ctxDbCacheWired?: boolean;
+  /**
+   * Ceiling on the join keys one relation-crossing `where` predicate may pull
+   * back via semijoin pre-resolution before failing closed. Reaches
+   * `createShardCtxDb` through {@link ShardDO.ctxDbTuning}; `undefined` keeps
+   * the engine default (`DEFAULT_MAX_RELATION_KEYS`).
+   */
+  maxRelationKeys?: number;
   /**
    * Enable the per-shard reactive query cache. When provided, the dispatch
-   * path uses {@link ShardDO.runCachedQuery} to memoize query results by
-   * `(functionPath, stable-stringified args)`. Omit to keep the legacy
-   * behavior (every dispatch re-runs the handler).
+   * path routes every registered `query` through {@link ShardDO.runCachedQuery},
+   * memoizing results by `(identity, functionPath, stable-stringified args)`.
+   * Omit for the zero-overhead default (every dispatch re-runs the handler).
    *
-   * The cache is invisible to the WS subscription bridge: invalidations
-   * land via the ctx-db write hooks (`@lunora/do`'s `createShardCtxDb`
-   * `cache` option) BEFORE the broadcast goes out, so subscribers that
-   * re-run their queries in response always observe the post-write state.
+   * The cache is invisible to the WS subscription bridge: invalidations land
+   * via the ctx-db write hooks (the `cache` option {@link ShardDO.ctxDbTuning}
+   * supplies) BEFORE the broadcast goes out, so subscribers that re-run their
+   * queries in response always observe the post-write state.
    */
   reactiveCache?: ReactiveCacheOptions;
+  /**
+   * Resolution policy for relation-crossing `where` predicates whose child is
+   * co-located in this shard — `"auto"` (cost-based, the engine default),
+   * `"always"` (inline correlated EXISTS) or `"never"` (universal semijoin).
+   * All three return identical rows. Reaches `createShardCtxDb` through
+   * {@link ShardDO.ctxDbTuning}.
+   */
+  relationExistsPushDown?: "always" | "auto" | "never";
 }
 /**
  * Threshold at which a `__root__` DO triggers the size warning. 1 GiB —
@@ -900,15 +971,14 @@ declare abstract class ShardDO {
   protected state: ShardDOState;
   protected env: unknown;
   /**
-   * Opt-in per-shard reactive query cache. When the subclass passes
-   * `ReactiveCacheOptions` to `super(state, env, { reactiveCache: { … } })`
-   * the cache is instantiated here and exposed to subclasses via
-   * `runCachedQuery`; when omitted (today's default) it stays
-   * undefined and the dispatch path runs with zero cache overhead.
+   * Opt-in per-shard reactive query cache. Instantiated when the generated
+   * subclass passes `reactiveCache` through
+   * `super(state, env, { reactiveCache: { … } })`; otherwise undefined and the
+   * dispatch path runs with zero cache overhead.
    *
-   * The cache is per-shard and in-memory only — it is lost on DO restart
-   * and on workerd hibernation. That's fine: a cold shard simply re-runs
-   * the query on the first call, just like it does today.
+   * The cache is per-shard and in-memory only — it is lost on DO restart and
+   * on workerd hibernation. That's fine: a cold shard simply re-runs the query
+   * on the first call.
    */
   protected readonly reactiveCache: ReactiveCache | undefined;
   /**
@@ -933,6 +1003,21 @@ declare abstract class ShardDO {
    * changelog proved their table had not moved.
    */
   protected globalPoll: GlobalPollCounters;
+  /** ctx-db relation knobs from {@link ShardDOOptions}, handed on by {@link ShardDO.ctxDbTuning}. */
+  private readonly ctxDbRelationOptions;
+  /**
+   * Whether {@link ShardDO.ctxDbTuning} has been consulted, i.e. whether the
+   * subclass's `createShardCtxDb` call is wired to the precise, per-row
+   * invalidation half of the cache contract.
+   *
+   * It gates a coarse fallback in {@link ShardDO.recordChangedTable}: a shard
+   * whose writer never received the cache would otherwise keep serving
+   * memoized results across writes — stale reads, silently. The fallback drops
+   * every entry on a written table, which is strictly more invalidation than
+   * the wired path does, so the two never disagree about correctness; only
+   * about hit rate.
+   */
+  private readonly ctxDbCacheWired;
   /**
    * The host-neutral engine runner. `fetch` and `alarm` delegate through it, so
    * the dispatch entry points name a platform contract rather than a Durable
@@ -1369,32 +1454,15 @@ declare abstract class ShardDO {
    * raw events — production aggregation ships to a collector via the sink.
    */
   private readonly metricSeries;
-  /**
-   * In-flight dependency tracker for the currently-executing query. Set by
-   * `runCachedQuery` so the ctx-db hooks (wired via `onRead`) can
-   * stamp deps without threading the tracker explicitly through every
-   * generated handler signature. Cleared in the `finally` of the same
-   * call so a leaked tracker can never bleed into a sibling RPC.
-   */
-  private currentTracker;
-  /**
-   * In-flight range footprint (the `onReadRange` channel) for the
-   * currently-executing cached query. Set by `runCachedQuery` alongside
-   * `currentTracker` so `getCtxDbReadRangeHook` — and the range-marking half
-   * of `getCtxDbReadHook` — can stamp it without threading it explicitly
-   * through every generated handler signature. `ReactiveCache.run`'s ranges
-   * thunk reads it lazily, AFTER the handler resolves, so it always sees the
-   * footprint's final state. Cleared in the same `finally` as `currentTracker`.
-   */
-  private currentReadFootprint;
   /**
    * Tables the in-flight dispatch full-scanned (read via `SCAN_DEP`, no index
    * / point lookup). Allocated at the top of each `/rpc` dispatch and drained
    * into `recordFunctionCall` once the handler returns, so the durable
    * `__lunora_metrics_scans` attribution can pin a slow function to the
-   * table(s) it scanned. Independent of `currentTracker` (which only exists
-   * when the reactive cache is enabled), so the causal signal is collected
-   * even on a cache-less shard. Stamped by `getCtxDbReadHook`.
+   * table(s) it scanned. Independent of the per-dispatch
+   * {@link QueryReadScope} (which only exists when the reactive cache is
+   * enabled), so the causal signal is collected even on a cache-less shard.
+   * Stamped by `getCtxDbReadHook`.
    */
   private currentScannedTables;
   /**
@@ -1414,18 +1482,6 @@ declare abstract class ShardDO {
    * down with it.
    */
   private currentTransactionHeadroom;
-  /**
-   * Read-tables + cache-hit captured for the current `/rpc` dispatch, so the
-   * dispatch site can fold them into the durable request log
-   * (`request-log.ts`). Populated by `runCachedQuery` — the one place that
-   * both holds the per-query dependency tracker AND learns whether the
-   * reactive cache served the result — and reset per request in `fetch`.
-   * `undefined`/empty when the reactive cache is disabled or the path is a
-   * write/action (which doesn't run through the cache), which is exactly why
-   * the request log treats those fields as "unknown" rather than asserting a
-   * read set on the hot path.
-   */
-  private currentRequestReadTables;
   /**
    * Per-DISTINCT-statement SQL samples collected during the current `/rpc`
    * dispatch by the instrumented `sql` getter, keyed by the raw query text.
@@ -1471,8 +1527,6 @@ declare abstract class ShardDO {
    * leaderboard contribution reads as partial rather than complete.
    */
   private currentStmtSamplesTruncated;
-  /** Whether the current dispatch's cached query was served from cache; `undefined` until `runCachedQuery` resolves one. */
-  private currentRequestCacheHit;
   constructor(state: ShardDOState, env: unknown, options?: ShardDOOptions);
   /**
    * Worker-side fetch entry point. Delegates to the host-neutral
@@ -1534,8 +1588,17 @@ declare abstract class ShardDO {
    * their own tracker (`dispatchLifecycle`, `handleRunAs`) omit it and the
    * codegen subclass falls back to `this.transactionHeadroom()`, unchanged from
    * before this parameter existed.
+   *
+   * `scope` is the same shape of BY-VALUE thread for the reactive cache: the
+   * `/rpc` query path routes through {@link ShardDO.runCachedQuery}, which
+   * mints a {@link QueryReadScope} per dispatch and passes it here so the ctx
+   * this dispatch builds stamps reads into ITS OWN tracker and footprint.
+   * Implementations must hand it to `getCtxDbReadHook(scope)` /
+   * `getCtxDbReadRangeHook(scope)` on the `createShardCtxDb(...)` call that
+   * builds the ctx; both factories return unbound (tracker-less) hooks when it
+   * is omitted, which is what every non-cached dispatch passes.
    */
-  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker): Promise<unknown>;
+  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope): Promise<unknown>;
   /**
    * The registered function paths to dispatch on a lifecycle moment —
    * `connect`/`disconnect` per socket, `init` once per Durable Object instance,
@@ -2614,30 +2677,36 @@ declare abstract class ShardDO {
     iterator: (signal: AbortSignal) => AsyncIterable<unknown>;
   };
   /**
-   * Wrap a query handler in the reactive cache. The subclass passes the
-   * function path, parsed args, and a `run` callback that resolves to the
-   * handler's return value. When the cache is configured we key by
-   * `(functionPath, stable-stringified args)`, allocate a fresh dep
-   * tracker, store it on `this.currentTracker` so `getCtxDbReadHook` reads
-   * stamp into it, and restore the prior tracker in `finally`. When the
-   * cache is absent we just call `run()` — same shape, zero overhead.
-   *
-   * Subclasses should ALSO pass `getCtxDbReadHook()` as the `onRead`
+   * Wrap a query handler in the reactive cache. The `/rpc` dispatch path calls
+   * this for every path {@link ShardDO.isQueryFunction} recognises, so a
+   * subclass does NOT wrap its own `handleRpc` — see the re-entry guard below
+   * for why doing both would be worse than doing neither. When the cache is
+   * configured we key by `(identity, functionPath, stable-stringified args)`,
+   * mint a fresh {@link QueryReadScope} (dep tracker + read footprint) and
+   * hand it to `run` — which threads it through `handleRpc` into the ctx the
+   * handler reads through, so this dispatch's reads stamp THIS dispatch's
+   * tracker even while a sibling dispatch is parked on an await. When the
+   * cache is absent we just call `run()` with no scope — same shape, zero
+   * overhead.
+   *
+   * Subclasses must ALSO pass `getCtxDbReadHook(scope)` as the `onRead`
    * option on their `createShardCtxDb(...)` call so the tracker actually
-   * collects deps. Without that wiring the cache will memoize results
-   * with empty dep sets, so writes never invalidate them and stale
-   * results stick around — the {@link ReactiveCache} class is contract-
-   * neutral about who fills `deps`.
-   *
-   * Also allocates a fresh {@link ReadFootprint} alongside the tracker,
-   * stored on `this.currentReadFootprint` so `getCtxDbReadRangeHook()` —
-   * and the range-marking half of `getCtxDbReadHook()` — can stamp it. Its
+   * collects deps. Without that wiring the cache memoizes results with empty
+   * dep sets, so the write hooks never invalidate them — the
+   * {@link ReactiveCache} class is contract-neutral about who fills `deps`,
+   * and dep-less entries survive `invalidate` AND `invalidateTable` alike, so
+   * neither the ctx-db hooks nor the {@link ShardDO.recordChangedTable}
+   * backstop can rescue that omission.
+   *
+   * The scope's {@link ReadFootprint} is the ranges channel:
+   * `getCtxDbReadRangeHook(scope)` — and the range-marking half of
+   * `getCtxDbReadHook(scope)` — stamp it. Its
    * `ranges()` is handed to `reactiveCache.run` as a LAZY 4th argument (a
    * thunk, evaluated only after `run()` resolves), the same deferral
    * `deps` already relies on: the footprint is only complete once the
    * handler has actually run. Subclasses that also want range-precise
-   * invalidation should pass `getCtxDbReadRangeHook()` as `onReadRange` on
-   * the same `createShardCtxDb(...)` call — mirroring `onRead` above. A
+   * invalidation should pass `getCtxDbReadRangeHook(scope)` as `onReadRange`
+   * on the same `createShardCtxDb(...)` call — mirroring `onRead` above. A
    * subclass that only wires `onRead` still works: `ranges()` degrades to
    * `undefined` and every read is treated as a whole-table dependency, per
    * `ReactiveCache.run`'s own default. When `onReadRange` IS wired, a table
@@ -2647,22 +2716,24 @@ declare abstract class ShardDO {
    * method's body. Only a table read EXCLUSIVELY through provable ranges
    * gets range-precise invalidation instead.
    */
-  protected runCachedQuery<R>(functionPath: string, args: Record<string, unknown>, run: () => Promise<R>): Promise<R>;
+  protected runCachedQuery<R>(functionPath: string, args: Record<string, unknown>, run: (scope?: QueryReadScope) => Promise<R>, attribution?: QueryAttribution, outer?: QueryReadScope): Promise<R>;
   /**
    * Returns an `onRead` callback suitable to hand to `createShardCtxDb`'s
-   * `onRead` option. The returned function stamps the in-flight tracker (set
-   * by `runCachedQuery`) when one exists and is a no-op otherwise — so
+   * `onRead` option, BOUND to the dispatch whose {@link QueryReadScope} is
+   * passed in. `runCachedQuery` mints that scope and threads it through
+   * `handleRpc`; a dispatch with no cache scope (a mutation, an action, a
+   * cache-less shard) passes nothing and gets a hook that stamps no deps — so
    * subclasses can wire this hook unconditionally without checking whether
    * the cache is enabled.
    *
    * It ALSO records the table into {@link currentScannedTables} whenever the
-   * read was a full-table scan (the `SCAN_DEP` sentinel). That set is drained
-   * into `recordFunctionCall` after dispatch to build the durable per-function
-   * full-scan attribution — and unlike the tracker, it's collected even when
-   * the reactive cache is off, since the causal signal is independent of
-   * caching.
+   * read was a full-table scan (the `SCAN_DEP` sentinel), scope or no scope.
+   * That set is drained into `recordFunctionCall` after dispatch to build the
+   * durable per-function full-scan attribution — unlike the tracker, it's
+   * collected even when the reactive cache is off, since the causal signal is
+   * independent of caching.
    *
-   * It ALSO marks the table unnarrowable on {@link currentReadFootprint},
+   * It ALSO marks the table unnarrowable on the scope's `footprint`,
    * mirroring `executeSubscription`'s wiring (which hands a single
    * `ReadFootprint`'s `onRead`/`onReadRange` pair straight to `buildCtx`).
    * `ctx-db.ts`'s reader calls this `onRead` and `onReadRange` mutually
@@ -2672,19 +2743,20 @@ declare abstract class ShardDO {
    * "read this table outside a range" signal {@link ReadFootprint.ranges}
    * needs to drop that table from the narrowed set.
    */
-  protected getCtxDbReadHook(): (table: string, idOrScan?: string) => void;
+  protected getCtxDbReadHook(scope?: QueryReadScope): (table: string, idOrScan?: string) => void;
   /**
    * Returns an `onReadRange` callback suitable to hand to
-   * `createShardCtxDb`'s `onReadRange` option, alongside `getCtxDbReadHook()`
-   * as `onRead` on the same call — the pairing `executeSubscription` already
-   * uses via `ReadFootprint`. Stamps the in-flight footprint (set by
-   * `runCachedQuery`) when one exists and is a no-op otherwise, so subclasses
-   * can wire this hook unconditionally regardless of whether the cache is
-   * enabled. Without this wiring `runCachedQuery`'s ranges thunk always
-   * observes an empty footprint and every cached query degrades to the prior
-   * whole-table dependency — safe, just not range-precise.
-   */
-  protected getCtxDbReadRangeHook(): (range: KeyRange) => void;
+   * `createShardCtxDb`'s `onReadRange` option, alongside
+   * `getCtxDbReadHook(scope)` as `onRead` on the same call — the pairing
+   * `executeSubscription` already uses via `ReadFootprint`. Stamps the
+   * footprint of the {@link QueryReadScope} passed in and is a no-op when
+   * none is, so subclasses can wire this hook unconditionally regardless of
+   * whether the cache is enabled. Without this wiring `runCachedQuery`'s
+   * ranges thunk always observes an empty footprint and every cached query
+   * degrades to the prior whole-table dependency — safe, just not
+   * range-precise.
+   */
+  protected getCtxDbReadRangeHook(scope?: QueryReadScope): (range: KeyRange) => void;
   /**
    * Read hook recording which declared indexes a query actually exercises.
    * Two destinations, both stamped here so a single hook serves the live and
@@ -2698,6 +2770,52 @@ declare abstract class ShardDO {
    * to `createShardCtxDb` by the generated subclass.
    */
   protected getCtxDbIndexUseHook(): (table: string, indexName: string) => void;
+  /**
+   * The `createShardCtxDb` options this DO's configuration decides, as one
+   * spreadable slice: the reactive cache (invalidation half of the contract)
+   * plus the two relation-resolution knobs from {@link ShardDOOptions}.
+   *
+   * The generated `buildCtx` spreads this FIRST into its `createShardCtxDb`
+   * call, so a per-request option it sets afterwards still wins:
+   *
+   * ```ts
+   * createShardCtxDb({ ...this.ctxDbTuning(), auth: …, schema, sql, … })
+   * ```
+   *
+   * One accessor rather than three, because it is one decision — "how this
+   * deployment configured its ctx-db" — and the emitter should not have to
+   * grow a line per knob. Only keys the app actually set are present, so
+   * spreading never overwrites an engine default with `undefined`.
+   *
+   * Handing over `cache` is what makes writes invalidate at row + index-range
+   * precision (`ctx-db.ts` calls `cache.invalidate(table, id, indexKeys)` on
+   * every `insert`/`patch`/`replace`/`delete`). EVERY writer the emitter builds
+   * spreads this — the user-facing ctx and all three admin/maintenance writers —
+   * because a writer that skips it leaves post-write reads answering from the
+   * pre-write snapshot.
+   *
+   * Pure: it reports the slice and records nothing. Whether the emitter actually
+   * wired it is a fact the emitter knows statically and declares through
+   * {@link ShardDOOptions.ctxDbCacheWired}; inferring it from a call to this
+   * accessor made reading the slice — in a test, or to log it — silently disarm
+   * the invalidation backstop in {@link ShardDO.recordChangedTable}.
+   */
+  protected ctxDbTuning(): {
+    cache?: ReactiveCache;
+    maxRelationKeys?: number;
+    relationExistsPushDown?: "always" | "auto" | "never";
+  };
+  /**
+   * Whether `functionPath` names a registered `query` — the only kind whose
+   * result may be memoized by the reactive cache.
+   *
+   * The base class has no function registry, so the default is `false`: the
+   * conservative answer, since caching an `action` would skip its outbound
+   * side effects on a hit and caching a `mutation` is meaningless. The
+   * codegen-generated subclass overrides it with the real `LUNORA_FUNCTIONS`
+   * lookup, which is what production dispatch uses.
+   */
+  protected isQueryFunction(_functionPath: string): boolean;
   /**
    * Ceilings for one transaction. The base class uses the engine defaults
    * (sized for a 128 MiB Durable Object isolate); a subclass overrides this
@@ -3547,10 +3665,15 @@ declare abstract class ShardDO {
    * The correlated fields all come from data the dispatch already holds, with
    * no extra hot-path bookkeeping. `tablesWritten` is snapshotted from
    * `pendingChangedTables` by the caller before `flushChangedTables` drains it.
-   * `tablesRead` and `cacheHit` are captured by `runCachedQuery`, so they are
-   * present only for cached query paths — a write/action doesn't run through
-   * the cache, and an instance with the reactive cache disabled never captures
-   * them — and are left empty/`undefined` rather than recomputed here.
+   * `tablesRead` and `cacheHit` arrive in `attribution`, the per-dispatch
+   * object `beginDispatch` minted and `runCachedQuery` filled in — passed BY
+   * VALUE for the same reason `trace` is, since both are read here, after the
+   * handler's awaits, where a shared field belongs to whichever concurrent
+   * dispatch resolved last. They are present only for cached query paths — a
+   * write/action doesn't run through the cache, an instance with the reactive
+   * cache disabled never captures them, and a query that hit the re-entry
+   * guard passed through uncached — and are left empty/`undefined` rather
+   * than recomputed here.
    * `subscriptionsReRun` is left `0`: the write-driven subscription refresh
    * runs off the response path via `waitUntil` (see `flushChangedTables`), so a
    * per-request count isn't available synchronously at this site, and threading
@@ -3711,7 +3834,7 @@ declare abstract class ShardDO {
    * per identity), and a flag read ({@link FLAGS_FUNCTION_PREFIX}) evaluates
    * the provider with the subscriber's identity (per-user targeting). Sharing
    * one socket's result with another would leak one identity's rows/flags to a
-   * different identity, so this predicate gates {@link resolveReactiveOutcomeDeduped}
+   * different identity, so this predicate gates {@link ShardDO.resolveReactiveOutcomeDeduped}
    * shut for them.
    */
   protected isIdentityIndependent(functionPath: string): boolean;
@@ -3835,15 +3958,20 @@ declare abstract class ShardDO {
    * run would have to fan one failure to every sharing socket while preserving
    * the "leave memo untouched ⇒ re-run next flush" contract.
    *
-   * The framework's INTENDED answer to this fan-out already exists: the opt-in
-   * {@link ReactiveCache} (`ShardDOOptions.reactiveCache`). Refreshes run with
-   * an explicit anonymous {@link SubscriptionIdentity}, so the cache key
-   * `reactiveCacheKey(functionPath, args, null)` is identical across all
-   * sockets — N identical subscriptions collapse to ONE handler run plus N
-   * cache hits, with every per-run side effect honored exactly once by design.
-   * Recommended remediation is to document/enable ReactiveCache for
-   * high-fanout shards rather than bolt a second, semantically-divergent dedup
-   * into this loop.
+   * The opt-in {@link ReactiveCache} (`ShardDOOptions.reactiveCache`) does NOT
+   * cover this, despite the shared key shape: it wraps `/rpc` query dispatch
+   * (see {@link ShardDO.runCachedQuery}), while a refresh runs through
+   * `executeSubscription`, which never consults it. It cannot, either — a
+   * subscription's re-run is only half about the value. The other half is the
+   * `tables`/`ranges` footprint it reports, which is what decides whether the
+   * NEXT write re-runs it; a cache hit produces a value with no footprint, so
+   * routing refreshes through the cache would quietly empty every memo's
+   * dependency set and stop the subscription updating at all.
+   *
+   * So this fan-out stands as characterized. Collapsing it needs a dedup that
+   * shares the footprint alongside the value — {@link ShardDO.resolveReactiveOutcomeDeduped}
+   * is that, per flush, for the identity-independent subset — not a second
+   * memo bolted into this loop.
    */
   /**
    * Count and log a subscription-delivery error that its caller is about to
@@ -4493,11 +4621,6 @@ declare abstract class ShardDO {
   private deliverWhisperLocal;
   private readAttachment;
 }
-/**
- * @deprecated Renamed to {@link TelemetrySink} — it carries spans and metrics as
- * well as logs. Kept as an alias so existing import sites keep working.
- */
-type LogSink = TelemetrySink;
 /** Conventional DO instance name, passed to `idFromName` to address the single registry instance. */
 declare const SHARD_REGISTRY_DO_NAME: string;
 /**
@@ -4557,4 +4680,4 @@ declare class ShardRegistryDO {
   /** The in-memory map as a JSON-safe `table → [keys]` object. */
   private serializeTables;
 }
-export { type HibernatableWebSocket, type LogSink, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };
+export { type HibernatableWebSocket, type QueryReadScope, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };