@lunora/do 1.0.0-alpha.61 → 1.0.0-alpha.63

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { SchemaLike, DatabaseWriterLike, CdcChange, FilterClause, ExportRow, MigrationDirection, ReactiveCache, ReactiveCacheOptions, ShardSocketLike, LifecycleDispatchInfo, MigrationRunResult, TableIndexInfo, ColumnMeta, AdvisoryFinding, AdvisorProcedure, RlsPoliciesResult, MaskPoliciesResult, StorageRulesResult, StudioFeaturesResult, FlagsResult, SubscriptionIdentity, QueuesResult, WorkflowsResult, ImportShardResult, ShardRankPageResult, SubscriptionQuery, ShapeSubscriptionQuery, MutationDelta, KeyRange, ResolvedShape, ShapeRow, TtlSweepSpec, TransactionLimits, TransactionHeadroomTracker, IndexKeyEntry, SqlExec } from '@lunora/shard-engine';
+import { SchemaLike, DatabaseWriterLike, 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 { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, type AdvisorProcedure, type AdvisorProceduresResult, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, type ExternalSourceDiffResult, type ExternalSourceLike, FLAGS_FUNCTION_PREFIX, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionStatsResult, GEO_DEFAULT_PRECISION, type GeoBoundingBox, type GeoFilterBuilderLike, type GeoIndexDefinitionLike, type GeoPoint, type GroupByEntry, type GroupByOptions, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IncrementalMaterializeResult, type IndexDefinitionLike, type IndexKeyEntry, type IndexRangeBuilderLike, type KeyRange, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, type MaskColumnMetadata, type MaskPoliciesResult, type MaterializeResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunTriggersOptions, SCAN_DEP, type SchedulableWorkflowReferenceLike, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SearchIndexDefinitionLike, type SelectMatchingIdsOptions, type ServerDefaultContextLike, type SettingEntry, type SettingKind, type SettingsResult, type ShapeSubscriptionQuery, type ShardRankPageResult, type SocketAttachment, type SortDirection, type SourceClientLike, type SourceCursorLike, type SourceRefresh, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionHeadroomTracker, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type TtlSweepSpec, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertShapeShardable, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, backfillSearchIndexes, boundingBoxCenter, boundingBoxGeohashes, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, coveringGeohashes, createDependencyTracker, createReadFootprint, createShardCtxDb, createSystemReader, decodeCursor, depKey, diffExternalSource, encodeAggregateKey, encodeCursor, encodeGeohash, encodePartitionKey, ensureMailTable, exportShardRows, exportShardTable, facetColumn, fanOutScalarCounts, foldAggregateTally, guardWriter, hasTrigger, haversineMeters, importShardRows, isRelationPredicate, isSoftDeleted, isSourceDue, liftSourceId, listTables, matchesRankStaticWhere, matchesStaticWhere, materializeExternalRows, materializeExternalRowsIncremental, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, pointInBoundingBox, pullExternalSourceIncrementalTick, pullExternalSourceTick, rankTableName, reactiveCacheKey, readAggregateValue, readBookmark, readCapturedMail, readCdcChanges, readExternalSourceBaseline, readMigrationStatus, readTablePage, recordCapturedMail, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runExternalSourceTick, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, selectExpiredIds, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, softDeleteScope, sortColumnName, stableStringify, stableWireKey, subscriptionListDeltas, throwingScheduler, trimCdcChanges, validateImportRow } from '@lunora/shard-engine';
 import { DatabaseInstrumentation, MetricHistoryOptions, LogEventInput, ContextLogLevel, TraceAnchor, ContextTracer, ContextFetch, ContextMetrics } from '@lunora/observability';
 import { DrizzleSqliteDODatabase } from 'drizzle-orm/durable-sqlite';
@@ -1131,6 +1131,13 @@ declare abstract class ShardDO {
    * RPC. In-memory only — they reset when the DO hibernates or restarts, which
    * is the right granularity for a "since this instance woke" health readout
    * (durable aggregation would be a separate, heavier feature).
+   *
+   * `subscriptionRefreshErrors` (DO-01) rides along the same lifetime/in-memory
+   * shape: incremented, alongside a structured log, wherever a live-query
+   * refresh or shape poke swallows a per-subscription/per-socket error so its
+   * siblings can keep flushing (`refreshSubscriptions`, `pokeShapeSubscribers`
+   * via `recordSubscriptionRefreshError`). It IS on the `getMetrics` wire
+   * response (`collectMetrics`); a studio panel charting it is a follow-up.
    */
   private readonly metrics;
   /**
@@ -1208,6 +1215,16 @@ declare abstract class ShardDO {
    * 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
@@ -1248,19 +1265,38 @@ declare abstract class ShardDO {
    */
   private currentRequestReadTables;
   /**
-   * Per-statement SQL samples collected during the current `/rpc` dispatch by
-   * the instrumented `sql` getter. Drained into the durable
-   * `__lunora_metrics_queries` table after the handler returns (same pattern as
-   * `currentScannedTables` / `currentIndexHits`). `undefined` when no dispatch
-   * is in flight; allocated fresh per dispatch so a previous request's samples
-   * never leak into the next one.
-   *
-   * Each entry is `[rawSql, durationMs, rowsRead, rowsWritten]`. DML rows
-   * written is always 0 here — the ctx-db adapter doesn't expose a
+   * Per-DISTINCT-statement SQL samples collected during the current `/rpc`
+   * dispatch by the instrumented `sql` getter, keyed by the raw query text.
+   * Drained into the durable `__lunora_metrics_queries` table after the
+   * handler returns (same pattern as `currentScannedTables` /
+   * `currentIndexHits`). `undefined` when no dispatch is in flight; allocated
+   * fresh per dispatch so a previous request's samples never leak into the
+   * next one.
+   *
+   * Keyed by the raw query string rather than a growing array: a handler
+   * that queries in a loop reuses the SAME prepared-statement text on every
+   * iteration (bind parameters travel separately via `...params`, never
+   * inlined into `query`), so folding each call into its entry as it lands
+   * collapses the loop to one entry — {@link ShardDO.flushStmtSamples} then
+   * pays one upsert per DISTINCT statement instead of one per raw execution.
+   * Bounded at {@link MAX_STMT_SAMPLES_PER_DISPATCH} distinct entries; past
+   * that, a brand-new statement shape (ad-hoc SQL built per iteration) is
+   * dropped and `currentStmtSamplesTruncated` is set — already-tracked
+   * statements keep folding regardless.
+   *
+   * `rowsWritten` is always 0 here — the ctx-db adapter doesn't expose a
    * `changes()` count through the structural `SqlExec` surface, so we
    * attribute only SELECT result sizes as `rowsRead`.
    */
   private currentStmtSamples;
+  /**
+   * Set when `currentStmtSamples` hit {@link MAX_STMT_SAMPLES_PER_DISPATCH}
+   * distinct statements and a brand-new shape was dropped this dispatch.
+   * Folded onto the dispatch's wide event as `db.stmt_samples_truncated`
+   * (mirrors `database-telemetry.ts`'s `db.spans_truncated`) so a truncated
+   * 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);
@@ -1315,8 +1351,22 @@ declare abstract class ShardDO {
    * this stays dormant there.
    */
   alarm(): Promise<void>;
-  /** Subclasses implement function dispatch. */
-  abstract handleRpc(functionPath: string, args: Record<string, unknown>): Promise<unknown>;
+  /**
+   * Subclasses implement function dispatch.
+   *
+   * `headroom` is an optional BY-VALUE override, mirroring
+   * {@link ShardDO.deleteRowThroughWriter}'s pattern: the main `/rpc` dispatch
+   * (`handleFetchCloudflare`) captures its freshly-minted tracker in a LOCAL and
+   * passes it here explicitly, so the ctx this dispatch builds never depends on
+   * `this.currentTransactionHeadroom` still holding the right value by the time
+   * the (possibly `await`-interleaved) handler runs — a concurrent dispatch's
+   * `finally` clearing that shared field could otherwise leave this one
+   * unmetered mid-flight. Callers that dispatch through here without minting
+   * their own tracker (`dispatchLifecycle`, `handleRunAs`) omit it and the
+   * codegen subclass falls back to `this.transactionHeadroom()`, unchanged from
+   * before this parameter existed.
+   */
+  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker): Promise<unknown>;
   /**
    * The registered function paths to dispatch when a socket connects/disconnects.
    * Base default is empty; the codegen subclass overrides it to return the
@@ -1353,7 +1403,7 @@ declare abstract class ShardDO {
   protected runRelationFanoutRead(_functionPath: string, _args: Record<string, unknown>): Promise<unknown>;
   /**
    * Instrumented SQL handle. Wraps `state.storage.sql` so that every `exec`
-   * call during a user RPC dispatch is timed and its result size captured into
+   * call during a user RPC dispatch is timed and its result size folded into
    * `currentStmtSamples`. The samples are flushed to the durable
    * `__lunora_metrics_queries` table after the handler returns (same lifecycle
    * as `currentScannedTables`/`currentIndexHits`).
@@ -1669,8 +1719,14 @@ declare abstract class ShardDO {
    * The base class can't build a writer without the user's `schema.ts`, so it
    * reports the table as unknown; the codegen-generated subclass overrides
    * this to call `writer.delete(id)` on a live `createShardCtxDb(...)` writer.
+   *
+   * `headroom` is an optional BY-VALUE override: {@link ShardDO.runShardBulkDelete}
+   * (a normal `/rpc` dispatch) omits it, so the override falls back to
+   * `this.transactionHeadroom()` — the per-dispatch meter every other write
+   * already uses. {@link ShardDO.pollTtlSweeps} (an alarm work item, no dispatch
+   * in flight) passes its own fresh tracker explicitly instead.
    */
-  protected deleteRowThroughWriter(_table: string, _id: string): Promise<void>;
+  protected deleteRowThroughWriter(_table: string, _id: string, _headroom?: TransactionHeadroomTracker): Promise<void>;
   /**
    * Bulk-delete the rows of `table` matching the active `filters`/`search`
    * (or every row, for `clearTable`), bounded to {@link SHARD_BULK_DELETE_CAP}
@@ -2042,6 +2098,17 @@ declare abstract class ShardDO {
    * cadence, so freshly-written rows expire within a bounded window) while any
    * TTL table exists, or `undefined` when there are none — so a DO with no TTL
    * table never arms this tier.
+   *
+   * One {@link ShardDO.alarmHeadroom} tracker covers the WHOLE sweep pass (every
+   * spec, every batch) — not per-row or per-spec — because the ceiling exists to
+   * bound one alarm tick's total isolate cost, not any single table's. A
+   * `TRANSACTION_LIMIT_EXCEEDED` mid-batch is "batch full", not a genuine
+   * failure: `selectExpiredIds` never re-selects an already-deleted row, so
+   * deletion IS the resumable checkpoint here — no separate cursor is needed.
+   * The sweep stops immediately, logs a `warn` (not `recordShapeError`, which
+   * would surface as a genuine failure), and returns `Date.now()` so the shared
+   * alarm re-arms promptly via `nextPollAlarmTarget`'s existing due-now floor,
+   * rather than waiting out the full `TTL_SWEEP_INTERVAL_MS` cadence.
    */
   protected pollTtlSweeps(): Promise<number | undefined>;
   /**
@@ -2084,6 +2151,24 @@ declare abstract class ShardDO {
    * 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
+   * `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
+   * 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
+   * `footprint.ranges()` could not narrow (any by-id/scan read, or a
+   * provable range mixed with one) still falls back to a whole-table
+   * `SCAN_DEP`, stamped after `run()` resolves — see the fallback in this
+   * 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>;
   /**
@@ -2099,8 +2184,30 @@ declare abstract class ShardDO {
    * 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.
+   *
+   * It ALSO marks the table unnarrowable on {@link currentReadFootprint},
+   * 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
+   * exclusively per read — a provable index slice fires ONLY `onReadRange`,
+   * everything else (by-id, scan, an unprovable slice) fires ONLY this
+   * `onRead` — so folding the footprint's `onRead` in here is exactly the
+   * "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;
+  /**
+   * 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;
   /**
    * Read hook recording which declared indexes a query actually exercises.
    * Two destinations, both stamped here so a single hook serves the live and
@@ -2143,6 +2250,20 @@ declare abstract class ShardDO {
    * drain would take the refresh branch and lose its own ceiling entirely.
    */
   protected subscriptionHeadroom(): TransactionHeadroomTracker;
+  /**
+   * A fresh budget for one alarm-driven work item — one external-source
+   * table's tick, or one TTL sweep pass.
+   *
+   * Alarm work runs with no client waiting and no `/rpc` dispatch in flight,
+   * so `transactionHeadroom()`'s per-dispatch tracker is `undefined` there —
+   * leaving external-source ingest and TTL sweeps completely unmetered, the
+   * exact isolate-exhaustion class the meter exists to bound. Handed to the
+   * writer BY VALUE, the same pattern as `subscriptionHeadroom()` and for the
+   * same reason: an ambient instance-field flag would race a concurrently
+   * in-flight `/rpc` dispatch, or a sibling alarm work item, clearing or
+   * substituting the wrong tracker mid-flight.
+   */
+  protected alarmHeadroom(): TransactionHeadroomTracker;
   /**
    * Record that `table` was written during the current RPC. Wired into the
    * db adapter's `broadcast` callback by the generated subclass so that
@@ -2440,12 +2561,25 @@ declare abstract class ShardDO {
    * fields. `indexHits` is shaped exactly as the advisor's `AdvisorIndexHit`
    * (`{ table, index, reads }`), so the studio passes it straight to
    * `runLints({ ..., indexHits })` after summing the per-shard arrays.
+   *
+   * `subscriptionRefreshErrors` (DO-01) rides along the same way: an
+   * in-memory-only lifetime count (no durable table, unlike `requests`/
+   * `errors`), incremented by `recordSubscriptionRefreshError` whenever a live
+   * query refresh or shape poke swallows a per-subscription error to protect
+   * its siblings. The field is on the wire so it is queryable/testable now;
+   * charting it in the studio's metrics panel is a follow-up.
    */
   private collectMetrics;
   /**
    * Fold one dispatch into the per-function counters keyed by `functionPath`,
    * creating the entry on first sight. `errorMessage` is supplied only when
-   * the handler threw, in which case the failure counters advance too.
+   * the handler threw, in which case the failure counters advance too. The
+   * caller is expected to have already redacted `errorMessage` (via
+   * `redactArgs`, the same `standardRules` treatment the request-log sinks
+   * use) — this method persists/caches it verbatim into BOTH the durable
+   * `__lunora_metrics.last_error_message` column and the in-memory
+   * `functionStats.lastErrorMessage` served by `getFunctionStats`, so an
+   * un-redacted message reaching here leaks into the Studio.
    * `scannedTables` carries the tables the dispatch full-scanned (collected by
    * `getCtxDbReadHook`), which advance the causal scan attribution.
    * `indexHits` carries the declared indexes it exercised (collected by
@@ -2464,9 +2598,16 @@ declare abstract class ShardDO {
    */
   private recordFunctionCall;
   /**
-   * Flush per-statement SQL samples accumulated during the current dispatch
-   * into the durable `__lunora_metrics_queries` table. Called after
-   * `recordFunctionCall` on both the success and error paths.
+   * Flush the per-DISTINCT-statement SQL samples accumulated during the
+   * current dispatch into the durable `__lunora_metrics_queries` table.
+   * Called after `recordFunctionCall` on both the success and error paths.
+   *
+   * Already folded by the instrumented `sql` getter (see
+   * `currentStmtSamples`), so this pays exactly one `recordQueryMetric` call
+   * — one accumulator upsert plus one bucket upsert — per distinct statement
+   * the dispatch ran, however many times it actually ran. `count` carries the
+   * real execution count through so the durable `exec_count`/`total_duration_ms`
+   * still reflect every execution, not just one.
    *
    * Best-effort: a SQL failure (e.g. a test double without a usable `sql`
    * handle) must never fail the response, so every call is swallowed.
@@ -2492,8 +2633,8 @@ declare abstract class ShardDO {
   /**
    * Per-function coarse time-series served additively by the metrics RPC, so
    * the studio can chart call/error history. Reads the durable
-   * `__lunora_metrics_buckets` table; returns `[]` when persistence is
-   * unavailable so the response stays well-formed.
+   * `__lunora_metrics_buckets` table; returns an empty, non-truncated result
+   * when persistence is unavailable so the response stays well-formed.
    */
   private collectFunctionMetricBuckets;
   private maybeWarnRootSize;
@@ -2914,15 +3055,26 @@ declare abstract class ShardDO {
    * @returns the result and table-dependency set for a read op, or `null` for a write/migration op
    */
   private readAdminOp;
+  /**
+   * Shared shape behind `describeTables` and `listTablesIndexes`: read the
+   * `tables` arg, run `lookup` (a cheap, synchronous, schema-sourced `this.*()`
+   * hook) over each, and report the requested set as the read's table
+   * dependency (or the {@link ADMIN_WILDCARD} sentinel when none were named).
+   * Factored out so `readAdminTableSignal` states each batched RPC as one line
+   * rather than duplicating the array-filter/fan-out shape per sibling.
+   */
+  private batchedTableLookup;
   /**
    * Resolve the table-scoped introspection reads whose payload is a single
    * `this.*()` lookup keyed by an optional `table` arg — `listTableIndexes`
    * (declared indexes), `describeTable` (declared columns) and `migrationStatus`
-   * (the migration ledger). The first two carry their `table` (or the
-   * {@link ADMIN_WILDCARD} sentinel when unscoped); `migrationStatus` is
-   * deployment-wide, so it always carries the wildcard. Returns `undefined` for
-   * any other path so {@link readAdminOp} falls through; folded into one helper
-   * to keep that dispatcher under its complexity budget.
+   * (the migration ledger); plus their batched siblings `describeTables` and
+   * `listTablesIndexes` (one RPC for N tables via {@link batchedTableLookup}).
+   * The single-table pair carries its `table` (or the {@link ADMIN_WILDCARD}
+   * sentinel when unscoped); `migrationStatus` is deployment-wide, so it always
+   * carries the wildcard. Returns `undefined` for any other path so
+   * {@link readAdminOp} falls through; folded into one helper to keep that
+   * dispatcher under its complexity budget.
    * @returns the read result and its table-dependency set, or `undefined` when the path is not owned by this resolver
    */
   private readAdminTableSignal;
@@ -3220,6 +3372,32 @@ declare abstract class ShardDO {
    * high-fanout shards rather than bolt a second, semantically-divergent dedup
    * into this loop.
    */
+  /**
+   * Count and log a subscription-delivery error that its caller is about to
+   * swallow (DO-01) — `refreshSubscriptions`' per-`(socket, sub)` catch and
+   * `pokeShapeSubscribers`' per-socket catch both call this instead of a bare
+   * `catch { continue; }`, so a live query or shape poke that throws
+   * DETERMINISTICALLY on every flush is counted on `metrics.subscriptionRefreshErrors`
+   * and shows up in the studio's Live Logs, rather than repeating silently for
+   * the life of the socket. Factored out because both call sites need the
+   * identical counter-then-best-effort-log shape, and duplicating it inline
+   * pushed each closure over the file's cognitive-complexity budget.
+   *
+   * `lastTelemetrySink` (not a threaded `sink`) because both flush workers run
+   * with no `ctx` — the same stand-in `flushTelemetry` uses.
+   *
+   * `error` is a caught INTERNAL failure surfaced from a background
+   * refresh/poke pass, not a value a developer chose to log via `ctx.log` —
+   * so `recordUserLog`'s "args are not redacted" contract (see its
+   * docstring) does not apply here: a thrown value can carry an arbitrary
+   * `cause`, stack, or custom own property (a handler can `throw
+   * Object.assign(new Error(...), { row })`), and `args` rides raw into any
+   * `sink.onLog` an operator has configured. Route it through the same
+   * `toErrorBody` envelope every other error-crossing boundary in this file
+   * uses (see `errorToResponse`, the shape-seed catches above) so only a
+   * bounded `{ code, message }` — not the raw error — reaches the sink.
+   */
+  private recordSubscriptionRefreshError;
   private refreshSubscriptions;
   /**
    * Seed a freshly-registered subscription with its first value. Runs the
@@ -3309,9 +3487,10 @@ declare abstract class ShardDO {
    * the results into the poke parts to send and the per-shape memo advances. A
    * `.global()` shape (driven by the alarm poll loop, not this flush) and a shape
    * whose table didn't change are skipped; a shape whose resolve/diff throws is
-   * logged and skipped with its memo unadvanced so a later flush retries. Empty
-   * diffs advance unconditionally; part-bearing shapes advance only once the
-   * caller confirms the poke was delivered.
+   * counted and logged via `recordSubscriptionRefreshError` (DO-01) and skipped
+   * with its memo unadvanced so a later flush retries. Empty diffs advance
+   * unconditionally; part-bearing shapes advance only once the caller confirms
+   * the poke was delivered.
    */
   private collectShapePokeParts;
   /**
@@ -3404,6 +3583,16 @@ declare abstract class ShardDO {
    * default, since neither knows a more precise due time yet.
    */
   private scheduleGlobalPoll;
+  /**
+   * Delete one expired row through {@link ShardDO.deleteRowThroughWriter},
+   * absorbing a `TRANSACTION_LIMIT_EXCEEDED` as "batch full" rather than
+   * letting it propagate — split out of {@link ShardDO.pollTtlSweeps} to keep
+   * that method's own complexity down. Returns `true` when the limit was hit
+   * (the caller must stop the sweep pass) and logs a `warn` recording it; `false`
+   * on an ordinary successful delete. Any OTHER thrown error still propagates —
+   * only the meter's own signal is contained here.
+   */
+  private deleteExpiredTtlRow;
   /**
    * Record a contained shape-tier error (poll / poke / seed) into the DO's log
    * ring without aborting the rest of the pass. The shape pipeline is a
@@ -3478,6 +3667,14 @@ declare abstract class ShardDO {
    * persist its resume position and replay it as `sinceSeq` on reconnect
    * (Pillar 1b). Omitted on shards without CDC, keeping the wire byte-identical
    * to the pre-cursor format.
+   *
+   * `clientWatermark` is this socket's `socketClientWatermark(ws)` — read
+   * ONCE by the caller and passed in, not recomputed here. A single
+   * write-flush can call this method many times for the same socket (once
+   * per affected subscription — see `refreshOne`), and the watermark
+   * depends only on `ws`, never on `subId`/`outcome`, so recomputing it per
+   * subscription was a redundant `SELECT … FROM __client_watermark` per
+   * subscription per socket per flush.
    */
   private pushSubscriptionData;
   /**
@@ -3559,13 +3756,17 @@ declare abstract class ShardDO {
    * harness double) or a pre-CDC shard, so callers degrade to the no-CDC path.
    */
   private cdcEnabled;
-  /** Whether `ws` carries a credential whose expiry (stamped at upgrade) is now past. */
+  /**
+   * Whether `ws` carries a credential whose expiry (stamped at upgrade) is
+   * now past. Delegates to the shared boundary check `@lunora/agent`'s
+   * voice DO uses for the same decision, so the two DOs can never disagree
+   * about it.
+   */
   private isSocketExpired;
   /**
-   * Send the `TOKEN_EXPIRED` error frame and close the socket with code 4001 so
-   * the client distinguishes an expired-credential drop from an ordinary one
-   * and refreshes before reconnecting. Best-effort: a throw (socket already
-   * gone) is swallowed — this must never escape the hibernation handlers.
+   * Drop an expired-credential socket via the shared `TOKEN_EXPIRED`/`4001`
+   * helper `@lunora/agent`'s voice DO also calls, so both DOs send the
+   * client-facing wire shape from one place.
    */
   private dropExpiredSocket;
   /**