@lunora/do 1.0.0-alpha.97 → 1.0.0-alpha.99

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { SchemaLike, DatabaseWriterLike, CrossShardReadArgs, CdcChange, FilterClause, ExportRow, MigrationDirection, ReactiveCache, ReactiveCacheOptions, ShardSocketLike, TransactionHeadroomTracker, LifecycleDispatchInfo, MigrationRunResult, TableIndexInfo, ColumnMeta, AdvisoryFinding, AdvisorProcedure, RlsPoliciesResult, MaskPoliciesResult, StorageRulesResult, StudioFeaturesResult, FlagsResult, SubscriptionIdentity, QueuesResult, WorkflowsResult, ImportShardResult, ShardRankPageResult, SubscriptionQuery, ShapeSubscriptionQuery, MutationDelta, KeyRange, ResolvedShape, ShapeRow, TtlSweepSpec, TransactionLimits, IndexKeyEntry, SqlExec } 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 ShardRankPageResult, type SourceClientLike, type SqlExec, type StorageRulesResult, type StudioFeaturesResult, type SystemReaderStorageLike, type TransactionHeadroomTracker, type ValidatorLike, type WhereInput, type WorkflowsResult, type WriteHook, applyCdcChanges, assertShapeShardable, buildReprojectionMigration, clearMemoryTables, countLegacyRows, createReadFootprint, createShardCtxDb, exportShardRows, importShardRows, isSourceDue, pullExternalSourceIncrementalTick, pullExternalSourceTick, reprojectionMigrationId, reprojectionTables, runDataMigration, runShardMigrations, subscriptionListDeltas } from '@lunora/shard-engine';
+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';
+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 { DrizzleSqliteDODatabase } from 'drizzle-orm/durable-sqlite';
 export { type ShardPlatform, type WorkerPlatform, type WorkerPlatformOptions, createShardAlarms, createShardDirectory, createShardHost, createShardKvStore, createShardPlatform, createSocketHost, createWorkerPlatform } from '@lunora/platform-cloudflare';
@@ -842,6 +842,14 @@ declare abstract class ShardDO {
    * never trip it.
    */
   protected static readonly GLOBAL_SHAPE_MAX_ROWS = 5e4;
+  /**
+   * How long a `.global()` poll may go without an unconditional membership
+   * pass. Between resyncs the poll trusts the global changelog and skips
+   * unchanged tables; a resync re-reads regardless, so a write that left no
+   * changelog row (another system writing the same database) still surfaces
+   * within this window instead of never.
+   */
+  protected static readonly GLOBAL_SHAPE_RESYNC_MS = 3e4;
   /**
    * Per-socket whisper-topic cap. Topic membership rides the same hibernation
    * attachment as `subs`, so bound it for the same reason — a runaway
@@ -903,6 +911,28 @@ declare abstract class ShardDO {
    * the query on the first call, just like it does today.
    */
   protected readonly reactiveCache: ReactiveCache | undefined;
+  /**
+   * Running read tallies for the shape-poke path, surfaced next to
+   * {@link ShardDO.fanout} on `getFanoutMetrics`. `run` counts the reads this
+   * instance issued to SQLite; `served` counts the ones the per-flush
+   * {@link ShapeDiffCache} answered because another socket had already asked the
+   * identical question. BOTH halves of the diff are counted — the changed-key
+   * scan keyed by `(table, op range)` and the membership probe keyed by
+   * `(effectiveWhere, that same range)` — so the reported sharing rate covers
+   * the work the cache actually does rather than half of it.
+   *
+   * Without the split the sharing is invisible: a flush that collapsed a
+   * hundred reads into one looks exactly like a flush that only ever had one
+   * shape.
+   */
+  protected shapeProbe: ShapeProbeCounters;
+  /**
+   * Running `.global()` poll tallies, reported alongside {@link ShardDO.shapeProbe}.
+   * `run` counts membership drains actually issued to the global backend;
+   * `served` counts the (socket, shape) pairs a tick skipped because the global
+   * changelog proved their table had not moved.
+   */
+  protected globalPoll: GlobalPollCounters;
   /**
    * The host-neutral engine runner. `fetch` and `alarm` delegate through it, so
    * the dispatch entry points name a platform contract rather than a Durable
@@ -1095,6 +1125,13 @@ declare abstract class ShardDO {
    * hot path without needing a separate alarm/cron.
    */
   private lastIdempotencyTrimAt;
+  /**
+   * Wall-clock millis of the last `__cdc_log` retention sweep on this warm
+   * instance, throttling {@link ShardDO.sweepCdcRetention} to at most once per
+   * {@link CDC_SWEEP_INTERVAL_MS}. In-memory like its `__idempotency` twin, so
+   * a fresh instance sweeps on its first coalesced flush.
+   */
+  private lastCdcSweepAt;
   /**
    * Per-request identity envelope forwarded from the runtime via the
    * `x-lunora-identity` JSON header. Stores claims like `email`,
@@ -1235,6 +1272,32 @@ declare abstract class ShardDO {
    * threshold is grounded in real numbers, with no behavior change.
    */
   private readonly fanout;
+  /**
+   * The `.global()` changelog position the last poll tick observed, or
+   * `undefined` on a cold instance. In-memory on purpose: losing it costs one
+   * full re-read pass, which is the safe direction — a stale persisted cursor
+   * would let a tick skip a table that HAD changed.
+   */
+  private globalPollCursor;
+  /**
+   * Set when a shape failed to settle in the last poll tick, forcing the next one
+   * to read every shape unconditionally. See {@link GlobalPollTick.resyncRequested}
+   * for why a shared cursor leaves no cheaper recovery.
+   */
+  private globalResyncRequested;
+  /**
+   * Whether this wake has already re-minted the epoch to seal a rolled-back
+   * timeline. In-memory on purpose — see {@link ShardDO.sealForkedTimeline} for
+   * why the seal is capped at one per wake, and why losing the flag on eviction
+   * is the correct direction.
+   */
+  private forkSealed;
+  /**
+   * Wall-clock millis of the last unconditional `.global()` membership pass.
+   * Bounds how long a write this deployment cannot see in its own changelog —
+   * an out-of-band writer against the global database — can go unnoticed.
+   */
+  private lastGlobalResyncAt;
   /**
    * The runtime's Durable Object namespace binding name (e.g. `"SHARD"`),
    * forwarded as `x-lunora-shard-binding` on every request so a DO can address
@@ -1384,6 +1447,18 @@ declare abstract class ShardDO {
    * attribute only SELECT result sizes as `rowsRead`.
    */
   private currentStmtSamples;
+  /**
+   * The instrumented `sql` proxy built for {@link ShardDO.currentStmtSamples},
+   * and the samples map it was built for.
+   *
+   * `get sql()` is read on essentially every storage call, and a fresh `Proxy`
+   * per read is not only an allocation: the resume path memoizes this shard's
+   * table catalog in a `WeakMap` keyed by the handle, so a new object each read
+   * meant that memo never once hit during a dispatch — it re-scanned
+   * `sqlite_master` every time, which is the 18% of `evaluateResume` the memo
+   * exists to remove.
+   */
+  private instrumentedSql;
   /**
    * Set when `currentStmtSamples` hit {@link MAX_STMT_SAMPLES_PER_DISPATCH}
    * distinct statements and a brand-new shape was dropped this dispatch.
@@ -1701,6 +1776,20 @@ declare abstract class ShardDO {
    * look the migration up and invoke `runDataMigration`.
    */
   protected runShardDataMigration(args: RunShardMigrationArgs): Promise<MigrationRunResult>;
+  /**
+   * Index the rows that predate a `.searchIndex()` into its companion, a
+   * bounded number of pages per call, and report whether anything is left.
+   *
+   * This is the exit from `staged: true`. A staged index is skipped by every
+   * migration pass by design — the option exists for tables too large to walk
+   * during a cold start — so without an explicit run its pre-existing rows are
+   * unsearchable forever. The base class can't reach the project's generated
+   * `schema`, so it reports the op unsupported; the codegen subclass overrides
+   * it to call `backfillSearchIndexes`.
+   */
+  protected runShardSearchBackfill(_options: {
+    maxPages?: number;
+  }): SearchBackfillProgress;
   /**
    * Lazily provision the shard's physical tables before an operation that
    * depends on them existing. The base class has no `schema.ts`, so it does
@@ -1968,19 +2057,64 @@ declare abstract class ShardDO {
    * the wire byte-identical to the pre-epoch format for non-CDC apps.
    */
   protected currentCdcEpoch(): string | undefined;
+  /**
+   * Mint a fresh CDC epoch because a resume claim just proved this shard's
+   * changelog forked under it, and return the new value for the outgoing frame.
+   *
+   * The trigger is a client presenting `sinceEpoch === epoch` with `sinceSeq >
+   * cursor`: it holds a cursor this shard once issued on THIS timeline and can
+   * no longer account for. Only a rollback produces that — in practice a native
+   * PITR restore, which is armed in {@link handlePitrAdminOp}.
+   *
+   * **Why the signal has to come from a client.** A restore reverts the whole
+   * SQLite database, `__cdc_meta` included, so the proactive bump `pitrRestore`
+   * performs is rolled back along with everything else — the epoch cannot
+   * detect the one event it exists for. Nothing durable inside a SQLite-backed
+   * Durable Object escapes that: the KV half of `state.storage` is the same
+   * database, and an alarm is a row in it. The only record of the pre-restore
+   * timeline that the restore cannot reach is the cursor each CLIENT cached, so
+   * that is what this reads. Turning one client's refusal into a shard-wide
+   * epoch bump is what extends the protection to clients that reconnect later,
+   * after post-restore writes have climbed the AUTOINCREMENT back past their
+   * own `sinceSeq` and the `sinceSeq > cursor` guard no longer fires for them.
+   *
+   * **What it detects.** Any rollback under a live subscriber base, promptly: a
+   * restore restarts the object (`ctx.abort()`, or the eviction that lets a
+   * deferred restore apply), which drops every hibernated socket, so the whole
+   * subscriber set reconnects with pre-restore cursors while the restored
+   * cursor is still low. The first of them seals the fork for the rest.
+   *
+   * **What it cannot detect.** A rollback on a shard whose clients ALL stay
+   * offline until the cursor has climbed back past their cursors — nobody is
+   * left to present the proof. A shard with no subscribers at all is the
+   * degenerate case of that, and is also the case where nothing is stale.
+   *
+   * **On trusting `sinceSeq`.** It is client-supplied, so a caller that already
+   * knows this shard's epoch can force a bump, and a bump is shard-wide: every
+   * subscriber takes a full snapshot instead of a resume on its NEXT reconnect.
+   * The cost is bounded (the once-per-wake latch below) and deferred — nothing
+   * is pushed and no live subscription is interrupted — and it stays strictly
+   * less than what the same caller can already spend by subscribing without a
+   * `sinceSeq` at all.
+   * @returns the freshly minted epoch, to stamp on the frame this verdict produces
+   */
+  protected sealForkedTimeline(): string;
   /**
    * Decide whether a reconnecting subscription can resume from `sinceSeq`
    * without a full snapshot. Returns the current high-watermark `cursor` plus
    * a `resumable` verdict.
    *
-   * `resumable: true` means `sinceSeq` is within the CDC retention window and
-   * no table in the query's `readSet` changed in `(sinceSeq, cursor]` — the
-   * client's cached value is still current, so the caller emits a lightweight
-   * `resume` frame instead of re-shipping the snapshot.
+   * `resumable: true` means `sinceSeq` is within the CDC retention window,
+   * every entry in the query's `readSet` is one the changelog can speak for,
+   * and none of them changed in `(sinceSeq, cursor]` — the client's cached
+   * value is still current, so the caller emits a lightweight `resume` frame
+   * instead of re-shipping the snapshot.
    *
-   * `resumable: false` means either the log was compacted past `sinceSeq` (a
+   * `resumable: false` means the log was compacted past `sinceSeq` (a
    * retention gap), a read table changed (the client needs the fresh value),
-   * or CDC is off — the caller falls back to the full-snapshot seed.
+   * the read-set contains something the changelog cannot vouch for (see
+   * {@link cdcCanVouchFor}), or CDC is off — the caller falls back to the
+   * full-snapshot seed.
    */
   protected evaluateResume(sinceSeq: number, readSet: Set<string>, sinceEpoch?: string): {
     cursor: number | undefined;
@@ -2989,8 +3123,8 @@ declare abstract class ShardDO {
   private handleAdminRpc;
   /**
    * Dispatch the side-effecting / non-read admin ops that `handleAdminRpc`
-   * doesn't handle inline: the auth-event + mail-capture writes and the native
-   * PITR ops. Returns the op's `Response`, or `undefined` when `functionPath`
+   * doesn't handle inline: the auth-event + mail-capture writes, the search
+   * backfill, and the native PITR ops. Returns the op's `Response`, or `undefined` when `functionPath`
    * isn't one of these (so the caller answers 404). Kept out of
    * `handleAdminRpc` to hold that dispatcher under the complexity budget,
    * mirroring `handlePitrAdminOp`.
@@ -3031,6 +3165,18 @@ declare abstract class ShardDO {
    * untag); a missing or malformed value is a 400 rather than a silent no-op.
    */
   private parseIssueTriagePatch;
+  /**
+   * `__lunora_admin__:backfillSearch` — index the rows that predate this
+   * shard's `.searchIndex()` declarations, `maxPages` pages at a time.
+   *
+   * Bounded rather than run-to-completion because a DO request has a CPU and
+   * wall-clock budget, and the tables `staged: true` exists for are precisely
+   * the ones a single unbounded walk cannot finish. Progress is durable, so an
+   * operator drives it with repeated calls until `done` — `lunora run
+   * '__lunora_admin__:backfillSearch' --args '{"maxPages":20}'` needs no new
+   * CLI surface. Admin-gated by `handleAdminRpc`'s caller.
+   */
+  private handleBackfillSearch;
   /**
    * Record one app-level auth attempt for the auth-failure SLO (PLAN3 §2.3).
    * The worker calls this fire-and-forget (via `waitUntil`) after a top-level
@@ -3247,6 +3393,8 @@ declare abstract class ShardDO {
    * is still an operator asking the database a question.
    */
   private handleGenerateSql;
+  /** The single-shape admin writes (decode args → Response), keyed by function path. */
+  private simpleAdminHandlers;
   /** The AI-assistant admin writes, keyed by function path. */
   private aiAdminHandlers;
   /**
@@ -3858,7 +4006,12 @@ declare abstract class ShardDO {
    * epoch, its checkpoint doesn't run ahead of ours, and the log still covers it;
    * else a full re-seed. A fully-compacted log only proves "nothing missed" when
    * the client is already at `cursor`.
-   * @returns the cursor/epoch, the resume base (`baseCheckpoint`), and the membership patch
+   *
+   * `reset` is the inverse of the resume decision and MUST ride the wire: the
+   * re-seed branch returns the whole membership as inserts, which can only ever
+   * add rows, so a client that splices it onto a stale view keeps every row that
+   * left the shape while it was disconnected. Callers stamp it on the poke part.
+   * @returns the cursor/epoch, the resume base (`baseCheckpoint`), whether this is a full re-seed, and the membership patch
    */
   private computeOpLogShapeSeed;
   /**
@@ -3872,6 +4025,95 @@ declare abstract class ShardDO {
    * carrying a part per changed shape. No-op when no socket holds a shape.
    */
   private pokeShapeSubscribers;
+  /**
+   * Enforce the configured `__cdc_log` retention, at most once per interval per
+   * warm instance. Two independent, independently-configured levels:
+   *
+   * **Payload compaction** (`LUNORA_CDC_PAYLOAD_RETENTION`, in rows) nulls the
+   * post-images of older entries while keeping their `(seq, table, id, op)`
+   * keys. Post-images are essentially all of the log's bytes, and since the
+   * shape diff reads its values from the table rather than the log
+   * (`selectShapeMembers`), dropping them costs a live subscriber
+   * nothing — a client past the payload floor still gets an exact key-level
+   * delta instead of a full re-seed.
+   *
+   * **Row deletion** (`LUNORA_CDC_LOG_RETENTION`, in rows) drops the entries
+   * outright. This is the level that ends resumability for anyone below it:
+   * `minCdcSeq` then reports a floor above their cursor and they re-seed.
+   *
+   * Both levels are enforced on the READ paths, not merely intended by the
+   * sweep — `evaluateResume` and `computeOpLogShapeSeed` gate on `minCdcSeq`,
+   * and {@link ShardDO.runShardCdcSync} refuses a page below either floor
+   * (`CDC_LOG_TRIMMED` / `CDC_PAYLOAD_COMPACTED`). That matters because the
+   * failure this sweep can cause is silent by nature: a consumer handed the
+   * surviving tail with an advanced cursor has no way to notice a range went
+   * missing, so every path that can serve one has to refuse instead.
+   *
+   * **Both are opt-in, and that is a deliberate answer rather than caution.**
+   * The log's in-shard consumers record durable cursors this sweep can read
+   * ({@link ShardDO.retentionFloor}), but its out-of-shard consumers do not: a
+   * warehouse connector holds an opaque cursor token issued by the Worker, and
+   * nothing in this shard knows where it is. Trimming to a floor computed only
+   * from what SQLite can see would silently drop rows a connector had not read
+   * — so a deployment that wants retention states the window it can afford, and
+   * gets a sweep that additionally never crosses the in-shard floor. A shard
+   * that configures neither behaves exactly as before.
+   *
+   * Best-effort throughout: a stub `sql` handle or a shard without CDC is a
+   * no-op, and a failure here must never surface on a write path whose data
+   * already committed.
+   */
+  private sweepCdcRetention;
+  /**
+   * The highest `seq` this sweep may compact or delete through without stranding
+   * an in-shard consumer: the lowest cursor any durable local consumer has
+   * durably reached, or the log's head when there is none.
+   *
+   * The direction is what matters. Every input can only pull the floor DOWN, and
+   * a consumer whose cursor cannot be read contributes nothing rather than a
+   * guess — a floor that is too low leaves rows around for one more sweep, while
+   * a floor that is too high deletes a range a live subscription still has to be
+   * told about.
+   *
+   * Two in-shard consumers, and they are tracked in different places. Local
+   * sockets record `__shape_poke_cursor` per `(connection, subscription)` on
+   * every delivered poke, so that table carries their position. **Relayed
+   * subscribers are not in it**: a relay's cohort frontier and its per-socket
+   * proxies are the owner's shape registry (`__lunora_relay_shapes`, read back
+   * through `RelayLink.minShapeCursor`). Reading only the local table would
+   * therefore see a fully relayed shard — the high-fan-out case, i.e. exactly
+   * the shard an operator turns retention on for — as having no subscribers,
+   * and delete the rows the next relayed diff had to read. Both are folded in
+   * here.
+   *
+   * **The floor is each consumer's `cursor`, not its `delivered`** (see
+   * {@link ShapeMemo.delivered}), and the two differ: a client's own position is
+   * `delivered`, which can sit BELOW the `cursor` this floor is computed from.
+   * Trimming to the higher of the two is nonetheless safe, and only for one
+   * reason: `cursor` runs ahead of `delivered` exclusively across ranges where
+   * that shape's table saw no change at all — that is what an empty diff means,
+   * and empty diffs are the only thing that advances `cursor` alone. So the rows
+   * this deletes in `(delivered, cursor]` are never rows that shape still owes
+   * its client. Change what advances `cursor` and this stops holding.
+   *
+   * **Known ceiling: a relayed cohort on a quiet table pins this floor.** A
+   * scalar MIN over every consumer is only as good as the slowest consumer's
+   * ability to advance, and the relay tier's cannot: `OwnerRelay.buildShapePoke`
+   * must leave a cohort's cursor where the last DELIVERED poke reached, because
+   * advancing it without a poke puts every relay socket's memo below the next
+   * poke's `fromCursor` and freezes them (the failure `relay-hub.test.ts` pins).
+   * Local sockets have no such constraint — the shard computes their diffs from
+   * its own memo — so `collectShapePokeParts` advances them on every flush. The
+   * asymmetry means a shard whose shapes are all relayed can still see retention
+   * do nothing.
+   *
+   * The upgrade is a floor PER TABLE rather than one scalar: `readCdcChangeKeys`
+   * already filters by table, so a cohort watching a quiet table never needs the
+   * busy table's rows and should not be holding them. That is a real change to
+   * how the sweep is expressed, not a tweak here, so it waits for a deployment
+   * that needs it.
+   */
+  private retentionFloor;
   /**
    * Diff every op-log-backed shape a socket holds against this flush, splitting
    * the results into the poke parts to send and the per-shape memo advances. A
@@ -3884,37 +4126,38 @@ declare abstract class ShardDO {
    */
   private collectShapePokeParts;
   /**
-   * Drain the op-log range `(sinceSeq, upTo]` for `table` into the latest op per
-   * row id (collapsing multiple ops on the same row to the newest). Within one
-   * flush, every shape over the SAME `(table, sinceSeq, upTo)` reads the
-   * identical changelog slice, so the drained map is memoized in the
-   * caller-supplied `cache` (created fresh per flush) — N shapes on a table
-   * share ONE changelog drain instead of re-scanning it per shape. The
-   * per-shape membership probe still runs per shape (its predicate is
-   * identity/args-specific), so only the shared op read is collapsed.
+   * Read the changed row keys for a shape diff. A thin protected seam over
+   * {@link readCdcChangeKeys}, kept for the one thing nothing else observes:
+   * the `sinceSeq` each diff resumed FROM. Which baseline a poke picked — the
+   * durable memo, the attachment's subscribe-time cursor, or a clamped one
+   * after a PITR rollback — is the assertion in three tests, and it is not
+   * recoverable from the outside.
+   *
+   * It is NOT the read counter. `ShapeDiffCache.probesRun`/`probesServed` count
+   * the reads the per-flush memo collapses, and that is what the sharing tests
+   * assert against.
    */
-  private readShapeOpRange;
+  protected readShapeCdcKeys(sql: SqlExec, table: string, sinceSeq: number, upTo: number): CdcChangeKey[];
   /**
-   * Read one page of the `__cdc_log` for a shape diff (table-scoped). A thin
-   * protected seam over {@link readCdcChanges}: it isolates the single
-   * changelog read that {@link readShapeOpRange} memoizes per flush, and gives
-   * tests a point to count the reads the op-range cache collapses.
+   * One relayed shape's diff, on its own cache.
+   *
+   * The relay tier computes one delta per cohort or proxy rather than per
+   * socket, so there is nothing to share WITHIN a call — the cache exists
+   * because the pipeline requires one. Its counters are still folded back into
+   * {@link ShardDO.shapeProbe}, because they are reads this instance issued:
+   * discarding them would under-report exactly the shards the fan-out panel
+   * exists for, since a shard is relayed precisely when its fan-out is large.
    */
-  protected readShapeCdcPage(sql: SqlExec, sinceSeq: number, tables: ReadonlySet<string>): {
-    changes: CdcChange[];
-    cursor: number;
-  };
+  private diffRelayedShape;
   /**
-   * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
-   * the changelog (drained across pages via {@link readShapeOpRange}, shared
-   * across same-range shapes in a flush), collapses to the latest op per row,
-   * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
-   * changed ids: a row still in the set → upsert with its post-image doc
-   * (projected to the shape's columns); a row that left the set, or any delete,
-   * → `delete(key)` (a delete carries no post-image, so membership is
-   * unknowable from the op alone — the client no-ops an unknown key).
+   * This shard's shape diff: {@link buildShapeDiff} with the changelog read
+   * routed through {@link ShardDO.readShapeCdcKeys}, so the DO's one seam over
+   * that read stays the DO's.
+   *
+   * The pipeline itself is host-neutral and lives in `@lunora/shard-engine` —
+   * it reads through the `sql` handle and touches no instance state.
    */
-  private buildShapeDiff;
+  private diffShape;
   /** Build the full insert-poke of a shape's current membership — the first-seed/full-reseed rowset. */
   private buildShapeSeed;
   /**
@@ -4007,6 +4250,88 @@ declare abstract class ShardDO {
    * snapshotted per socket.
    */
   private withinGlobalShapeBound;
+  /**
+   * The changelog settings the generated code hands to the `.global()` writer.
+   *
+   * `cdc` is the app's own opt-in, forwarded from the shard config so the two
+   * logs are governed by ONE switch: a deployment that turns CDC on gets a
+   * changelog on both tiers, and one that leaves it off pays for neither. Until
+   * this was threaded, the global writer was built without it unconditionally —
+   * so the global `__cdc_log` was never written, and the poll's
+   * changed-tables fast path was unreachable in every generated app while
+   * looking, from the shard side, exactly like a backend that had CDC disabled.
+   *
+   * `cdcRetentionMs` is read here rather than in the generated factory so every
+   * deployment knob goes through one strict parser (see
+   * {@link ShardDO.sweepCdcRetention} for why lenient parsing on a delete path
+   * is a footgun). Absent means the global log is never trimmed.
+   */
+  protected globalCdcOptions(cdc: boolean): {
+    cdc: boolean;
+    cdcRetentionMs?: number;
+  };
+  /**
+   * Ask the `.global()` backend which tables it recorded a write to after
+   * `sinceSeq`. The base class has no global backend, so it reports no
+   * visibility (`undefined`) and every poll tick falls back to re-reading
+   * membership; the codegen-generated subclass overrides this to forward the
+   * question to the global store's changelog. Emitted only for a project that
+   * has both shapes and `.global()` tables.
+   *
+   * `cursorOnly` says the caller has already committed to reading everything
+   * this pass and wants only the cursor — see the contract on
+   * `DatabaseWriterLike.cdcChangedTables`.
+   */
+  protected readGlobalChangedTables(_sinceSeq: number, _cursorOnly?: boolean): Promise<{
+    cursor: number;
+    floor?: number;
+    tables: string[];
+  } | undefined>;
+  /**
+   * Open one `.global()` poll tick: ask the global changelog what moved since
+   * the last tick, and decide whether this tick may use that answer to skip
+   * membership reads.
+   *
+   * Two things force a full pass regardless of what the changelog says. The
+   * first is having no cursor to compare against — a cold instance, or a
+   * backend with CDC disabled, has no basis for "unchanged" and must read. The
+   * second is the resync interval, and it is the honest part of this design: a
+   * `.global()` table can be written by something that is not this deployment,
+   * and such a write leaves no row in our changelog. Trusting the changelog
+   * forever would mean a shape silently frozen against an out-of-band writer,
+   * so the fast path is a bounded skip — at worst {@link ShardDO.GLOBAL_SHAPE_RESYNC_MS}
+   * of staleness for a change we could not see, against the full membership
+   * re-read of every shape on every socket every two seconds that it replaces.
+   *
+   * That same bound now covers a second case worth naming: a shape whose
+   * membership moves WITHOUT a write — a predicate over wall-clock, like
+   * `_creationTime > now - 1h`. It used to converge on the poll interval
+   * because every tick re-read it; it now converges on the resync interval,
+   * because no changelog row marks its table as having moved. Bounded and
+   * intended, but a different guarantee than the one this path used to give.
+   */
+  private openGlobalPollTick;
+  /**
+   * Read a `.global()` shape's membership through this tick's cache.
+   *
+   * The key is the resolved predicate **and the caller's identity**, and the
+   * second half is not redundant with the first. The op-log path can share a
+   * probe on the predicate alone because it reads this shard's own SQLite with
+   * nothing but that predicate — identity has no other channel into the query.
+   * A `.global()` read does not have that property: the backend writer is built
+   * per request from `{ identity, userId }`, so an application's own `d1` /
+   * `hyperdriveGlobal` factory may scope rows by the caller before this code
+   * ever sees them. Two sockets with equal predicates and different identities
+   * can therefore be entitled to different rows, and sharing one read between
+   * them would hand one user the other's.
+   *
+   * What remains shareable is what is genuinely identical: every socket of the
+   * same user (tabs, devices, reconnects), and every socket of an anonymous or
+   * public shape — which is where the fan-out that made this path expensive
+   * lives. An identity or predicate that cannot be stably keyed falls back to
+   * an un-shared read.
+   */
+  private readGlobalShapeRowsCached;
   /**
    * Refresh every `.global()`-table shape held across all live sockets, one
    * diff-poke per (socket, shape). Returns the number of global shapes still