@minnowdb/core 0.7.8 → 0.8.0

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,12 +19,12 @@ 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";
 import { chooseJoinOrder, optimizePlan, qualifyCorrelatedReferences, renderPlan } from "./optimizer.js";
-import { encodeSqlEqualityValue, readUntypedText } from "./sql-semantics.js";
+import { encodeSqlEqualityValue, readUntypedText, compareSqlValues } from "./sql-semantics.js";
 import { exactNumericAsNumber, exactNumericValue, externalSqlDomainValue, externalSqlTextValue, isDateDomainValue, isExactNumeric, isSqlDomainValue, normalizeSqlDomainValue, protectedSqlTextValue } from "./sql-domains.js";
 import { toCatalog } from "./catalog.js";
 import { applyColumnSteps, assertColumnDroppable, compileGeneratedColumnExpression, declaredForeignKeys, isDestructiveStep, planMigration } from "./schema.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");
@@ -1124,11 +1129,11 @@ class MinnowDatabase {
       this.#activeReadReservations -= 1;
     }
   }
-  async #queryWithReadReservation(sql, options) {
+  async #queryWithReadReservation(sql, options, probe, storeMemo = true) {
     throwIfAborted(options.signal);
     await this.#settleExpiredStatementTransaction();
     throwIfAborted(options.signal);
-    return this.#openTransaction === void 0 ? this.#withReadReservation(() => this.#queryUnreserved(sql, options)) : this.#queryUnreserved(sql, options);
+    return this.#openTransaction === void 0 ? this.#withReadReservation(() => this.#queryUnreserved(sql, options, probe, storeMemo)) : this.#queryUnreserved(sql, options, probe, storeMemo);
   }
   async #assistAutomaticCollection() {
     if (!this.#autoCollect && !this.#manualCollectionDebtInitialized) {
@@ -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,
@@ -2857,7 +2870,7 @@ class MinnowDatabase {
   async query(sql, options = {}) {
     return this.#queryWithReadReservation(sql, options);
   }
-  async #queryUnreserved(sql, options) {
+  async #queryUnreserved(sql, options, probe, storeMemo = true) {
     throwIfAborted(options.signal);
     const open = this.#openTransaction;
     if (open !== void 0) {
@@ -2883,9 +2896,9 @@ class MinnowDatabase {
       }
     }
     const plan = bindPlanParameters(compiled, options.params);
-    const probe = this.store.getCatalogProbe.bind(this.store);
+    const readProbe = this.store.getCatalogProbe.bind(this.store);
     const memoizable = options.memoize !== false && cacheableQueryInput(sql, options.params ?? []) && plan.usesStatementDatetime !== true && plan.usesVolatileFunctions !== true && plan.usesSequenceCalls !== true && options.version === void 0 && options.executionMemoryBudgetBytes === void 0 && options.spillToStorage === void 0 && options.spillPageRows === void 0;
-    const result = !memoizable ? await this.#queryCompiled(plan, options) : await this.#memoizedQuery(plan, `res ${queryResultMemoKey(sql, options.params ?? [])}`, options, probe);
+    const result = !memoizable ? await this.#queryCompiled(plan, options, probe) : await this.#memoizedQuery(plan, `res ${queryResultMemoKey(sql, options.params ?? [])}`, options, readProbe, probe, storeMemo);
     throwIfAborted(options.signal);
     return externalizeQueryResult(result);
   }
@@ -2974,23 +2987,34 @@ class MinnowDatabase {
       });
     }
   }
-  async #memoizedQuery(plan, key, options, probe) {
+  async #memoizedQuery(plan, key, options, probe, before, store = true) {
     throwIfAborted(options.signal);
-    const before = await probe();
+    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);
     }
     const result = await this.#queryCompiled(plan, options, before);
     throwIfAborted(options.signal);
+    if (!store)
+      return result;
     const bytes = queryResultRetainedBytes(result);
     if (bytes <= RESULT_MEMO_MAX_BYTES) {
       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;
@@ -3081,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];
@@ -3105,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);
@@ -3122,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;
     };
@@ -3729,19 +3788,15 @@ class MinnowDatabase {
         return this.store.getCatalogProbe();
       },
       manifestPage: (afterVersion, limit) => this.store.listManifestPage(afterVersion, limit),
-      dependencyTableIds: async (query) => {
+      dependencyTableIds: async (query, probe) => {
         const compiled = compileLiveQuery(query);
-        const plan = await this.#applyCatalogRewrites(compiled);
+        const plan = await this.#applyCatalogRewrites(compiled, probe);
         const tables = await this.#findRealBlockTables(plan);
         return new Set([...tables.values()].map((record) => record.id));
       },
-      execute: async (query) => {
-        if (typeof query === "string")
-          return this.query(query);
-        if (query.kind === "typed-query")
-          return this.#queryCompiled(query.plan);
-        return this.query(query.sql, { params: query.params });
-      },
+      execute: (query, context) => this.#liveExecute(query, context),
+      executeMaintainable: (query, context) => this.#liveExecuteMaintainable(compileLiveQuery(query), context),
+      maintain: (_query, result, state, tableIds, after, until, probe) => this.#liveMaintain(result, state, tableIds, after, until, probe),
       changeCanAffect: (query, tableIds, after, until) => this.#liveChangeCanAffect(query, tableIds, after, until)
     }, {
       ...options,
@@ -3754,6 +3809,282 @@ class MinnowDatabase {
     this.#liveSets.add(set);
     return set;
   }
+  async #liveExecute(query, context) {
+    if (context === void 0) {
+      if (typeof query === "string")
+        return this.query(query);
+      if (query.kind === "typed-query")
+        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 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);
+    return this.#queryWithReadReservation(query.sql, { params: query.params }, probe, memoize);
+  }
+  async #liveMaintenancePlan(compiled, probe) {
+    if (compiled.usesStatementDatetime === true || compiled.usesVolatileFunctions === true || compiled.usesSequenceCalls === true) {
+      return void 0;
+    }
+    const plan = await this.#applyCatalogRewrites(compiled, probe);
+    const base = plan.base;
+    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;
+      }
+      return childExpressions(expression).every(rowLocal);
+    };
+    if (!plan.select.every((item) => rowLocal(item.expression)))
+      return void 0;
+    if (!plan.predicates.every(({ left, right }) => rowLocal(left) && rowLocal(right))) {
+      return void 0;
+    }
+    if (!plan.orderBy.every((term) => rowLocal(term.expression)))
+      return void 0;
+    const publicColumns = plan.select.map((item) => item.alias);
+    if (publicColumns.some((name) => name.startsWith(LIVE_HIDDEN_PREFIX)))
+      return void 0;
+    const fullPlan = clonePlanTree(plan);
+    const qualifiedKey = `${base.alias}.${keyColumn.name}`;
+    fullPlan.select.push({
+      expression: { kind: "column", reference: qualifiedKey },
+      alias: LIVE_KEY_ALIAS
+    });
+    const orderTerms = [];
+    for (const [index, term] of plan.orderBy.entries()) {
+      let alias;
+      if (term.expression.kind === "column" && !term.expression.reference.includes(".")) {
+        const output = term.expression.reference;
+        if (publicColumns.includes(output))
+          alias = output;
+      } else if (term.expression.kind === "literal" && typeof term.expression.value === "number") {
+        const position = term.expression.value;
+        if (!Number.isInteger(position) || position < 1 || position > publicColumns.length) {
+          return void 0;
+        }
+        alias = publicColumns[position - 1];
+      }
+      if (alias === void 0) {
+        alias = `${LIVE_ORDER_ALIAS}${String(index)}`;
+        fullPlan.select.push({ expression: clonePlanTree(term.expression), alias });
+      }
+      orderTerms.push({ alias, descending: term.direction === "desc", nulls: term.nulls });
+    }
+    const deltaPlan = clonePlanTree(fullPlan);
+    deltaPlan.orderBy = [];
+    delete deltaPlan.limit;
+    delete deltaPlan.offset;
+    const margin = plan.limit === void 0 || orderTerms.length === 0 ? 0 : Math.max(LIVE_WINDOW_MARGIN_MIN, Math.min(plan.limit, LIVE_WINDOW_MARGIN_MAX));
+    if (margin > 0)
+      fullPlan.limit = (plan.limit ?? 0) + margin;
+    return {
+      tableId: table.id,
+      keyColumnId: keyColumn.id,
+      qualifiedKey,
+      fullPlan,
+      deltaPlan,
+      publicColumns,
+      columnDomains: [],
+      orderTerms,
+      limit: plan.limit,
+      offset: plan.offset ?? 0,
+      margin,
+      complete: true,
+      rows: [],
+      keys: [],
+      positions: /* @__PURE__ */ new Map(),
+      order: []
+    };
+  }
+  async #liveExecuteMaintainable(compiled, context) {
+    const probe = context?.probe ?? await this.store.getCatalogProbe();
+    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)));
+    } catch {
+      return void 0;
+    }
+    const split = splitLiveHiddenColumns(executed, state);
+    return liveMaintainedOutcome({
+      ...state,
+      columnDomains: split.result.columnDomains,
+      complete: state.fullPlan.limit === void 0 || split.result.rows.length < state.fullPlan.limit,
+      rows: split.result.rows,
+      keys: split.keys,
+      order: split.order
+    }, void 0);
+  }
+  async #liveMaintain(retained, state, tableIds, after, until, probe) {
+    if (tableIds.length !== 1 || tableIds[0] !== state.tableId)
+      return void 0;
+    const context = await this.#liveProofContext(after, until);
+    const entry = await this.#liveProofTable(context, state.tableId);
+    if (entry === void 0)
+      return void 0;
+    for (const version of context.changedVersions.get(state.tableId) ?? []) {
+      if (!entry.coveredVersions.has(version))
+        return void 0;
+    }
+    const changed = await this.#liveChangedKeys(entry, state.keyColumnId);
+    if (changed === void 0)
+      return void 0;
+    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 = 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;
+    const truncated = !state.complete;
+    if (truncated && affected.size > 0 && state.orderTerms.length === 0)
+      return void 0;
+    if (state.offset > 0) {
+      for (const token of existingKeys)
+        if (!retainedTokens.has(token))
+          return void 0;
+    }
+    const deltaPlan = {
+      ...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 delta = splitLiveHiddenColumns(externalizeQueryResult(await this.#withReadReservation(() => this.#queryCompiled(deltaPlan, {}, probe))), state);
+    const compare = liveOrderComparator(state.orderTerms);
+    const added = {
+      rows: delta.result.rows,
+      keys: delta.keys,
+      order: delta.order,
+      previousIndex: new Int32Array(delta.result.rows.length).fill(-1)
+    };
+    let merged;
+    try {
+      const kept = filterLiveRows(state, (index) => !affected.has(index));
+      if (state.offset > 0 && added.rows.length > 0) {
+        if (kept.rows.length === 0 || added.rows.some((_, index) => compare(added.order, index, kept.order, 0) < 0)) {
+          return void 0;
+        }
+      }
+      merged = mergeLiveRows(kept, added, compare, state.orderTerms.length > 0);
+    } catch {
+      return void 0;
+    }
+    if (fullLimit !== void 0 && merged.rows.length > fullLimit)
+      merged = trimLiveRows(merged, fullLimit);
+    if (truncated && affected.size > 0 && state.limit !== void 0) {
+      const oldEdge = state.rows.length - 1;
+      const visibleEdge = Math.min(merged.rows.length, state.limit) - 1;
+      if (merged.rows.length < state.limit || oldEdge < 0 || visibleEdge < 0 || compare(merged.order, visibleEdge, state.order, oldEdge) > 0) {
+        return void 0;
+      }
+    }
+    return liveMaintainedOutcome({ ...state, rows: merged.rows, keys: merged.keys, order: merged.order }, retained, merged.previousIndex);
+  }
   async #liveChangeCanAffect(query, tableIds, after, until) {
     const plan = typeof query === "string" ? this.#compileCached(query) : query.kind === "typed-query" ? query.plan : bindPlanParameters(this.#compileCached(query.sql), query.params);
     if (planContainsFts(plan))
@@ -3855,6 +4186,51 @@ class MinnowDatabase {
     }
     return context;
   }
+  #liveChangedKeys(entry, keyColumnId) {
+    const cached = entry.changedKeys.get(keyColumnId);
+    if (cached !== void 0)
+      return cached;
+    const pending = (async () => {
+      const blockIds = [];
+      const existingBlockIds = /* @__PURE__ */ new Set();
+      let deltaRows = 0;
+      for (const segment of entry.windowSegments) {
+        if (segment.kind === "base")
+          continue;
+        const ids = segment.columnBlockIds[keyColumnId];
+        if (ids === void 0)
+          return void 0;
+        deltaRows += segment.rowCount;
+        if (deltaRows > LIVE_MAINTENANCE_MAX_DELTA_ROWS)
+          return void 0;
+        blockIds.push(...ids);
+        if (segment.kind !== "insert")
+          for (const id of ids)
+            existingBlockIds.add(id);
+      }
+      const changedKeys = /* @__PURE__ */ new Map();
+      const existingKeys = /* @__PURE__ */ new Set();
+      if (blockIds.length > 0) {
+        const decoded = await this.#loadDecodedBlocks([...new Set(blockIds)]);
+        for (const blockId of blockIds) {
+          const column = decoded.get(blockId);
+          if (column === void 0)
+            return void 0;
+          for (const value of column.values) {
+            if (value === null)
+              continue;
+            const token = liveKeyToken(value);
+            changedKeys.set(token, value);
+            if (existingBlockIds.has(blockId))
+              existingKeys.add(token);
+          }
+        }
+      }
+      return { changedKeys, existingKeys };
+    })();
+    entry.changedKeys.set(keyColumnId, pending);
+    return pending;
+  }
   #liveProofTable(context, tableId) {
     const cached = context.tables.get(tableId);
     if (cached !== void 0)
@@ -3875,7 +4251,7 @@ class MinnowDatabase {
         coveredVersions.add(committed);
         windowSegments.push(segment);
       }
-      return { table, windowSegments, coveredVersions };
+      return { table, windowSegments, coveredVersions, changedKeys: /* @__PURE__ */ new Map() };
     })();
     context.tables.set(tableId, entry);
     return entry;
@@ -5181,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) {
@@ -7968,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;
     }
@@ -14189,6 +14571,217 @@ function searchableFtsColumns(table) {
     return void 0;
   return visibleTableColumns(table).filter((column) => column.type !== "boolean").map((column) => column.name);
 }
+const LIVE_HIDDEN_PREFIX = "__minnow_live_";
+const LIVE_KEY_ALIAS = `${LIVE_HIDDEN_PREFIX}key`;
+const LIVE_ORDER_ALIAS = `${LIVE_HIDDEN_PREFIX}order_`;
+const LIVE_MAINTENANCE_MAX_DELTA_ROWS = 2048;
+const LIVE_WINDOW_MARGIN_MIN = 16;
+const LIVE_WINDOW_MARGIN_MAX = 64;
+function sameLiveRow(left, right, columns) {
+  for (const column of columns) {
+    const a = left[column] ?? null;
+    const b = right[column] ?? null;
+    if (a instanceof Date || b instanceof Date) {
+      if (!(a instanceof Date && b instanceof Date) || !Object.is(dateMilliseconds(a), dateMilliseconds(b))) {
+        return false;
+      }
+    } else if (!Object.is(a, b))
+      return false;
+  }
+  return true;
+}
+function liveKeyToken(value) {
+  if (typeof value === "number")
+    return `n:${String(value)}`;
+  if (typeof value === "string")
+    return `s:${value}`;
+  if (typeof value === "boolean")
+    return value ? "b:1" : "b:0";
+  if (value instanceof Date)
+    return `d:${String(dateMilliseconds(value))}`;
+  return "z";
+}
+function splitLiveHiddenColumns(executed, state) {
+  const publicCount = state.publicColumns.length;
+  const hidden = executed.columns.slice(publicCount);
+  const count = executed.rows.length;
+  const keys = new Array(count);
+  const order = state.orderTerms.map(() => new Array(count));
+  for (let index = 0; index < count; index += 1) {
+    const row = executed.rows[index] ?? {};
+    keys[index] = row[LIVE_KEY_ALIAS] ?? null;
+    for (const [term, { alias }] of state.orderTerms.entries()) {
+      const values = order[term];
+      if (values !== void 0)
+        values[index] = row[alias] ?? null;
+    }
+    for (const column of hidden)
+      Reflect.deleteProperty(row, column);
+  }
+  return {
+    result: {
+      columns: executed.columns.slice(0, publicCount),
+      columnDomains: executed.columnDomains.slice(0, publicCount),
+      rows: executed.rows
+    },
+    keys,
+    order
+  };
+}
+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) {
+    return {
+      result: {
+        columns: [...state.publicColumns],
+        columnDomains: [...state.columnDomains],
+        rows: visible
+      },
+      state,
+      retainedBytes,
+      changed: true
+    };
+  }
+  const previousCount = previous.rows.length;
+  const retained = new Int32Array(visibleCount);
+  let same = visibleCount === previousCount;
+  let kept = 0;
+  for (let index = 0; index < visibleCount; index += 1) {
+    const was = previousIndex?.[index] ?? -1;
+    if (was >= 0 && was < previousCount) {
+      retained[index] = was;
+      kept += 1;
+      if (was !== index)
+        same = false;
+      continue;
+    }
+    retained[index] = -1;
+    const before = previous.rows[index];
+    const now = visible[index];
+    if (before !== void 0 && now !== void 0 && sameLiveRow(before, now, previous.columns)) {
+      visible[index] = before;
+      retained[index] = index;
+      kept += 1;
+    } else
+      same = false;
+  }
+  if (same)
+    return { result: previous, state, retainedBytes, changed: false };
+  return {
+    result: {
+      columns: [...state.publicColumns],
+      columnDomains: [...state.columnDomains],
+      rows: visible
+    },
+    state,
+    retainedBytes,
+    changed: true,
+    ...kept > 0 ? { retained } : {}
+  };
+}
+function filterLiveRows(state, keep) {
+  const rows = [];
+  const keys = [];
+  const order = state.order.map(() => new Array());
+  const previous = [];
+  for (let index = 0; index < state.rows.length; index += 1) {
+    const row = state.rows[index];
+    if (row === void 0 || !keep(index))
+      continue;
+    rows.push(row);
+    keys.push(state.keys[index] ?? null);
+    for (const [term, values] of state.order.entries()) {
+      order[term]?.push(values[index] ?? null);
+    }
+    previous.push(index);
+  }
+  return { rows, keys, order, previousIndex: Int32Array.from(previous) };
+}
+function trimLiveRows(rows, count) {
+  return {
+    rows: rows.rows.slice(0, count),
+    keys: rows.keys.slice(0, count),
+    order: rows.order.map((values) => values.slice(0, count)),
+    previousIndex: rows.previousIndex.slice(0, count)
+  };
+}
+function liveOrderComparator(terms) {
+  return (leftOrder, leftIndex, rightOrder, rightIndex) => {
+    for (const [term, { descending, nulls }] of terms.entries()) {
+      const a = leftOrder[term]?.[leftIndex] ?? null;
+      const b = rightOrder[term]?.[rightIndex] ?? null;
+      if (a === null || b === null) {
+        if (a === null && b === null)
+          continue;
+        const nullsFirst = nulls === "first" || nulls === void 0 && descending;
+        return a === null ? nullsFirst ? -1 : 1 : nullsFirst ? 1 : -1;
+      }
+      let comparison = compareSqlValues(a, b);
+      if (descending)
+        comparison = -comparison;
+      if (comparison !== 0)
+        return comparison;
+    }
+    return 0;
+  };
+}
+function mergeLiveRows(kept, added, compare, ordered) {
+  if (added.rows.length === 0)
+    return kept;
+  const terms = kept.order.length;
+  const total = kept.rows.length + added.rows.length;
+  const rows = new Array(total);
+  const keys = new Array(total);
+  const order = Array.from({ length: terms }, () => new Array(total));
+  const previousIndex = new Int32Array(total);
+  const take = (source, from, to) => {
+    rows[to] = source.rows[from] ?? {};
+    keys[to] = source.keys[from] ?? null;
+    for (let term = 0; term < terms; term += 1) {
+      const values = order[term];
+      if (values !== void 0)
+        values[to] = source.order[term]?.[from] ?? null;
+    }
+    previousIndex[to] = source.previousIndex[from] ?? -1;
+  };
+  if (!ordered) {
+    for (let index = 0; index < kept.rows.length; index += 1)
+      take(kept, index, index);
+    for (let index = 0; index < added.rows.length; index += 1) {
+      take(added, index, kept.rows.length + index);
+    }
+    return { rows, keys, order, previousIndex };
+  }
+  const addedIndexes = added.rows.map((_, index) => index);
+  addedIndexes.sort((left, right) => compare(added.order, left, added.order, right));
+  let keptIndex = 0;
+  let addedPosition = 0;
+  for (let to = 0; to < total; to += 1) {
+    const addedIndex = addedIndexes[addedPosition];
+    const takeAdded = addedIndex !== void 0 && (keptIndex >= kept.rows.length || compare(added.order, addedIndex, kept.order, keptIndex) < 0);
+    if (takeAdded) {
+      take(added, addedIndex, to);
+      addedPosition += 1;
+    } else {
+      take(kept, keptIndex, to);
+      keptIndex += 1;
+    }
+  }
+  return { rows, keys, order, previousIndex };
+}
 function getUniqueKeyColumn(table) {
   if (table.uniqueKeyColumnId === void 0)
     return void 0;