@lunora/do 1.0.0-alpha.7 → 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);
@@ -4520,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
@@ -5031,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
@@ -5290,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.
@@ -5718,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);
@@ -4520,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
@@ -5031,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
@@ -5290,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.
@@ -5718,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 } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-2DxWrdla.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,4 +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-2DxWrdla.mjs → ROOT_DO_SIZE_WARN_BYTES-BCz6GIDw.mjs}

@@ -4,11 +4,11 @@ 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';
@@ -1776,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.<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
@@ -2728,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);
   }
   /**
@@ -2848,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
@@ -3389,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
@@ -3605,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;
           }
@@ -3655,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;
     }

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/package.json

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