@minnowdb/core 0.7.10 → 0.8.0

package/dist/engine/client.d.ts

@@ -1,3 +1,4 @@
+import { type LiveQueryPatchOptions } from "./live-patch.js";
 import { type CompactionJobRecord, type GarbageCollectionJobRecord, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult } from "../storage/types.js";
 import { type BatchRow } from "./batch.js";
 import type { Catalog } from "./catalog.js";
@@ -264,6 +265,8 @@ export declare class ClientLiveQuerySet {
     constructor(client: MinnowDatabaseClient, handleId: string, created: Promise<unknown>);
     /** Registers a query (SQL or a compiled-plan envelope) and re-runs it on relevant changes. */
     subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<ClientLiveSubscription>;
+    /** Delivers changed row payloads; the worker transport still sends its result snapshot. */
+    subscribePatches(query: LiveQueryInput, options: LiveQueryPatchOptions): Promise<ClientLiveSubscription>;
     /** Registers dependency observation while leaving execution/result mapping to an adapter. */
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<ClientLiveSubscription>;
     stats(): Promise<LiveQueryStats>;

package/dist/engine/client.js

@@ -1,3 +1,4 @@
+import { createLiveQueryPatch } from "./live-patch.js";
 import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, PostingBuildConflictError, SnapshotManifestMissingError, SnapshotImportConflictError, SchemaConflictError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, StorageCorruptionError, StorageFormatVersionError, OpfsUncertainOutcomeError } from "../storage/types.js";
 import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
 import { parseRpcResponse, MAX_DATABASE_RPC_IN_FLIGHT, protocolVersion } from "../worker-protocol/index.js";
@@ -683,6 +684,13 @@ class ClientLiveQuerySet {
       throw error;
     }
   }
+  subscribePatches(query, options) {
+    return this.subscribe(query, {
+      onChange: (result, delivery) => options.onPatch(createLiveQueryPatch(result, delivery), delivery),
+      ...options.onError === void 0 ? {} : { onError: options.onError.bind(options) },
+      ...options.onComplete === void 0 ? {} : { onComplete: options.onComplete.bind(options) }
+    });
+  }
   async observe(query, options) {
     await this.#created;
     const subscriptionId = crypto.randomUUID();

package/dist/engine/database.js

@@ -1,3 +1,6 @@
+import { LiveAggregate } from "./live-aggregate.js";
+import { QueryGenerations } from "./query-generations.js";
+import { applyWindowFunctionsAsync } from "./windows.js";
 import { crossJoinPlan } from "../plan/model.js";
 import { definedVectors, toColumnarBatch } from "./batch.js";
 import { ArtifactCache } from "./artifact-cache.js";
@@ -16,7 +19,7 @@ import { cachedQueryTerms, FTS_TOKENIZER_VERSION, renderDocumentValue, tokenize
 import { boundedMaintenanceBatchItems, simpleDataTypes, floorWholeNumberProduct, BlockReadBatchTooLargeError, validateColumnDefault, validateEnumValues, secondaryIndexColumnIds, secondaryIndexDirections, secondaryUniqueKeyNamespace, CompactionJobConflictError, CompactionBacklogError, GarbageCollectionJobConflictError, MAX_LEVEL_ZERO_SEGMENTS, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_INDEXED_STRING_CHARACTERS, MAX_CATALOG_NAME_CHARACTERS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MAINTENANCE_BATCH_ITEMS, MAX_STORAGE_BULK_READ_ITEMS, MAX_BLOCK_READ_BATCH_BYTES, MAX_TRANSACTION_STAGE_BLOCKS, MAX_TRANSACTION_STAGE_BYTES, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_POSTING_BUILD_TTL_MS, MAX_TEMP_OWNER_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, SNAPSHOT_FRAME_KINDS, validateStorageId, SnapshotManifestMissingError, SchemaConflictError, TableInUseError, TableRecordConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError } from "../storage/types.js";
 import { decodeSnapshotFrameStream, encodeSnapshotFrameStreamFooter, encodeSnapshotFrameStreamHeader, extendSnapshotFrameStreamChecksum, snapshotFrameEnvelopeParts, snapshotFrameStreamHeaderIdentity } from "../storage/snapshot.js";
 import { Snapshot, TransactionManager } from "../transactions/index.js";
-import { applyWindowFunctions, bindPendingSelectShapes, bindPlanParameters, bindStatementParameters, DUAL_TABLE, dualTableRows, blockHasSubqueries, combineUnionResults, compileCheckExpression, compileQuery, hasAggregate, createRecursiveCteState, annotateAvgArgumentScales, compileStatement, comparisonHolds, createPreparedColumnarQuery, evaluateJoinedRowExpression, evaluateRowExpression, externalizeQueryResult, expressionColumnNames, inferBlockSchema, inferResultColumnDomains, isDeferredInsertExpression, isDefaultInsertValue, referencedColumns, childExpressions, expandFtsColumns, expandNaturalJoins, expandSourceColumnAliases, expandViewSources, forEachBlockExpression, forEachNestedBlock, planContainsFts, planHasNaturalJoins, planHasSourceColumnAliases, planReadsTable, planReadsViews, planReadsBeyondSingleScan, projectResultColumns, queryResultNeedsExternalization, resolveStatementDatetimes, subqueryResolutionSteps, topLevelFtsMatchConjuncts, transparentProjectionSource, unknownColumnDomains, validateDefaultExpression, windowOutputDomain, windowOutputType, volatileScalarFunctionNames, annotatePlanIntegerDivision, clonePlanTree, planMayHaveIntegerDivision, foldIdentifierCase, extendGroupByWithKeyDependents, expandRowReferences } from "./query.js";
+import { bindPendingSelectShapes, bindPlanParameters, bindStatementParameters, DUAL_TABLE, dualTableRows, blockHasSubqueries, combineUnionResults, compileCheckExpression, compileQuery, hasAggregate, createRecursiveCteState, annotateAvgArgumentScales, compileStatement, comparisonHolds, createPreparedColumnarQuery, evaluateJoinedRowExpression, evaluateRowExpression, externalizeQueryResult, expressionColumnNames, inferBlockSchema, inferResultColumnDomains, isDeferredInsertExpression, isDefaultInsertValue, referencedColumns, childExpressions, mapChildExpressions, expandFtsColumns, expandNaturalJoins, expandSourceColumnAliases, expandViewSources, forEachBlockExpression, forEachNestedBlock, planContainsFts, planHasNaturalJoins, planHasSourceColumnAliases, planReadsTable, planReadsViews, planReadsBeyondSingleScan, projectResultColumns, queryResultNeedsExternalization, resolveStatementDatetimes, subqueryResolutionSteps, topLevelFtsMatchConjuncts, transparentProjectionSource, unknownColumnDomains, validateDefaultExpression, windowOutputDomain, windowOutputType, volatileScalarFunctionNames, annotatePlanIntegerDivision, clonePlanTree, planMayHaveIntegerDivision, foldIdentifierCase, extendGroupByWithKeyDependents, expandRowReferences } from "./query.js";
 import { copyQueryResult, planMemoKey, queryResultMemoKey, queryResultRetainedBytes, RESULT_MEMO_MAX_BYTES } from "./query-cache.js";
 import { QueryMemoryBudgetError, QueryMemoryContext, DEFAULT_QUERY_MEMORY_BUDGET_BYTES } from "./memory.js";
 import { LiveQueryLimitError, LiveQuerySet, MAX_LIVE_QUERY_SETS_PER_DATABASE } from "./live.js";
@@ -576,6 +579,7 @@ class MinnowDatabase {
   #liveSets = /* @__PURE__ */ new Set();
   #liveProofContexts = /* @__PURE__ */ new Map();
   #artifactCache;
+  #queryGenerations;
   #queryExecutionMemoryBudgetBytes;
   #ftsAutoIndexRows;
   #autoCompact;
@@ -657,6 +661,7 @@ class MinnowDatabase {
     if (!Number.isSafeInteger(this.#transactionOwnerLeaseMs) || this.#transactionOwnerLeaseMs <= 0) {
       throw new RangeError("Transaction owner lease lifetime must be a positive whole number");
     }
+    this.#queryGenerations = new QueryGenerations((after, limit) => this.store.listManifestPage(after, limit));
     this.#artifactCache = new ArtifactCache(options.bufferPoolBytes ?? 64 * 1024 * 1024);
     const queryBudget = options.executionMemoryBudgetBytes;
     this.#queryExecutionMemoryBudgetBytes = queryBudget === null ? Number.MAX_SAFE_INTEGER : positiveWholeNumber(queryBudget ?? DEFAULT_QUERY_MEMORY_BUDGET_BYTES, "Query execution memory budget");
@@ -2748,6 +2753,12 @@ class MinnowDatabase {
               const expected = schema2?.[index];
               if (expected === void 0)
                 return;
+              if (column.unknown === true)
+                return;
+              if (expected.unknown === true) {
+                schema2 = schema2?.map((entry, position) => position === index ? { ...column, name: entry.name } : entry);
+                return;
+              }
               if (column.type === expected.type && column.sqlDomain?.kind === "numeric" && expected.sqlDomain?.kind === "numeric") {
                 if (JSON.stringify(column.sqlDomain) !== JSON.stringify(expected.sqlDomain)) {
                   schema2 = schema2?.map((entry, position) => position === index ? { ...entry, sqlDomain: { kind: "numeric" } } : entry);
@@ -2769,7 +2780,7 @@ class MinnowDatabase {
       if (source.windowed !== void 0) {
         const innerKey = await this.#blockResultCacheKey(source.windowed.block, snapshot, visibility, realTables, cacheResults);
         throwIfAborted(signal);
-        const columnarKey2 = innerKey === void 0 ? void 0 : `ctw|${JSON.stringify(source.windowed.windows)}|${innerKey}`;
+        const columnarKey2 = innerKey === void 0 ? void 0 : `ctw|${planMemoKey(source.windowed.windows)}|${innerKey}`;
         if (columnarKey2 !== void 0) {
           const hit = this.#cacheGet(columnarKey2);
           if (hit !== void 0) {
@@ -2779,8 +2790,10 @@ class MinnowDatabase {
           }
         }
         const { result: inner, schema: innerSchema } = await this.#executeBlockWithSchemaCached(source.windowed.block, snapshot, visibility, memory, realTables, typedSchemas, cacheResults, allowSpill, forceSpill, spillPageRows, signal);
-        const windowed = applyWindowFunctions(inner, source.windowed.windows, {
-          copyRows: cacheResults
+        const windowed = await applyWindowFunctionsAsync(inner, source.windowed.windows, {
+          copyRows: cacheResults,
+          memoryContext: memory,
+          ...signal === void 0 ? {} : { signal }
         });
         const schema2 = [
           ...innerSchema,
@@ -2978,7 +2991,16 @@ class MinnowDatabase {
     throwIfAborted(options.signal);
     before ??= await probe();
     throwIfAborted(options.signal);
-    const cached = this.#cacheGet(`${key}
${String(before.catalogEpoch)}`);
+    const dependencyKey = `deps ${String(before.schemaEpoch)} ${key}`;
+    let dependencies = this.#cacheGet(dependencyKey);
+    if (dependencies === void 0) {
+      const rewritten = await this.#applyCatalogRewrites(plan, before);
+      dependencies = [...(await this.#findRealBlockTables(rewritten)).values()].map((table) => table.id).sort();
+      this.#cachePut(dependencyKey, dependencies, 64 + dependencies.reduce((bytes2, id) => bytes2 + id.length * 2 + 16, 0));
+    }
+    const generation = await this.#queryGenerations.key(dependencies, before.manifestVersion);
+    const resultKey = `${key}
${String(before.schemaEpoch)}
${generation}`;
+    const cached = this.#cacheGet(resultKey);
     if (cached !== void 0) {
       options.onStats?.({ peakMemoryBytes: 0 });
       return copyQueryResult(cached);
@@ -2992,7 +3014,7 @@ class MinnowDatabase {
       const after = await probe();
       throwIfAborted(options.signal);
       if (after.catalogEpoch === before.catalogEpoch) {
-        this.#cachePut(`${key}
${String(before.catalogEpoch)}`, copyQueryResult(result), bytes);
+        this.#cachePut(resultKey, copyQueryResult(result), bytes);
       }
     }
     return result;
@@ -3083,7 +3105,34 @@ class MinnowDatabase {
     if (plan.base.table !== DUAL_TABLE || plan.joins.length > 0) {
       throw new TypeError("NEXTVAL and CURRVAL currently require a SELECT without FROM");
     }
-    const resolved = structuredClone(plan);
+    const resolved = resolveStatementDatetimes(structuredClone(plan), this.#now());
+    const evaluate = (expression) => evaluateRowExpression(expression, DUAL_TABLE, {});
+    const literal = (value) => ({
+      kind: "literal",
+      value,
+      internalSqlValue: true
+    });
+    const omitted = resolved.limit === 0;
+    const matches = !omitted && resolved.predicates.every((predicate) => evaluate({ kind: "condition", ...predicate }) === true);
+    if (!omitted)
+      resolved.predicates = matches ? [] : [
+        {
+          left: literal(false),
+          operator: "=",
+          right: literal(true)
+        }
+      ];
+    const discarded = !matches;
+    if (discarded) {
+      const omit = (expression) => {
+        if (expression.kind === "call" && sequenceFunctionNames.has(expression.name))
+          return literal(0);
+        return mapChildExpressions(expression, omit);
+      };
+      for (const item of resolved.select)
+        item.expression = omit(item.expression);
+      return resolved;
+    }
     const rewrite = async (expression) => {
       if (expression.kind === "call" && (expression.name === "NEXTVAL" || expression.name === "CURRVAL")) {
         const argument = expression.arguments[0];
@@ -3107,6 +3156,21 @@ class MinnowDatabase {
         this.#sequenceCurrValues.set(name, value);
         return { kind: "literal", value };
       }
+      if (expression.kind === "case") {
+        for (const branch of expression.branches) {
+          if (evaluate(await rewrite(branch.when)) === true)
+            return rewrite(branch.then);
+        }
+        return expression.otherwise === void 0 ? literal(null) : rewrite(expression.otherwise);
+      }
+      if (expression.kind === "call" && expression.name === "COALESCE") {
+        for (const argument of expression.arguments) {
+          const value = evaluate(await rewrite(argument));
+          if (value !== null)
+            return literal(value);
+        }
+        return literal(null);
+      }
       if (expression.kind === "binary" || expression.kind === "condition" || expression.kind === "logical") {
         expression.left = await rewrite(expression.left);
         expression.right = await rewrite(expression.right);
@@ -3124,13 +3188,6 @@ class MinnowDatabase {
         }
       } else if (expression.kind === "not") {
         expression.operand = await rewrite(expression.operand);
-      } else if (expression.kind === "case") {
-        for (const branch of expression.branches) {
-          branch.when = await rewrite(branch.when);
-          branch.then = await rewrite(branch.then);
-        }
-        if (expression.otherwise !== void 0)
-          expression.otherwise = await rewrite(expression.otherwise);
       }
       return expression;
     };
@@ -3757,14 +3814,14 @@ class MinnowDatabase {
       if (typeof query === "string")
         return this.query(query);
       if (query.kind === "typed-query")
-        return this.#queryCompiled(query.plan);
+        return externalizeQueryResult(await this.#withReadReservation(() => this.#queryCompiled(query.plan)));
       return this.query(query.sql, { params: query.params });
     }
     const { probe, memoize } = context;
     if (typeof query !== "string" && query.kind === "typed-query") {
       const plan = query.plan;
       const memoizable = plan.usesStatementDatetime !== true && plan.usesVolatileFunctions !== true && plan.usesSequenceCalls !== true;
-      return this.#withReadReservation(() => memoizable ? this.#memoizedQuery(plan, `typed ${planMemoKey(plan)}`, {}, this.store.getCatalogProbe.bind(this.store), probe, memoize) : this.#queryCompiled(plan, {}, probe));
+      return externalizeQueryResult(await this.#withReadReservation(() => memoizable ? this.#memoizedQuery(plan, `typed ${planMemoKey(plan)}`, {}, this.store.getCatalogProbe.bind(this.store), probe, memoize) : this.#queryCompiled(plan, {}, probe)));
     }
     if (typeof query === "string")
       return this.#queryWithReadReservation(query, {}, probe, memoize);
@@ -3776,9 +3833,49 @@ class MinnowDatabase {
     }
     const plan = await this.#applyCatalogRewrites(compiled, probe);
     const base = plan.base;
-    if (plan.joins.length > 0 || base.derived !== void 0 || base.union !== void 0 || base.recursive !== void 0 || base.windowed !== void 0 || plan.pendingSelectShape !== void 0 || plan.distinctWildcard === true || plan.groupBy.length > 0 || plan.having.length > 0 || plan.limitParameter !== void 0 || plan.offsetParameter !== void 0 || planReadsBeyondSingleScan(plan) || planContainsFts(plan)) {
+    if (base.table === DUAL_TABLE || base.derived !== void 0 || base.union !== void 0 || base.recursive !== void 0 || base.windowed !== void 0 || plan.pendingSelectShape !== void 0 || plan.distinctWildcard === true || plan.limitParameter !== void 0 || plan.offsetParameter !== void 0 || planReadsBeyondSingleScan(plan) || planContainsFts(plan)) {
       return void 0;
     }
+    if (plan.joins.length > 0) {
+      const join = plan.joins[0];
+      if (plan.joins.length !== 1 || join === void 0 || !["inner", "left"].includes(join.kind) || join.on !== void 0 || join.derived !== void 0 || join.union !== void 0 || join.windowed !== void 0 || join.recursive !== void 0)
+        return void 0;
+      const lookup = await this.#findTable(join.table);
+      const lookupKey = getUniqueKeyColumn(lookup);
+      if (lookupKey === void 0 || lookupKey.sqlDomain !== void 0)
+        return void 0;
+      const lookupReference = `${join.alias}.${lookupKey.name}`;
+      const joinedKey = [join.left, join.right].find((expression) => expression.kind === "column" && expression.reference === lookupReference);
+      if (joinedKey === void 0)
+        return void 0;
+    }
+    const table = await this.#findTable(base.table);
+    const keyColumn = getUniqueKeyColumn(table);
+    if (keyColumn === void 0 || keyColumn.hidden === true || keyColumn.sqlDomain !== void 0)
+      return void 0;
+    const aggregate = LiveAggregate.plan(plan, `${base.alias}.${keyColumn.name}`);
+    if (aggregate !== void 0)
+      return {
+        tableId: table.id,
+        keyColumnId: keyColumn.id,
+        qualifiedKey: `${base.alias}.${keyColumn.name}`,
+        fullPlan: aggregate.inputPlan,
+        deltaPlan: aggregate.inputPlan,
+        publicColumns: plan.select.map((item) => item.alias),
+        columnDomains: [],
+        orderTerms: [],
+        limit: void 0,
+        offset: 0,
+        margin: 0,
+        complete: true,
+        rows: [],
+        keys: [],
+        positions: /* @__PURE__ */ new Map(),
+        order: [],
+        aggregate
+      };
+    if (plan.groupBy.length > 0 || plan.having.length > 0)
+      return void 0;
     const rowLocal = (expression) => {
       if (expression.kind === "subquery" || expression.kind === "exists" || expression.kind === "window" || expression.kind === "wildcard" || expression.kind === "parameter" || hasAggregate(expression)) {
         return false;
@@ -3792,11 +3889,6 @@ class MinnowDatabase {
     }
     if (!plan.orderBy.every((term) => rowLocal(term.expression)))
       return void 0;
-    const table = await this.#findTable(base.table);
-    const keyColumn = getUniqueKeyColumn(table);
-    if (keyColumn === void 0 || keyColumn.hidden === true || keyColumn.sqlDomain !== void 0) {
-      return void 0;
-    }
     const publicColumns = plan.select.map((item) => item.alias);
     if (publicColumns.some((name) => name.startsWith(LIVE_HIDDEN_PREFIX)))
       return void 0;
@@ -3848,6 +3940,7 @@ class MinnowDatabase {
       complete: true,
       rows: [],
       keys: [],
+      positions: /* @__PURE__ */ new Map(),
       order: []
     };
   }
@@ -3856,6 +3949,19 @@ class MinnowDatabase {
     const state = await this.#liveMaintenancePlan(compiled, probe);
     if (state === void 0)
       return void 0;
+    if (state.aggregate !== void 0) {
+      try {
+        const input = await this.#withReadReservation(() => this.#queryCompiled(state.fullPlan, {}, probe));
+        const aggregate = state.aggregate.patch(input, /* @__PURE__ */ new Set(), liveKeyToken);
+        return {
+          result: aggregate.result(),
+          state: { ...state, aggregate },
+          retainedBytes: aggregate.retainedBytes
+        };
+      } catch {
+        return void 0;
+      }
+    }
     let executed;
     try {
       executed = externalizeQueryResult(await this.#withReadReservation(() => this.#queryCompiled(state.fullPlan, {}, probe)));
@@ -3889,12 +3995,40 @@ class MinnowDatabase {
     const { changedKeys, existingKeys } = changed;
     if (changedKeys.size === 0)
       return { result: retained, state, changed: false };
+    if (state.aggregate !== void 0) {
+      const deltaPlan2 = {
+        ...state.deltaPlan,
+        predicates: [
+          ...state.deltaPlan.predicates,
+          {
+            left: { kind: "column", reference: state.qualifiedKey },
+            operator: "IN",
+            right: {
+              kind: "list",
+              items: [...changedKeys.values()].map((value) => ({ kind: "literal", value }))
+            }
+          }
+        ]
+      };
+      const input = await this.#withReadReservation(() => this.#queryCompiled(deltaPlan2, {}, probe));
+      const aggregate = state.aggregate.patch(input, new Set(changedKeys.keys()), liveKeyToken);
+      const result = aggregate.result();
+      const changed2 = result.rows.length !== retained.rows.length || result.rows.some((row, index) => {
+        const previous = retained.rows[index];
+        return previous === void 0 || !sameLiveRow(previous, row, result.columns);
+      });
+      return {
+        result,
+        state: { ...state, aggregate },
+        retainedBytes: aggregate.retainedBytes,
+        changed: changed2
+      };
+    }
     const affected = /* @__PURE__ */ new Set();
-    const retainedTokens = /* @__PURE__ */ new Set();
-    for (const [index, key] of state.keys.entries()) {
-      const token = liveKeyToken(key);
-      retainedTokens.add(token);
-      if (changedKeys.has(token))
+    const retainedTokens = state.positions;
+    for (const token of changedKeys.keys()) {
+      const index = retainedTokens.get(token);
+      if (index !== void 0)
         affected.add(index);
     }
     const fullLimit = state.limit === void 0 ? void 0 : state.limit + state.margin;
@@ -5423,11 +5557,15 @@ class MinnowDatabase {
       set.notifyLocalCommit();
   }
   async run(query) {
-    const probe = this.store.getCatalogProbe.bind(this.store);
-    if (query.plan.usesStatementDatetime === true || query.plan.usesVolatileFunctions === true) {
-      return (await this.#queryCompiled(query.plan)).rows;
-    }
-    return (await this.#memoizedQuery(query.plan, `typed ${planMemoKey(query.plan)}`, {}, probe)).rows;
+    await this.#settleExpiredStatementTransaction();
+    const open = this.#openTransaction;
+    const plan = query.plan;
+    const execute = async () => {
+      const probe = this.store.getCatalogProbe.bind(this.store);
+      return plan.usesStatementDatetime === true || plan.usesVolatileFunctions === true || plan.usesSequenceCalls === true ? this.#queryCompiled(plan) : this.#memoizedQuery(plan, `typed ${planMemoKey(plan)}`, {}, probe);
+    };
+    const result = open === void 0 ? await this.#withReadReservation(execute) : await this.#duringTransaction(open, () => open.session.queryPlan(plan));
+    return externalizeQueryResult(result).rows;
   }
   async migrate(definition = this.#schema, options = {}) {
     if (definition === void 0) {
@@ -8210,10 +8348,12 @@ ${notes.map((note) => `-- ${note}`).join("\n")}`;
       const table = realTables.get(name);
       if (table === void 0)
         return void 0;
-      parts.push(`${table.id}=${String(snapshot.version ?? -1)}`);
+      parts.push(`${table.id}:${String(table.revision)}`);
     }
     try {
-      return `blk\0${parts.join(";")}\0${JSON.stringify(block)}`;
+      const ids = collectRealTableNames(block).sort().map((name) => realTables.get(name)?.id ?? name);
+      const generation = await this.#queryGenerations.key(ids, snapshot.version);
+      return `blk\0${parts.join(";")}\0${generation}\0${planMemoKey(block)}`;
     } catch {
       return void 0;
     }
@@ -14489,6 +14629,18 @@ function splitLiveHiddenColumns(executed, state) {
   };
 }
 function liveMaintainedOutcome(state, previous, previousIndex) {
+  const positions = /* @__PURE__ */ new Map();
+  let retainedBytes = 128 + planMemoKey(state.fullPlan).length * 2 + planMemoKey(state.deltaPlan).length * 2;
+  for (const [index, key] of state.keys.entries()) {
+    const token = liveKeyToken(key);
+    positions.set(token, index);
+    retainedBytes += 64 + token.length * 2;
+  }
+  for (const row of state.rows)
+    retainedBytes += 48 + estimateValuesBytes(Object.values(row)) * 2;
+  for (const values of state.order)
+    retainedBytes += values.length * 8 + estimateValuesBytes(values) * 2;
+  state = { ...state, positions };
   const visibleCount = state.limit === void 0 ? state.rows.length : Math.min(state.rows.length, state.limit);
   const visible = state.rows.slice(0, visibleCount);
   if (previous === void 0) {
@@ -14499,6 +14651,7 @@ function liveMaintainedOutcome(state, previous, previousIndex) {
         rows: visible
       },
       state,
+      retainedBytes,
       changed: true
     };
   }
@@ -14526,7 +14679,7 @@ function liveMaintainedOutcome(state, previous, previousIndex) {
       same = false;
   }
   if (same)
-    return { result: previous, state, changed: false };
+    return { result: previous, state, retainedBytes, changed: false };
   return {
     result: {
       columns: [...state.publicColumns],
@@ -14534,6 +14687,7 @@ function liveMaintainedOutcome(state, previous, previousIndex) {
       rows: visible
     },
     state,
+    retainedBytes,
     changed: true,
     ...kept > 0 ? { retained } : {}
   };

package/dist/engine/errors.d.ts

@@ -17,10 +17,10 @@ export declare class DatabaseReadBacklogError extends Error {
 }
 /** A live-query owner reached one of its documented resident-resource ceilings. */
 export declare class LiveQueryLimitError extends Error {
-    readonly resource: "set" | "group" | "subscription";
+    readonly resource: "set" | "group" | "subscription" | "byte";
     readonly limit: number;
     readonly name = "LiveQueryLimitError";
-    constructor(resource: "set" | "group" | "subscription", limit: number);
+    constructor(resource: "set" | "group" | "subscription" | "byte", limit: number);
 }
 export declare class UniqueConstraintError extends Error {
     readonly tableName: string;

package/dist/engine/errors.js

@@ -22,7 +22,7 @@ class LiveQueryLimitError extends Error {
   limit;
   name = "LiveQueryLimitError";
   constructor(resource, limit) {
-    super(resource === "set" ? `A database cannot retain more than ${String(limit)} live-query sets` : `A live-query set cannot retain more than ${String(limit)} ${resource} records`);
+    super(resource === "set" ? `A database cannot retain more than ${String(limit)} live-query sets` : resource === "byte" ? `A live-query set cannot retain more than ${String(limit)} modeled bytes` : `A live-query set cannot retain more than ${String(limit)} ${resource} records`);
     this.resource = resource;
     this.limit = limit;
   }

package/dist/engine/live-aggregate.d.ts

@@ -0,0 +1,12 @@
+import type { CompiledQuery, QueryResult, QueryValue } from "../plan/model.js";
+/** Single-table COUNT/SUM/AVG contributions; SQL still evaluates filters and arguments. */
+export declare class LiveAggregate {
+    #private;
+    readonly inputPlan: CompiledQuery;
+    readonly keyAlias: string;
+    private constructor();
+    static plan(plan: CompiledQuery, qualifiedKey: string): LiveAggregate | undefined;
+    patch(result: QueryResult, changed: ReadonlySet<string>, token: (value: QueryValue) => string): LiveAggregate;
+    result(): QueryResult;
+    get retainedBytes(): number;
+}