@lunora/do 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/index.d.mts

@@ -596,6 +596,7 @@ declare const rankTableName: (table: string, indexName: string) => string;
 * - `sortValues[i]` === `serializeSqlValue(doc[index.sortBy[i].field])` — the same transform `syncRankIndexEntry` applies to the stored `__sort_k<i>__` column, so the comparison is byte-for-byte (and JSON-safe for the cross-shard wire) regardless of which shard owns the row. `rankBefore` re-applies it idempotently, so a direct caller passing raw values still works.
 * - `rowId` === `doc._id`, the `__id__` tiebreak.
 */
+declare const stableStringify: (value: unknown) => string;
 /** A single memoized result, the deps it read, and any active subscribers. */
 interface CacheEntry {
   /** Approximate serialized size of `result`, charged against `maxBytes`. */
@@ -728,16 +729,6 @@ declare class ReactiveCache {
   private evict;
 }
 /**
-* Stable, sorted JSON encoding of `args` for use in a cache key. Object keys
-* are visited in lexical order at every depth so `{ a: 1, b: 2 }` and
-* `{ b: 2, a: 1 }` hash to the same string. Arrays preserve their order
-* (the index IS the key). `undefined` values are skipped at the object level
-* so `{ a: undefined }` collides with `{}` — matches Convex behavior and
-* avoids spurious cache misses on optional args. Inside arrays `undefined`
-* encodes as `null` to keep positional semantics.
-*/
-declare const stableStringify: (value: unknown) => string;
-/**
 * Compose a cache key from a function path, a stably-encoded args object, and
 * the caller's identity discriminator. Exported so the wiring layer and tests
 * build identical keys without each side reinventing the format.
@@ -2262,6 +2253,19 @@ declare const ADMIN_FUNCTION_PREFIX = "__lunora_admin__:";
 */
 declare const RELATION_FUNCTION_PREFIX = "__lunora_relation__:";
 /**
+* Reserved `functionPath` prefix for live feature-flag reads. The React client's
+* `useFlag`/`useFlags` subscribe to `__lunora_flags__:eval` over the same WS
+* channel as a user query; `ShardDO` intercepts it before user dispatch and
+* serves it from the codegen-overridden flag-subscription read hook, which
+* evaluates the flag through the app's OpenFeature provider under the socket's
+* verified identity. Like the other reserved prefixes it is NOT admin-gated (a
+* flag read is public, scoped to the subscriber's own targeting context), and
+* the `__lunora_` namespace is reserved so a real `<file>:<function>` can't
+* collide. Re-evaluated on every write-flush so values stay live within a
+* session (provider-side flips with no intervening write surface on reconnect).
+*/
+declare const FLAGS_FUNCTION_PREFIX = "__lunora_flags__:";
+/**
 * Fully-qualified reserved paths the data browser invokes. The
 * `__lunora_admin__:` prefix is spelled out inline rather than interpolated so
 * the values stay emittable under `--isolatedDeclarations`.
@@ -2292,6 +2296,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getSettings: "__lunora_admin__:getSettings";
   readonly getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus";
   readonly importShard: "__lunora_admin__:importShard";
+  readonly listFlags: "__lunora_admin__:listFlags";
   readonly listQueues: "__lunora_admin__:listQueues";
   readonly listTables: "__lunora_admin__:listTables";
   readonly listWorkflows: "__lunora_admin__:listWorkflows";
@@ -2572,6 +2577,8 @@ interface StorageRulesResult {
 * package's tests and the studio's fails the build if the two key sets diverge.
 */
 interface StudioFeaturesResult {
+  /** `@lunora/flags` / `ctx.flags` is used, or it is a declared dependency. */
+  flags: boolean;
   /** `@lunora/mail` is imported by a `lunora/` source or a declared dependency. */
   mail: boolean;
   /** `@lunora/payment` is used (import or `ctx.payments`) or a declared dependency. */
@@ -2588,6 +2595,40 @@ interface StudioFeaturesResult {
   workflows: boolean;
 }
 /**
+* One feature flag evaluated under a supplied targeting context, surfaced by
+* `__lunora_admin__:listFlags` for the studio's read-only Flags page. The `key`
+* and `type` are statically discovered by `@lunora/codegen` from the app's
+* `ctx.flags.<type>("key", …)` reads; `value`/`reason`/`variant`/`errorCode`
+* come from the live OpenFeature evaluation (the codegen subclass overrides the
+* base `evaluateFlags` hook). `value` is the resolved flag value as JSON.
+*/
+interface FlagEvaluation {
+  /** OpenFeature `errorCode` when the evaluation failed (the value falls back to the default). */
+  errorCode?: string;
+  /** The discovered flag key (the first argument of a `ctx.flags.<type>(...)` read). */
+  key: string;
+  /** OpenFeature `reason` for the resolution (`TARGETING_MATCH`, `DEFAULT`, `ERROR`, …). */
+  reason?: string;
+  /** The flag's value type, derived from which `ctx.flags.<type>` method read it. */
+  type: "boolean" | "number" | "object" | "string";
+  /** The resolved value (JSON), or the type default when unconfigured / on error. */
+  value: unknown;
+  /** OpenFeature `variant` identifier when the provider reports one. */
+  variant?: string;
+}
+/**
+* Payload of a `__lunora_admin__:listFlags` call: every statically-discovered
+* flag evaluated under the supplied targeting context. `configured` is `false`
+* when the app wires no `@lunora/flags` provider (the base hook), so the studio
+* can distinguish "no flags configured" from "configured but zero flags read".
+*/
+interface FlagsResult {
+  /** `true` when an `@lunora/flags` provider is wired (the codegen override ran). */
+  configured: boolean;
+  /** Each discovered flag evaluated under the request's targeting context. */
+  flags: FlagEvaluation[];
+}
+/**
 * One declared Cloudflare Workflow, surfaced by `__lunora_admin__:listWorkflows`
 * for the studio's Workflows page. Statically discovered by `@lunora/codegen`
 * from `lunora/workflows.ts` (the codegen subclass overrides the base hook);
@@ -3666,6 +3707,44 @@ declare class SessionDO {
   private handleRevoke;
 }
 /**
+* Diff the previously-sent list snapshot (`previousJson`, the memo's
+* `lastJson`) against the new query result and produce per-row
+* {@link MutationDelta}s the client can merge in place via `applyDelta` —
+* Convex-parity live-pagination deltas (server half of gap #20).
+*
+* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
+* unless ALL of these hold:
+*
+* 1. `previousJson` parses to an array (there IS a previous list to diff against).
+* 2. `nextResult` is also an array.
+* 3. Every row in both arrays is a plain object carrying a string `_id`.
+* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
+* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
+*
+* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
+* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
+* full new `row`; delete omits it (matching the wire contract `@lunora/client`
+* parses). Deltas are ordered deletes-then-inserts/updates so the client never
+* sees a transient over-length page.
+*
+* Per-row serialization is done exactly **once** per refresh (finding #6). Each
+* row is stringified a single time into a fingerprint reused for both the
+* `prev !== next` change-detection compare and — when the caller passes the
+* optional `frames` sink — the pre-serialized delta frame body. The returned
+* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
+* exact `JSON.stringify(delta)` string for each returned delta, in the same
+* order, so the caller can splice it straight into the `{type:"delta"}` frame
+* without serializing the delta (and the row inside it) a second time.
+* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
+*/
+declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
+/**
+* Send one WebSocket frame, reporting whether it left the socket. A throw from
+* `ws.send` (socket closed mid-flush, outbound buffer gone) is the only
+* delivery-failure signal the runtime exposes; callers use the boolean to decide
+* whether to advance a subscription's delivered-diff baseline.
+*/
+/**
 * Optional programmatic log sink, resolved from `createShardDO({ observability })`.
 * Structurally a subset of `@lunora/runtime`'s `ObservabilitySink`, so a user can
 * pass the SAME sink object to `createWorker` (which drives `onRpc`) and
@@ -3918,38 +3997,6 @@ interface RunShardRankPageArgs {
   take?: number;
 }
 /**
-* Diff the previously-sent list snapshot (`previousJson`, the memo's
-* `lastJson`) against the new query result and produce per-row
-* {@link MutationDelta}s the client can merge in place via `applyDelta` —
-* Convex-parity live-pagination deltas (server half of gap #20).
-*
-* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
-* unless ALL of these hold:
-*
-* 1. `previousJson` parses to an array (there IS a previous list to diff against).
-* 2. `nextResult` is also an array.
-* 3. Every row in both arrays is a plain object carrying a string `_id`.
-* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
-* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
-*
-* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
-* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
-* full new `row`; delete omits it (matching the wire contract `@lunora/client`
-* parses). Deltas are ordered deletes-then-inserts/updates so the client never
-* sees a transient over-length page.
-*
-* Per-row serialization is done exactly **once** per refresh (finding #6). Each
-* row is stringified a single time into a fingerprint reused for both the
-* `prev !== next` change-detection compare and — when the caller passes the
-* optional `frames` sink — the pre-serialized delta frame body. The returned
-* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
-* exact `JSON.stringify(delta)` string for each returned delta, in the same
-* order, so the caller can splice it straight into the `{type:"delta"}` frame
-* without serializing the delta (and the row inside it) a second time.
-* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
-*/
-declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
-/**
 * Threshold at which a `__root__` DO triggers the size warning. 1 GiB —
 * exactly 10% of the 10 GiB per-DO SQLite ceiling, leaving plenty of runway
 * to plan a `.shardBy()` migration before the wall hits.
@@ -4131,6 +4178,18 @@ declare abstract class ShardDO {
   */
   private pendingChangedTables;
   /**
+  * Coalesced set of tables awaiting a subscription-refresh pass, merged
+  * across every {@link ShardDO.flushChangedTables} call that lands while a
+  * pass is already draining. The single drain loop
+  * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
+  * writes to the same table therefore collapses into one (or two) refresh
+  * passes instead of N, so each affected subscription's handler re-runs once
+  * per burst rather than once per write. `undefined` when nothing is pending.
+  */
+  private pendingRefreshTables;
+  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
+  private refreshInFlight;
+  /**
   * Last pushed result per `(socket, subId)`, keyed by socket. Lets
   * `refreshSubscriptions` skip re-running queries whose tables were
   * untouched and suppress pushes when the re-run result is unchanged. Held
@@ -4502,6 +4561,26 @@ declare abstract class ShardDO {
   */
   protected studioFeatures(): StudioFeaturesResult;
   /**
+  * Evaluate every statically-discovered feature flag under `context` for the
+  * studio's read-only Flags page (`__lunora_admin__:listFlags`). The flag keys
+  * + value types are discovered by `@lunora/codegen` from the app's
+  * `ctx.flags.<type>("key", …)` reads and evaluated through the configured
+  * `@lunora/flags` provider — work only the codegen subclass can do, so it
+  * overrides this. The base class wires no provider and reports
+  * `configured: false` with zero flags (an un-generated `ShardDO` has none).
+  */
+  protected evaluateFlags(_context?: Record<string, unknown>): Promise<FlagsResult>;
+  /**
+  * Serve one reserved {@link FLAGS_FUNCTION_PREFIX} live flag read for the
+  * React client's `useFlag`/`useFlags`. `functionPath` carries the flag key +
+  * type and `args` the per-subscriber targeting context; the codegen subclass
+  * overrides this to evaluate the flag through the app's `@lunora/flags`
+  * provider under `identity` and return the resolved value. The base class
+  * wires no provider, so it returns `null` — `resolveReactiveOutcome` reads
+  * `null` as "nothing to deliver" and the subscriber keeps its default.
+  */
+  protected runFlagSubscriptionRead(_functionPath: string, _arguments: Record<string, unknown>, _identity?: SubscriptionIdentity): Promise<unknown>;
+  /**
   * The Cloudflare Queues declared by this app, surfaced via
   * `__lunora_admin__:listQueues` for the studio's Queues page. Queues are NOT
   * Durable Objects and hold no shard state, so this is pure declaration
@@ -5013,6 +5092,16 @@ declare abstract class ShardDO {
   */
   private handleGetWorkflowInstanceStatus;
   /**
+  * Serve `__lunora_admin__:listFlags` — the studio's read-only Flags page.
+  * Evaluates every statically-discovered feature flag under an optional
+  * `args.context` targeting context (the studio's editable context editor)
+  * via the {@link evaluateFlags} hook, which the codegen subclass overrides
+  * with live OpenFeature evaluation. Read-only: a flag lookup mutates no shard
+  * state, so nothing is flushed or audited. Admin-gated by `handleAdminRpc`'s
+  * caller.
+  */
+  private handleListFlags;
+  /**
   * Run `run()` with the per-request identity pinned to (`userId`, `identity`),
   * then restore the prior values in a `finally` (even if `run()` throws), so the
   * forced identity can never leak into a later dispatch on this DO instance. The
@@ -5272,6 +5361,16 @@ declare abstract class ShardDO {
   */
   private executeAdminSubscription;
   /**
+  * Resolve one subscription (seed or refresh) to its {@link SubscriptionOutcome}
+  * by routing the `functionPath` to the right read path — shared by
+  * {@link seedSubscription} and {@link refreshSubscriptions} so both branch
+  * identically:
+  * - `__lunora_admin__:*` → {@link executeAdminSubscription} (raw SQLite read).
+  * - {@link FLAGS_FUNCTION_PREFIX} → {@link runFlagSubscriptionRead} (the codegen subclass evaluates the flag through the configured provider). The value isn't bound to any table, so it is tagged with the {@link ADMIN_WILDCARD} dep — re-evaluated on every write-flush so a live `useFlag` stays current within a session. A `null` read means "nothing to deliver" (no provider, or a flag that resolved to `null`).
+  * - everything else → {@link executeSubscription} (the user query, under the socket's own by-value identity).
+  */
+  private resolveReactiveOutcome;
+  /**
   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
   * `false` (closed) when the token is unset so admin introspection is
   * opt-in rather than exposed by default.
@@ -5303,6 +5402,17 @@ declare abstract class ShardDO {
   */
   private flushChangedTables;
   /**
+  * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
+  * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
+  * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
+  * by the next loop iteration, so every committed write is observed by a
+  * refresh that runs after it — bursts simply share a pass. The post-write
+  * high-watermark and live-socket set are re-read inside each
+  * `refreshSubscriptions` call, so a later batch always reflects the latest
+  * committed state.
+  */
+  private drainSubscriptionRefreshes;
+  /**
   * For every live subscription whose query reads one of `changed`, re-run
   * the query and push a fresh `{ type: "data" }` frame when the result
   * differs from the last one sent. Subscriptions with no `functionPath`
@@ -5689,4 +5799,4 @@ interface WhereSqlStrategy {
 * `undefined` when the input imposes no constraint (empty `where`).
 */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, listTables, matchesRankStaticWhere, matchesStaticWhere, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, listTables, matchesRankStaticWhere, matchesStaticWhere, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };

package/dist/index.d.ts

@@ -596,6 +596,7 @@ declare const rankTableName: (table: string, indexName: string) => string;
 * - `sortValues[i]` === `serializeSqlValue(doc[index.sortBy[i].field])` — the same transform `syncRankIndexEntry` applies to the stored `__sort_k<i>__` column, so the comparison is byte-for-byte (and JSON-safe for the cross-shard wire) regardless of which shard owns the row. `rankBefore` re-applies it idempotently, so a direct caller passing raw values still works.
 * - `rowId` === `doc._id`, the `__id__` tiebreak.
 */
+declare const stableStringify: (value: unknown) => string;
 /** A single memoized result, the deps it read, and any active subscribers. */
 interface CacheEntry {
   /** Approximate serialized size of `result`, charged against `maxBytes`. */
@@ -728,16 +729,6 @@ declare class ReactiveCache {
   private evict;
 }
 /**
-* Stable, sorted JSON encoding of `args` for use in a cache key. Object keys
-* are visited in lexical order at every depth so `{ a: 1, b: 2 }` and
-* `{ b: 2, a: 1 }` hash to the same string. Arrays preserve their order
-* (the index IS the key). `undefined` values are skipped at the object level
-* so `{ a: undefined }` collides with `{}` — matches Convex behavior and
-* avoids spurious cache misses on optional args. Inside arrays `undefined`
-* encodes as `null` to keep positional semantics.
-*/
-declare const stableStringify: (value: unknown) => string;
-/**
 * Compose a cache key from a function path, a stably-encoded args object, and
 * the caller's identity discriminator. Exported so the wiring layer and tests
 * build identical keys without each side reinventing the format.
@@ -2262,6 +2253,19 @@ declare const ADMIN_FUNCTION_PREFIX = "__lunora_admin__:";
 */
 declare const RELATION_FUNCTION_PREFIX = "__lunora_relation__:";
 /**
+* Reserved `functionPath` prefix for live feature-flag reads. The React client's
+* `useFlag`/`useFlags` subscribe to `__lunora_flags__:eval` over the same WS
+* channel as a user query; `ShardDO` intercepts it before user dispatch and
+* serves it from the codegen-overridden flag-subscription read hook, which
+* evaluates the flag through the app's OpenFeature provider under the socket's
+* verified identity. Like the other reserved prefixes it is NOT admin-gated (a
+* flag read is public, scoped to the subscriber's own targeting context), and
+* the `__lunora_` namespace is reserved so a real `<file>:<function>` can't
+* collide. Re-evaluated on every write-flush so values stay live within a
+* session (provider-side flips with no intervening write surface on reconnect).
+*/
+declare const FLAGS_FUNCTION_PREFIX = "__lunora_flags__:";
+/**
 * Fully-qualified reserved paths the data browser invokes. The
 * `__lunora_admin__:` prefix is spelled out inline rather than interpolated so
 * the values stay emittable under `--isolatedDeclarations`.
@@ -2292,6 +2296,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getSettings: "__lunora_admin__:getSettings";
   readonly getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus";
   readonly importShard: "__lunora_admin__:importShard";
+  readonly listFlags: "__lunora_admin__:listFlags";
   readonly listQueues: "__lunora_admin__:listQueues";
   readonly listTables: "__lunora_admin__:listTables";
   readonly listWorkflows: "__lunora_admin__:listWorkflows";
@@ -2572,6 +2577,8 @@ interface StorageRulesResult {
 * package's tests and the studio's fails the build if the two key sets diverge.
 */
 interface StudioFeaturesResult {
+  /** `@lunora/flags` / `ctx.flags` is used, or it is a declared dependency. */
+  flags: boolean;
   /** `@lunora/mail` is imported by a `lunora/` source or a declared dependency. */
   mail: boolean;
   /** `@lunora/payment` is used (import or `ctx.payments`) or a declared dependency. */
@@ -2588,6 +2595,40 @@ interface StudioFeaturesResult {
   workflows: boolean;
 }
 /**
+* One feature flag evaluated under a supplied targeting context, surfaced by
+* `__lunora_admin__:listFlags` for the studio's read-only Flags page. The `key`
+* and `type` are statically discovered by `@lunora/codegen` from the app's
+* `ctx.flags.<type>("key", …)` reads; `value`/`reason`/`variant`/`errorCode`
+* come from the live OpenFeature evaluation (the codegen subclass overrides the
+* base `evaluateFlags` hook). `value` is the resolved flag value as JSON.
+*/
+interface FlagEvaluation {
+  /** OpenFeature `errorCode` when the evaluation failed (the value falls back to the default). */
+  errorCode?: string;
+  /** The discovered flag key (the first argument of a `ctx.flags.<type>(...)` read). */
+  key: string;
+  /** OpenFeature `reason` for the resolution (`TARGETING_MATCH`, `DEFAULT`, `ERROR`, …). */
+  reason?: string;
+  /** The flag's value type, derived from which `ctx.flags.<type>` method read it. */
+  type: "boolean" | "number" | "object" | "string";
+  /** The resolved value (JSON), or the type default when unconfigured / on error. */
+  value: unknown;
+  /** OpenFeature `variant` identifier when the provider reports one. */
+  variant?: string;
+}
+/**
+* Payload of a `__lunora_admin__:listFlags` call: every statically-discovered
+* flag evaluated under the supplied targeting context. `configured` is `false`
+* when the app wires no `@lunora/flags` provider (the base hook), so the studio
+* can distinguish "no flags configured" from "configured but zero flags read".
+*/
+interface FlagsResult {
+  /** `true` when an `@lunora/flags` provider is wired (the codegen override ran). */
+  configured: boolean;
+  /** Each discovered flag evaluated under the request's targeting context. */
+  flags: FlagEvaluation[];
+}
+/**
 * One declared Cloudflare Workflow, surfaced by `__lunora_admin__:listWorkflows`
 * for the studio's Workflows page. Statically discovered by `@lunora/codegen`
 * from `lunora/workflows.ts` (the codegen subclass overrides the base hook);
@@ -3666,6 +3707,44 @@ declare class SessionDO {
   private handleRevoke;
 }
 /**
+* Diff the previously-sent list snapshot (`previousJson`, the memo's
+* `lastJson`) against the new query result and produce per-row
+* {@link MutationDelta}s the client can merge in place via `applyDelta` —
+* Convex-parity live-pagination deltas (server half of gap #20).
+*
+* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
+* unless ALL of these hold:
+*
+* 1. `previousJson` parses to an array (there IS a previous list to diff against).
+* 2. `nextResult` is also an array.
+* 3. Every row in both arrays is a plain object carrying a string `_id`.
+* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
+* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
+*
+* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
+* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
+* full new `row`; delete omits it (matching the wire contract `@lunora/client`
+* parses). Deltas are ordered deletes-then-inserts/updates so the client never
+* sees a transient over-length page.
+*
+* Per-row serialization is done exactly **once** per refresh (finding #6). Each
+* row is stringified a single time into a fingerprint reused for both the
+* `prev !== next` change-detection compare and — when the caller passes the
+* optional `frames` sink — the pre-serialized delta frame body. The returned
+* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
+* exact `JSON.stringify(delta)` string for each returned delta, in the same
+* order, so the caller can splice it straight into the `{type:"delta"}` frame
+* without serializing the delta (and the row inside it) a second time.
+* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
+*/
+declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
+/**
+* Send one WebSocket frame, reporting whether it left the socket. A throw from
+* `ws.send` (socket closed mid-flush, outbound buffer gone) is the only
+* delivery-failure signal the runtime exposes; callers use the boolean to decide
+* whether to advance a subscription's delivered-diff baseline.
+*/
+/**
 * Optional programmatic log sink, resolved from `createShardDO({ observability })`.
 * Structurally a subset of `@lunora/runtime`'s `ObservabilitySink`, so a user can
 * pass the SAME sink object to `createWorker` (which drives `onRpc`) and
@@ -3918,38 +3997,6 @@ interface RunShardRankPageArgs {
   take?: number;
 }
 /**
-* Diff the previously-sent list snapshot (`previousJson`, the memo's
-* `lastJson`) against the new query result and produce per-row
-* {@link MutationDelta}s the client can merge in place via `applyDelta` —
-* Convex-parity live-pagination deltas (server half of gap #20).
-*
-* Returns `undefined` (caller falls back to a full `{type:"data"}` snapshot)
-* unless ALL of these hold:
-*
-* 1. `previousJson` parses to an array (there IS a previous list to diff against).
-* 2. `nextResult` is also an array.
-* 3. Every row in both arrays is a plain object carrying a string `_id`.
-* 4. Order preservation — rows present in BOTH arrays appear in the same relative order.
-* 5. Chattiness cap — the number of deltas does not exceed the new array length (a near-total change is cheaper as a snapshot).
-*
-* Diff is keyed by `_id`: rows only in prev → `delete`; rows only in next →
-* `insert`; rows in both whose JSON differs → `update`. Insert/update carry the
-* full new `row`; delete omits it (matching the wire contract `@lunora/client`
-* parses). Deltas are ordered deletes-then-inserts/updates so the client never
-* sees a transient over-length page.
-*
-* Per-row serialization is done exactly **once** per refresh (finding #6). Each
-* row is stringified a single time into a fingerprint reused for both the
-* `prev !== next` change-detection compare and — when the caller passes the
-* optional `frames` sink — the pre-serialized delta frame body. The returned
-* `MutationDelta[]` shape is unchanged; `frames`, when supplied, receives the
-* exact `JSON.stringify(delta)` string for each returned delta, in the same
-* order, so the caller can splice it straight into the `{type:"delta"}` frame
-* without serializing the delta (and the row inside it) a second time.
-* @returns the per-row deltas to send, or `undefined` when any precondition fails and a full snapshot should be sent instead
-*/
-declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown, table: string, frames?: string[]) => MutationDelta[] | undefined;
-/**
 * Threshold at which a `__root__` DO triggers the size warning. 1 GiB —
 * exactly 10% of the 10 GiB per-DO SQLite ceiling, leaving plenty of runway
 * to plan a `.shardBy()` migration before the wall hits.
@@ -4131,6 +4178,18 @@ declare abstract class ShardDO {
   */
   private pendingChangedTables;
   /**
+  * Coalesced set of tables awaiting a subscription-refresh pass, merged
+  * across every {@link ShardDO.flushChangedTables} call that lands while a
+  * pass is already draining. The single drain loop
+  * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
+  * writes to the same table therefore collapses into one (or two) refresh
+  * passes instead of N, so each affected subscription's handler re-runs once
+  * per burst rather than once per write. `undefined` when nothing is pending.
+  */
+  private pendingRefreshTables;
+  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
+  private refreshInFlight;
+  /**
   * Last pushed result per `(socket, subId)`, keyed by socket. Lets
   * `refreshSubscriptions` skip re-running queries whose tables were
   * untouched and suppress pushes when the re-run result is unchanged. Held
@@ -4502,6 +4561,26 @@ declare abstract class ShardDO {
   */
   protected studioFeatures(): StudioFeaturesResult;
   /**
+  * Evaluate every statically-discovered feature flag under `context` for the
+  * studio's read-only Flags page (`__lunora_admin__:listFlags`). The flag keys
+  * + value types are discovered by `@lunora/codegen` from the app's
+  * `ctx.flags.<type>("key", …)` reads and evaluated through the configured
+  * `@lunora/flags` provider — work only the codegen subclass can do, so it
+  * overrides this. The base class wires no provider and reports
+  * `configured: false` with zero flags (an un-generated `ShardDO` has none).
+  */
+  protected evaluateFlags(_context?: Record<string, unknown>): Promise<FlagsResult>;
+  /**
+  * Serve one reserved {@link FLAGS_FUNCTION_PREFIX} live flag read for the
+  * React client's `useFlag`/`useFlags`. `functionPath` carries the flag key +
+  * type and `args` the per-subscriber targeting context; the codegen subclass
+  * overrides this to evaluate the flag through the app's `@lunora/flags`
+  * provider under `identity` and return the resolved value. The base class
+  * wires no provider, so it returns `null` — `resolveReactiveOutcome` reads
+  * `null` as "nothing to deliver" and the subscriber keeps its default.
+  */
+  protected runFlagSubscriptionRead(_functionPath: string, _arguments: Record<string, unknown>, _identity?: SubscriptionIdentity): Promise<unknown>;
+  /**
   * The Cloudflare Queues declared by this app, surfaced via
   * `__lunora_admin__:listQueues` for the studio's Queues page. Queues are NOT
   * Durable Objects and hold no shard state, so this is pure declaration
@@ -5013,6 +5092,16 @@ declare abstract class ShardDO {
   */
   private handleGetWorkflowInstanceStatus;
   /**
+  * Serve `__lunora_admin__:listFlags` — the studio's read-only Flags page.
+  * Evaluates every statically-discovered feature flag under an optional
+  * `args.context` targeting context (the studio's editable context editor)
+  * via the {@link evaluateFlags} hook, which the codegen subclass overrides
+  * with live OpenFeature evaluation. Read-only: a flag lookup mutates no shard
+  * state, so nothing is flushed or audited. Admin-gated by `handleAdminRpc`'s
+  * caller.
+  */
+  private handleListFlags;
+  /**
   * Run `run()` with the per-request identity pinned to (`userId`, `identity`),
   * then restore the prior values in a `finally` (even if `run()` throws), so the
   * forced identity can never leak into a later dispatch on this DO instance. The
@@ -5272,6 +5361,16 @@ declare abstract class ShardDO {
   */
   private executeAdminSubscription;
   /**
+  * Resolve one subscription (seed or refresh) to its {@link SubscriptionOutcome}
+  * by routing the `functionPath` to the right read path — shared by
+  * {@link seedSubscription} and {@link refreshSubscriptions} so both branch
+  * identically:
+  * - `__lunora_admin__:*` → {@link executeAdminSubscription} (raw SQLite read).
+  * - {@link FLAGS_FUNCTION_PREFIX} → {@link runFlagSubscriptionRead} (the codegen subclass evaluates the flag through the configured provider). The value isn't bound to any table, so it is tagged with the {@link ADMIN_WILDCARD} dep — re-evaluated on every write-flush so a live `useFlag` stays current within a session. A `null` read means "nothing to deliver" (no provider, or a flag that resolved to `null`).
+  * - everything else → {@link executeSubscription} (the user query, under the socket's own by-value identity).
+  */
+  private resolveReactiveOutcome;
+  /**
   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
   * `false` (closed) when the token is unset so admin introspection is
   * opt-in rather than exposed by default.
@@ -5303,6 +5402,17 @@ declare abstract class ShardDO {
   */
   private flushChangedTables;
   /**
+  * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
+  * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
+  * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
+  * by the next loop iteration, so every committed write is observed by a
+  * refresh that runs after it — bursts simply share a pass. The post-write
+  * high-watermark and live-socket set are re-read inside each
+  * `refreshSubscriptions` call, so a later batch always reflects the latest
+  * committed state.
+  */
+  private drainSubscriptionRefreshes;
+  /**
   * For every live subscription whose query reads one of `changed`, re-run
   * the query and push a fresh `{ type: "data" }` frame when the result
   * differs from the last one sent. Subscriptions with no `functionPath`
@@ -5689,4 +5799,4 @@ interface WhereSqlStrategy {
 * `undefined` when the input imposes no constraint (empty `where`).
 */
 declare const compileWhereSql: (where: WhereInput | undefined, strategy: WhereSqlStrategy) => SQL | undefined;
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, listTables, matchesRankStaticWhere, matchesStaticWhere, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, AGGREGATE_SQL_FUNCTION, AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, type AdvisoriesResult, type AdvisoryFinding, type AggregateIndexDefinitionLike, type AggregateOp, type AggregateOptions, type AggregateResult, type AggregateTally, type ApplyOnDeleteOptions, type AuditEntry, type AuditLogResult, type AuthMetrics, type AuthMetricsBucket, type BroadcastDelta, CDC_LOG_TABLE, type CacheEntry, type CapturedMailRow, type CdcChange, type Clock, type ColumnMeta, type ColumnMetaLike, ConflictError, type CountArgs, CountRlsUnsupportedError, type CtxDbOptions, DATA_MIGRATION_STATE_TABLE, DEFAULT_MAX_RELATION_KEYS, type DataMigrationDocument, type DataMigrationLike, type DataMigrationTransform, type DatabaseWriterLike, type DependencyTracker, type DeployInfo, type ExportRow, type ExportShardAdminArgs, type ExportShardArgs, FLAGS_FUNCTION_PREFIX, FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, type FacetColumnOptions, type FacetColumnResult, type FacetValue, type FieldOperators, type FlagEvaluation, type FlagsResult, type FunctionCallStat, type FunctionMetricBucket, type FunctionMetricIndexHit, type FunctionStatsResult, type GroupByEntry, type GroupByOptions, type HibernatableWebSocket, type IdGenerator, type ImportError, type ImportShardAdminArgs, type ImportShardArgs, type ImportShardResult, type IndexDefinitionLike, type IndexRangeBuilderLike, LogBuffer, type LogEntry, type LogEventInput, type LogLevel, type LogSink, MAIL_RETENTION, MAIL_TABLE, MAX_SQL_ROWS, MIN_ADMIN_TOKEN_LENGTH, MIN_AUTH_SECRET_LENGTH, type MaskColumnMetadata, type MaskPoliciesResult, type MigrationDirection, type MigrationRunResult, type MigrationStatus, type MigrationStatusRow, type MutationDelta, type NestedWith, NotFoundError, NotUniqueError, type OnDeleteActionLike, type OrderByInput, type OrderKey, type PaginationOptions, type PitrBookmarkResult, type PitrRestoreArgs, type PitrRestoreResult, type PitrStorage, type QueryArgs, type QueryPage, type QueueMetadata, type QueuesResult, RANK_TIEBREAK, RELATION_FUNCTION_PREFIX, RLS_UNWRAP_SYMBOL, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RankDirection, type RankIndexDefinitionLike, type RankOptions, type RankPage, type RankPageOptions, type RankPageRow, type RankPageRowKey, type RankResult, type RankSortKeyLike, ReactiveCache, type ReactiveCacheOptions, type ReadHook, type ReadTablePageOptions, type RecordAuthEventInput, type RecordFunctionMetricInput, type RecordMailInput, type RelationDefinitionLike, type RenderedSql, type ResolveRelationPredicatesOptions, type ResolveWithOptions, type RestrictableQueryOptions, type RlsPoliciesResult, type RlsPolicyMetadata, RlsRequiredError, type RlsRoleMetadata, type RpcRequest, type RunDataMigrationOptions, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkDeleteArgs, type RunShardBulkDeleteResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, type RunTriggersOptions, SCAN_DEP, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, type ScheduledFunctionDoc, type SchedulerLike, type SchemaLike, type SearchFilterBuilderLike, type SecurityAuditResult, type SecurityFinding, type SecurityFindingKind, type SecurityFindingLevel, type SelectMatchingIdsOptions, type ServerDefaultContextLike, SessionDO, type SessionRecord, type SettingEntry, type SettingKind, type SettingsResult, ShardDO, type ShardDOOptions, type ShardDOState, type ShardRankPageResult, ShardRegistryDO, type SocketAttachment, type SortDirection, type SqlConsoleResult, type SqlCursor, type SqlEngine, type SqlExec, type StorageRuleMetadata, type StorageRulesResult, type StudioFeaturesResult, type SubscriptionEnvelope, type SubscriptionOutcome, type SubscriptionQuery, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemReaderOptions, type SystemReaderSchedulerLike, type SystemReaderStorageLike, type SystemTableName, type TableColumnsResult, type TableDefinitionLike, type TableIndexInfo, type TableIndexesResult, type TableInfo, type TablePage, type TableReaderLike, type TablesColumnsResult, type TransactionSqlLike, type TriggerContextLike, type TriggerDefinitionLike, type TriggerEventLike, type TriggerOpLike, type TriggerTimingLike, type ValidatorLike, type WhereInput, type WhereSqlStrategy, type WithInput, type WorkflowMetadata, type WorkflowsResult, type WriteEvent, type WriteHook, aggregateSqlFunction, aggregateTableName, applyCdcChanges, applyOnDelete, applySelect, armRestore, assertFlatPredicate, assertReadonly, assertValidClientId, backfillAggregateIndexes, backfillRankIndexes, buildFtsMatch, buildSecurityAudit, buildSeekWhere, clearCapturedMail, coerceAggregateNumber, compileWhereSql, containsRelationPredicate, createDependencyTracker, createShardCtxDb, createSystemReader, decodeCursor, depKey, encodeAggregateKey, encodeCursor, encodePartitionKey, ensureAuthMetricsTables, ensureFunctionMetricsTables, ensureMailTable, exportShardRows, exportShardTable, facetColumn, foldAggregateTally, ftsTableName, guardWriter, hasTrigger, importShardRows, isRelationPredicate, listTables, matchesRankStaticWhere, matchesStaticWhere, mergeWhere, normalizeCountArgument, normalizeIdStructurally, normalizeOrderKeys, parseExportShardArgs, parseImportShardArgs, planAggregateLookup, rankTableName, reactiveCacheKey, readAggregateValue, readAuthMetrics, readBookmark, readCapturedMail, readCdcChanges, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, readMigrationStatus, readTablePage, recordAuthEvent, recordCapturedMail, recordFunctionMetric, renderSql, resolveRankPartition, resolveRelationPredicates, resolveWith, runDataMigration, runReadonlySql, runRowValidators, runShardMigrations, runTriggers, scoreDocument, selectExportTables, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy, selectMatchingIds, serveRelationFanout, softDeleteScope, sortColumnName, stableStringify, stringifySearchText, subscriptionListDeltas, throwingScheduler, tokenizeSearch, trimCdcChanges, validateImportRow };

package/dist/index.mjs

@@ -8,22 +8,22 @@ export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } fro
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
 export { renderSql } from './packem_shared/renderSql-D6eUcn2N.mjs';
 export { FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, ensureFunctionMetricsTables, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, recordFunctionMetric } from './packem_shared/FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-CHcC8fKV.mjs';
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-D_UiYJFk.mjs';
 export { LogBuffer } from './packem_shared/LogBuffer-B_Ezju_N.mjs';
 export { MAIL_RETENTION, MAIL_TABLE, clearCapturedMail, ensureMailTable, readCapturedMail, recordCapturedMail } from './packem_shared/MAIL_RETENTION-CPpgl-dX.mjs';
 export { default as NotFoundError } from './packem_shared/NotFoundError-CMuMZt81.mjs';
 export { armRestore, readBookmark } from './packem_shared/armRestore-BJk53Ro8.mjs';
 export { applySelect, buildSeekWhere, decodeCursor, encodeCursor, normalizeOrderKeys, softDeleteScope } from './packem_shared/applySelect-BvZdFUBT.mjs';
 export { R as RANK_TIEBREAK, e as encodePartitionKey, m as matchesRankStaticWhere, r as rankTableName, a as resolveRankPartition, s as sortColumnName } from './packem_shared/rank-CrkEIpF4.mjs';
-export { ReactiveCache, reactiveCacheKey, stableStringify } from './packem_shared/ReactiveCache-ByVzgH3d.mjs';
-export { serveRelationFanout } from './packem_shared/serveRelationFanout-oxaM6_WL.mjs';
+export { ReactiveCache, reactiveCacheKey } from './packem_shared/ReactiveCache-1hDydFyv.mjs';
+export { serveRelationFanout } from './packem_shared/serveRelationFanout-C6lDaesn.mjs';
 export { DEFAULT_MAX_RELATION_KEYS, assertFlatPredicate, containsRelationPredicate, isRelationPredicate, resolveRelationPredicates } from './packem_shared/DEFAULT_MAX_RELATION_KEYS-Dou2PWdO.mjs';
 export { applyOnDelete, resolveWith, runRowValidators } from './packem_shared/applyOnDelete-sA7o1CqD.mjs';
 export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_shared/RLS_UNWRAP_SYMBOL-EtGQdC9d.mjs';
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-ilPZsVwu.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO, subscriptionListDeltas } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-DfwcxW8F.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-BCz6GIDw.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-dDcFE1YZ.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-8CzSZP9V.mjs';
@@ -33,3 +33,5 @@ export { compileWhereSql } from './packem_shared/compileWhereSql-CXrhFA3G.mjs';
 export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-Ctdmxmrv.mjs';
 export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-BbVPvciS.mjs';
 export { runShardMigrations } from './packem_shared/runShardMigrations-PabobOjF.mjs';
+export { stableStringify } from './packem_shared/stableStringify-CyHKJXre.mjs';
+export { subscriptionListDeltas } from './packem_shared/subscriptionListDeltas-ce84gpwL.mjs';

package/dist/packem_shared/{ADMIN_FUNCTIONS-CHcC8fKV.mjs → ADMIN_FUNCTIONS-D_UiYJFk.mjs}

@@ -1,5 +1,6 @@
 const ADMIN_FUNCTION_PREFIX = "__lunora_admin__:";
 const RELATION_FUNCTION_PREFIX = "__lunora_relation__:";
+const FLAGS_FUNCTION_PREFIX = "__lunora_flags__:";
 const ADMIN_FUNCTIONS = {
   applyCdc: "__lunora_admin__:applyCdc",
   cdcSync: "__lunora_admin__:cdcSync",
@@ -27,6 +28,7 @@ const ADMIN_FUNCTIONS = {
   // eslint-disable-next-line no-secrets/no-secrets -- reserved admin RPC path constant, not a credential
   getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus",
   importShard: "__lunora_admin__:importShard",
+  listFlags: "__lunora_admin__:listFlags",
   listQueues: "__lunora_admin__:listQueues",
   listTables: "__lunora_admin__:listTables",
   listWorkflows: "__lunora_admin__:listWorkflows",
@@ -311,4 +313,4 @@ const summarizeSubscriptions = (attachments) => {
   return { connections, totalConnections: connections.length, totalSubscriptions };
 };
 
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, MAX_PAGE_SIZE, RELATION_FUNCTION_PREFIX, facetColumn, findStorageReferences, listTables, readTablePage, selectMatchingIds, summarizeSubscriptions };
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, MAX_PAGE_SIZE, RELATION_FUNCTION_PREFIX, facetColumn, findStorageReferences, listTables, readTablePage, selectMatchingIds, summarizeSubscriptions };

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-DfwcxW8F.mjs → ROOT_DO_SIZE_WARN_BYTES-BCz6GIDw.mjs}

@@ -4,14 +4,15 @@ import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-C
 import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
 import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
 import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-CHcC8fKV.mjs';
+import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-D_UiYJFk.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
 import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
 import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-ByVzgH3d.mjs';
+import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-1hDydFyv.mjs';
 import { redact, standardRules } from '@visulima/redact';
 import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } from './security-audit-CucgBice.mjs';
 import { runReadonlySql } from './MAX_SQL_ROWS-dDcFE1YZ.mjs';
+import { trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-ce84gpwL.mjs';
 import { ConflictError } from './ConflictError-C0STs6bU.mjs';
 import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-Ctdmxmrv.mjs';
 import { r as readIdempotent, w as writeIdempotent, t as trimIdempotent } from './ctx-db-idempotency-DkC9rP91.mjs';
@@ -413,97 +414,7 @@ const findDanglingReferences = (sql, storageColumns, liveKeys) => {
 
 const WS_KEEPALIVE_PING = "lunora-ping";
 const WS_KEEPALIVE_PONG = "lunora-pong";
-const ROW_ID_FIELD = "_id";
-const DELTA_FALLBACK_TABLE = "__lunora__";
-const readRowId = (row) => {
-  if (typeof row !== "object" || row === null || Array.isArray(row)) {
-    return void 0;
-  }
-  const id = row[ROW_ID_FIELD];
-  return typeof id === "string" ? id : void 0;
-};
-const indexRowsById = (rows) => {
-  const byId = /* @__PURE__ */ new Map();
-  const order = [];
-  for (const row of rows) {
-    const id = readRowId(row);
-    if (id === void 0 || byId.has(id)) {
-      return void 0;
-    }
-    byId.set(id, row);
-    order.push(id);
-  }
-  return { byId, order };
-};
-const survivorsKeepOrder = (previous, next) => {
-  const survivingPrevious = previous.order.filter((id) => next.byId.has(id));
-  const survivingNext = next.order.filter((id) => previous.byId.has(id));
-  if (survivingPrevious.length !== survivingNext.length) {
-    return false;
-  }
-  return survivingPrevious.every((id, index) => survivingNext[index] === id);
-};
-const collectDeleteDeltas = (previous, next, deltaTable, tableJson) => {
-  const out = [];
-  for (const id of previous.order) {
-    if (!next.byId.has(id)) {
-      out.push({
-        delta: { key: id, op: "delete", table: deltaTable },
-        frame: `{"key":${JSON.stringify(id)},"op":"delete","table":${tableJson}}`
-      });
-    }
-  }
-  return out;
-};
-const collectUpsertDeltas = (previous, next, deltaTable, tableJson) => {
-  const out = [];
-  for (const id of next.order) {
-    const nextRow = next.byId.get(id);
-    const previousRow = previous.byId.get(id);
-    const nextFingerprint = JSON.stringify(nextRow);
-    const previousFingerprint = previousRow === void 0 ? void 0 : JSON.stringify(previousRow);
-    if (previousFingerprint === nextFingerprint) {
-      continue;
-    }
-    const op = previousFingerprint === void 0 ? "insert" : "update";
-    out.push({
-      delta: { key: id, op, row: nextRow, table: deltaTable },
-      frame: `{"key":${JSON.stringify(id)},"op":"${op}","row":${nextFingerprint},"table":${tableJson}}`
-    });
-  }
-  return out;
-};
-const subscriptionListDeltas = (previousJson, nextResult, table, frames) => {
-  let parsed;
-  try {
-    parsed = JSON.parse(previousJson);
-  } catch {
-    return void 0;
-  }
-  if (!Array.isArray(parsed) || !Array.isArray(nextResult)) {
-    return void 0;
-  }
-  const previous = indexRowsById(parsed);
-  const next = indexRowsById(nextResult);
-  if (previous === void 0 || next === void 0) {
-    return void 0;
-  }
-  if (!survivorsKeepOrder(previous, next)) {
-    return void 0;
-  }
-  const deltaTable = table === "" ? DELTA_FALLBACK_TABLE : table;
-  const tableJson = JSON.stringify(deltaTable);
-  const framed = [...collectDeleteDeltas(previous, next, deltaTable, tableJson), ...collectUpsertDeltas(previous, next, deltaTable, tableJson)];
-  if (framed.length > next.order.length) {
-    return void 0;
-  }
-  if (frames !== void 0) {
-    for (const { frame } of framed) {
-      frames.push(frame);
-    }
-  }
-  return framed.map(({ delta }) => delta);
-};
+const UNDELIVERED_BASELINE = "<undelivered>";
 const ROOT_DO_SIZE_WARN_BYTES = 1073741824;
 const CDC_RESUME_SCAN_LIMIT = 1e4;
 const IDEMPOTENCY_RETENTION_MS = 864e5;
@@ -1133,6 +1044,18 @@ class ShardDO {
    * the common read-only path allocates nothing.
    */
   pendingChangedTables = void 0;
+  /**
+   * Coalesced set of tables awaiting a subscription-refresh pass, merged
+   * across every {@link ShardDO.flushChangedTables} call that lands while a
+   * pass is already draining. The single drain loop
+   * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
+   * writes to the same table therefore collapses into one (or two) refresh
+   * passes instead of N, so each affected subscription's handler re-runs once
+   * per burst rather than once per write. `undefined` when nothing is pending.
+   */
+  pendingRefreshTables = void 0;
+  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
+  refreshInFlight = false;
   /**
    * Last pushed result per `(socket, subId)`, keyed by socket. Lets
    * `refreshSubscriptions` skip re-running queries whose tables were
@@ -1853,7 +1776,33 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the statically-discovered feature flags
   studioFeatures() {
-    return { mail: false, payments: false, queues: false, scheduler: false, storage: false, vectors: false, workflows: false };
+    return { flags: false, mail: false, payments: false, queues: false, scheduler: false, storage: false, vectors: false, workflows: false };
+  }
+  /**
+   * Evaluate every statically-discovered feature flag under `context` for the
+   * studio's read-only Flags page (`__lunora_admin__:listFlags`). The flag keys
+   * + value types are discovered by `@lunora/codegen` from the app's
+   * `ctx.flags.&lt;type>("key", …)` reads and evaluated through the configured
+   * `@lunora/flags` provider — work only the codegen subclass can do, so it
+   * overrides this. The base class wires no provider and reports
+   * `configured: false` with zero flags (an un-generated `ShardDO` has none).
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with live OpenFeature evaluation over the discovered flag keys
+  evaluateFlags(_context) {
+    return Promise.resolve({ configured: false, flags: [] });
+  }
+  /**
+   * Serve one reserved {@link FLAGS_FUNCTION_PREFIX} live flag read for the
+   * React client's `useFlag`/`useFlags`. `functionPath` carries the flag key +
+   * type and `args` the per-subscriber targeting context; the codegen subclass
+   * overrides this to evaluate the flag through the app's `@lunora/flags`
+   * provider under `identity` and return the resolved value. The base class
+   * wires no provider, so it returns `null` — `resolveReactiveOutcome` reads
+   * `null` as "nothing to deliver" and the subscriber keeps its default.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to evaluate the flag through the configured provider
+  runFlagSubscriptionRead(_functionPath, _arguments, _identity) {
+    return Promise.resolve(null);
   }
   /**
    * The Cloudflare Queues declared by this app, surfaced via
@@ -2249,10 +2198,7 @@ class ShardDO {
         if (!this.matchesSubscription(query, delta)) {
           continue;
         }
-        try {
-          ws.send(`{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
-        } catch {
-        }
+        trySendFrame(ws, `{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
       }
     }
   }
@@ -2808,6 +2754,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getWorkflowInstanceStatus) {
       return this.handleGetWorkflowInstanceStatus(args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.listFlags) {
+      return this.handleListFlags(args);
+    }
     return this.handlePitrAdminOp(functionPath, args);
   }
   /**
@@ -2928,6 +2877,21 @@ class ShardDO {
     return jsonResponse({ result }, 200);
   }
   /* eslint-enable no-secrets/no-secrets */
+  /**
+   * Serve `__lunora_admin__:listFlags` — the studio's read-only Flags page.
+   * Evaluates every statically-discovered feature flag under an optional
+   * `args.context` targeting context (the studio's editable context editor)
+   * via the {@link evaluateFlags} hook, which the codegen subclass overrides
+   * with live OpenFeature evaluation. Read-only: a flag lookup mutates no shard
+   * state, so nothing is flushed or audited. Admin-gated by `handleAdminRpc`'s
+   * caller.
+   */
+  async handleListFlags(args) {
+    const rawContext = args.context;
+    const context = typeof rawContext === "object" && rawContext !== null && !Array.isArray(rawContext) ? rawContext : void 0;
+    const result = await this.evaluateFlags(context);
+    return jsonResponse({ result }, 200);
+  }
   /**
    * Run `run()` with the per-request identity pinned to (`userId`, `identity`),
    * then restore the prior values in a `finally` (even if `run()` throws), so the
@@ -3469,6 +3433,25 @@ class ShardDO {
     const read = this.readAdminOp(functionPath, args);
     return read ? { result: read.result, tables: read.tables } : null;
   }
+  /**
+   * Resolve one subscription (seed or refresh) to its {@link SubscriptionOutcome}
+   * by routing the `functionPath` to the right read path — shared by
+   * {@link seedSubscription} and {@link refreshSubscriptions} so both branch
+   * identically:
+   * - `__lunora_admin__:*` → {@link executeAdminSubscription} (raw SQLite read).
+   * - {@link FLAGS_FUNCTION_PREFIX} → {@link runFlagSubscriptionRead} (the codegen subclass evaluates the flag through the configured provider). The value isn't bound to any table, so it is tagged with the {@link ADMIN_WILDCARD} dep — re-evaluated on every write-flush so a live `useFlag` stays current within a session. A `null` read means "nothing to deliver" (no provider, or a flag that resolved to `null`).
+   * - everything else → {@link executeSubscription} (the user query, under the socket's own by-value identity).
+   */
+  async resolveReactiveOutcome(functionPath, args, isAdmin, identity) {
+    if (isAdmin) {
+      return this.executeAdminSubscription(functionPath, args);
+    }
+    if (functionPath.startsWith(FLAGS_FUNCTION_PREFIX)) {
+      const result = await this.runFlagSubscriptionRead(functionPath, args, identity);
+      return result === null ? null : { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+    }
+    return this.executeSubscription(functionPath, args, identity);
+  }
   /**
    * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
    * `false` (closed) when the token is unset so admin introspection is
@@ -3567,11 +3550,47 @@ class ShardDO {
     if (!changed || changed.size === 0) {
       return;
     }
+    if (this.pendingRefreshTables) {
+      for (const table of changed) {
+        this.pendingRefreshTables.add(table);
+      }
+    } else {
+      this.pendingRefreshTables = changed;
+    }
+    if (this.refreshInFlight) {
+      return;
+    }
     if (typeof this.state.waitUntil === "function") {
-      this.state.waitUntil(this.refreshSubscriptions(changed));
+      this.state.waitUntil(this.drainSubscriptionRefreshes());
       return;
     }
-    await this.refreshSubscriptions(changed);
+    await this.drainSubscriptionRefreshes();
+  }
+  /**
+   * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
+   * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
+   * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
+   * by the next loop iteration, so every committed write is observed by a
+   * refresh that runs after it — bursts simply share a pass. The post-write
+   * high-watermark and live-socket set are re-read inside each
+   * `refreshSubscriptions` call, so a later batch always reflects the latest
+   * committed state.
+   */
+  async drainSubscriptionRefreshes() {
+    if (this.refreshInFlight) {
+      return;
+    }
+    this.refreshInFlight = true;
+    try {
+      let batch = this.pendingRefreshTables;
+      while (batch && batch.size > 0) {
+        this.pendingRefreshTables = void 0;
+        await this.refreshSubscriptions(batch);
+        batch = this.pendingRefreshTables;
+      }
+    } finally {
+      this.refreshInFlight = false;
+    }
   }
   /**
    * For every live subscription whose query reads one of `changed`, re-run
@@ -3649,15 +3668,10 @@ class ShardDO {
           continue;
         }
         try {
-          const outcome = isAdmin ? this.executeAdminSubscription(functionPath, query.args ?? {}) : (
-            // Re-run under the socket's OWN verified identity (stamped on the
-            // attachment at upgrade, unforgeable by the client) — passed BY
-            // VALUE, so this deferred re-run never reads or mutates the shared
-            // per-request identity fields. Without it an `rls()` / `ctx.auth`
-            // scoped live query would evaluate anonymous and return zero rows.
-            // eslint-disable-next-line no-await-in-loop -- subscriptions on a socket re-run sequentially; each shares the single SQLite handle
-            await this.executeSubscription(functionPath, query.args ?? {}, { identity: attachment.identity, userId: attachment.userId })
-          );
+          const outcome = await this.resolveReactiveOutcome(functionPath, query.args ?? {}, isAdmin, {
+            identity: attachment.identity,
+            userId: attachment.userId
+          });
           if (!outcome) {
             continue;
           }
@@ -3699,7 +3713,10 @@ class ShardDO {
   async seedSubscription(ws, subId, query, functionPath, isAdmin) {
     const seedArgs = query.args ?? {};
     const attachment = this.readAttachment(ws);
-    const outcome = isAdmin ? this.executeAdminSubscription(functionPath, seedArgs) : await this.executeSubscription(functionPath, seedArgs, { identity: attachment.identity, userId: attachment.userId });
+    const outcome = await this.resolveReactiveOutcome(functionPath, seedArgs, isAdmin, {
+      identity: attachment.identity,
+      userId: attachment.userId
+    });
     if (!outcome) {
       return;
     }
@@ -3763,21 +3780,8 @@ class ShardDO {
     }
     const deltaFrames = [];
     const deltas = existing === void 0 ? void 0 : subscriptionListDeltas(existing.lastJson, outcome.result, outcome.tables.values().next().value ?? "", deltaFrames);
-    memos.set(subId, { lastJson: json, tables: outcome.tables });
-    if (deltas !== void 0) {
-      const idJson = JSON.stringify(subId);
-      for (const deltaBody of deltaFrames) {
-        try {
-          ws.send(`{"type":"delta","id":${idJson},"delta":${deltaBody}${cursorSuffix}}`);
-        } catch {
-        }
-      }
-      return;
-    }
-    try {
-      ws.send(`{"type":"data","id":${JSON.stringify(subId)},"data":${json}${cursorSuffix}}`);
-    } catch {
-    }
+    const delivered = deltas === void 0 ? trySendFrame(ws, `{"type":"data","id":${JSON.stringify(subId)},"data":${json}${cursorSuffix}}`) : sendDeltaFrames(ws, subId, deltaFrames, cursorSuffix);
+    memos.set(subId, { lastJson: delivered ? json : existing?.lastJson ?? UNDELIVERED_BASELINE, tables: outcome.tables });
   }
   /**
    * Gate the upgrade request against two complementary controls:
@@ -3999,10 +4003,7 @@ class ShardDO {
       if (ws === sender || this.readAttachment(ws).whispers?.includes(topic) !== true) {
         continue;
       }
-      try {
-        ws.send(frame);
-      } catch {
-      }
+      trySendFrame(ws, frame);
     }
   }
   // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method grouped with the hibernation/attachment helpers; reads only the socket

package/dist/packem_shared/{ReactiveCache-ByVzgH3d.mjs → ReactiveCache-1hDydFyv.mjs}

@@ -1,11 +1,6 @@
+import { stableStringify } from './stableStringify-CyHKJXre.mjs';
 import { depKey, SCAN_DEP } from './SCAN_DEP-DLJF8dsj.mjs';
 
-const compareKeys = (a, b) => {
-  if (a < b) {
-    return -1;
-  }
-  return a > b ? 1 : 0;
-};
 const DEFAULT_MAX_ENTRIES = 1e3;
 const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
 const estimateBytes = (value) => {
@@ -232,28 +227,6 @@ class ReactiveCache {
     }
   }
 }
-const stableStringify = (value) => {
-  if (value === void 0) {
-    return "null";
-  }
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
-  }
-  const record = value;
-  const keys = Object.keys(record).toSorted(compareKeys);
-  const parts = [];
-  for (const key of keys) {
-    const raw = record[key];
-    if (raw === void 0) {
-      continue;
-    }
-    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
-  }
-  return `{${parts.join(",")}}`;
-};
 const reactiveCacheKey = (functionPath, args, identity) => `${identity ?? "\0anon"}\0${functionPath}:${stableStringify(args)}`;
 
 export { ReactiveCache, reactiveCacheKey, stableStringify };

package/dist/packem_shared/{serveRelationFanout-oxaM6_WL.mjs → serveRelationFanout-C6lDaesn.mjs}

@@ -1,4 +1,4 @@
-import { RELATION_FUNCTION_PREFIX } from './ADMIN_FUNCTIONS-CHcC8fKV.mjs';
+import { RELATION_FUNCTION_PREFIX } from './ADMIN_FUNCTIONS-D_UiYJFk.mjs';
 
 const serveRelationFanout = async (schema, database, functionPath, args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";

package/dist/packem_shared/stableStringify-CyHKJXre.mjs

@@ -0,0 +1,30 @@
+const compareKeys = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const record = value;
+  const keys = Object.keys(record).toSorted(compareKeys);
+  const parts = [];
+  for (const key of keys) {
+    const raw = record[key];
+    if (raw === void 0) {
+      continue;
+    }
+    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
+  }
+  return `{${parts.join(",")}}`;
+};
+
+export { stableStringify };

package/dist/packem_shared/subscriptionListDeltas-ce84gpwL.mjs

@@ -0,0 +1,111 @@
+const ROW_ID_FIELD = "_id";
+const DELTA_FALLBACK_TABLE = "__lunora__";
+const readRowId = (row) => {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) {
+    return void 0;
+  }
+  const id = row[ROW_ID_FIELD];
+  return typeof id === "string" ? id : void 0;
+};
+const indexRowsById = (rows) => {
+  const byId = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const row of rows) {
+    const id = readRowId(row);
+    if (id === void 0 || byId.has(id)) {
+      return void 0;
+    }
+    byId.set(id, row);
+    order.push(id);
+  }
+  return { byId, order };
+};
+const survivorsKeepOrder = (previous, next) => {
+  const survivingPrevious = previous.order.filter((id) => next.byId.has(id));
+  const survivingNext = next.order.filter((id) => previous.byId.has(id));
+  if (survivingPrevious.length !== survivingNext.length) {
+    return false;
+  }
+  return survivingPrevious.every((id, index) => survivingNext[index] === id);
+};
+const collectDeleteDeltas = (previous, next, deltaTable, tableJson) => {
+  const out = [];
+  for (const id of previous.order) {
+    if (!next.byId.has(id)) {
+      out.push({
+        delta: { key: id, op: "delete", table: deltaTable },
+        frame: `{"key":${JSON.stringify(id)},"op":"delete","table":${tableJson}}`
+      });
+    }
+  }
+  return out;
+};
+const collectUpsertDeltas = (previous, next, deltaTable, tableJson) => {
+  const out = [];
+  for (const id of next.order) {
+    const nextRow = next.byId.get(id);
+    const previousRow = previous.byId.get(id);
+    const nextFingerprint = JSON.stringify(nextRow);
+    const previousFingerprint = previousRow === void 0 ? void 0 : JSON.stringify(previousRow);
+    if (previousFingerprint === nextFingerprint) {
+      continue;
+    }
+    const op = previousFingerprint === void 0 ? "insert" : "update";
+    out.push({
+      delta: { key: id, op, row: nextRow, table: deltaTable },
+      frame: `{"key":${JSON.stringify(id)},"op":"${op}","row":${nextFingerprint},"table":${tableJson}}`
+    });
+  }
+  return out;
+};
+const subscriptionListDeltas = (previousJson, nextResult, table, frames) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(previousJson);
+  } catch {
+    return void 0;
+  }
+  if (!Array.isArray(parsed) || !Array.isArray(nextResult)) {
+    return void 0;
+  }
+  const previous = indexRowsById(parsed);
+  const next = indexRowsById(nextResult);
+  if (previous === void 0 || next === void 0) {
+    return void 0;
+  }
+  if (!survivorsKeepOrder(previous, next)) {
+    return void 0;
+  }
+  const deltaTable = table === "" ? DELTA_FALLBACK_TABLE : table;
+  const tableJson = JSON.stringify(deltaTable);
+  const framed = [...collectDeleteDeltas(previous, next, deltaTable, tableJson), ...collectUpsertDeltas(previous, next, deltaTable, tableJson)];
+  if (framed.length > next.order.length) {
+    return void 0;
+  }
+  if (frames !== void 0) {
+    for (const { frame } of framed) {
+      frames.push(frame);
+    }
+  }
+  return framed.map(({ delta }) => delta);
+};
+const trySendFrame = (ws, frame) => {
+  try {
+    ws.send(frame);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const sendDeltaFrames = (ws, subId, deltaFrames, cursorSuffix) => {
+  const idJson = JSON.stringify(subId);
+  let delivered = true;
+  for (const deltaBody of deltaFrames) {
+    if (!trySendFrame(ws, `{"type":"delta","id":${idJson},"delta":${deltaBody}${cursorSuffix}}`)) {
+      delivered = false;
+    }
+  }
+  return delivered;
+};
+
+export { sendDeltaFrames, subscriptionListDeltas, trySendFrame };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",