@minnowdb/core 0.7.8 → 0.8.0

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/keyed-live.js

@@ -1,23 +1,29 @@
 import { dateMilliseconds } from "../date-value.js";
 import { sameLiveValue } from "./live-equal.js";
+const dateTokens = /* @__PURE__ */ new Map();
 function keyToken(value, name) {
-  if (typeof value === "string")
-    return `s:${String(value.length)}:${value}`;
-  if (typeof value === "boolean")
-    return value ? "b:1" : "b:0";
+  if (typeof value === "string" || typeof value === "boolean")
+    return value;
   if (typeof value === "number") {
     if (Number.isNaN(value))
-      return "n:NaN";
+      return NaN;
     if (Object.is(value, -0))
-      return "n:-0";
-    return `n:${String(value)}`;
+      return /* @__PURE__ */ Symbol.for("minnow.live.key.-0");
+    return value;
   }
   if (value instanceof Date) {
     const time = dateMilliseconds(value);
     if (!Number.isFinite(time)) {
       throw new TypeError(`Live query key ${String(name)} must be a valid Date`);
     }
-    return `d:${String(time)}`;
+    let token = dateTokens.get(time);
+    if (token === void 0) {
+      token = /* @__PURE__ */ Symbol(`minnow.live.key.date:${String(time)}`);
+      dateTokens.set(time, token);
+      if (dateTokens.size > 65536)
+        dateTokens.clear();
+    }
+    return token;
   }
   throw new TypeError(`Live query key ${String(name)} must be a non-null string, number, boolean, or Date`);
 }
@@ -35,8 +41,7 @@ function indexRows(rows, key) {
   }
   return indexed;
 }
-function diffRows(previousRows, rows, key) {
-  const previous = indexRows(previousRows, key);
+function diffRows(previous, previousRows, rows, key) {
   const current = indexRows(rows, key);
   const changes = [];
   for (const [token, old] of previous) {
@@ -44,26 +49,44 @@ function diffRows(previousRows, rows, key) {
       continue;
     changes.push({ type: "delete", key: old.row[key], previous: old.row, index: old.index });
   }
+  let reused = 0;
+  const reconciled = new Array(rows.length);
   for (const [token, next] of current) {
     const old = previous.get(token);
     if (old === void 0) {
+      reconciled[next.index] = next.row;
       changes.push({ type: "insert", row: next.row, index: next.index });
       continue;
     }
-    if (!sameLiveValue(old.row, next.row)) {
+    let kept = next.row;
+    if (old.row === next.row || sameLiveValue(old.row, next.row)) {
+      kept = old.row;
+      if (old.row !== next.row) {
+        current.set(token, { row: old.row, index: next.index });
+        reused += 1;
+      }
+    } else {
       changes.push({ type: "update", row: next.row, previous: old.row, index: next.index });
     }
+    reconciled[next.index] = kept;
     if (old.index !== next.index) {
       changes.push({
         type: "move",
         key: next.row[key],
-        row: next.row,
+        row: kept,
         from: old.index,
         to: next.index
       });
     }
   }
-  return changes;
+  if (changes.length === 0 && rows.length === previousRows.length) {
+    return { changes, rows: previousRows, index: current };
+  }
+  return {
+    changes,
+    rows: reused === 0 ? rows : Object.freeze(reconciled),
+    index: current
+  };
 }
 class KeyedLiveQuery {
   #source;
@@ -72,6 +95,8 @@ class KeyedLiveQuery {
   #listeners = /* @__PURE__ */ new Set();
   #sourceUnsubscribe;
   #rows = [];
+  #sourceRows;
+  #index;
   #snapshot = { status: "loading", rows: [] };
   #hasReadySnapshot = false;
   #closed = false;
@@ -141,23 +166,35 @@ class KeyedLiveQuery {
       this.#emit();
       return;
     }
+    if (this.#snapshot.status === "ready" && snapshot.rows === this.#sourceRows && this.#snapshot.version === snapshot.version) {
+      return;
+    }
     try {
       if (this.#maxRows !== void 0 && snapshot.rows.length > this.#maxRows) {
         throw new RangeError(`Live query window returned ${String(snapshot.rows.length)} rows; maximum is ${String(this.#maxRows)}`);
       }
       const initial = !this.#hasReadySnapshot;
       let changes;
-      if (initial) {
-        indexRows(snapshot.rows, this.#key);
+      let rows;
+      if (initial || this.#index === void 0) {
+        this.#index = indexRows(snapshot.rows, this.#key);
+        rows = snapshot.rows;
         changes = snapshot.rows.map((row, index) => ({ type: "insert", row, index }));
+      } else if (snapshot.rows === this.#sourceRows) {
+        rows = this.#rows;
+        changes = [];
       } else {
-        changes = diffRows(this.#rows, snapshot.rows, this.#key);
+        const diff = diffRows(this.#index, this.#rows, snapshot.rows, this.#key);
+        this.#index = diff.index;
+        rows = diff.rows;
+        changes = diff.changes;
       }
-      this.#rows = snapshot.rows;
+      this.#rows = rows;
+      this.#sourceRows = snapshot.rows;
       this.#hasReadySnapshot = true;
       this.#snapshot = {
         status: "ready",
-        rows: snapshot.rows,
+        rows,
         changes: Object.freeze(changes),
         initial,
         version: snapshot.version

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;
+}

package/dist/engine/live-aggregate.js

@@ -0,0 +1,226 @@
+import { childExpressions, hasAggregate, mapChildExpressions, executeRowQueryInternal, inferResultColumnDomains, externalizeQueryResult } from "./query.js";
+import { encodeQueryIdentity } from "./query-identity.js";
+import { exactNumericBinary, exactNumericValue, externalSqlDomainValue, isExactNumeric } from "./sql-domains.js";
+import { encodeSqlEqualityValue } from "./sql-semantics.js";
+class LiveAggregate {
+  inputPlan;
+  #outputPlan;
+  #aggregates;
+  #groupAliases;
+  #rows;
+  #groups;
+  #domains;
+  keyAlias;
+  #schema;
+  constructor(inputPlan, outputPlan, aggregates, groupAliases, keyAlias, rows = /* @__PURE__ */ new Map(), groups = /* @__PURE__ */ new Map(), domains = [], schema = []) {
+    this.inputPlan = inputPlan;
+    this.#outputPlan = outputPlan;
+    this.#aggregates = aggregates;
+    this.#groupAliases = groupAliases;
+    this.keyAlias = keyAlias;
+    this.#rows = rows;
+    this.#groups = groups;
+    this.#domains = domains;
+    this.#schema = schema;
+  }
+  static plan(plan, qualifiedKey) {
+    const aggregates = [];
+    const groupAliases = plan.groupBy.map((_, index) => `__minnow_live_group_${String(index)}`);
+    const groupKeys = new Map(plan.groupBy.map((expression, index) => [
+      encodeQueryIdentity(expression),
+      groupAliases[index] ?? ""
+    ]));
+    const rowLocal = (expression) => !hasAggregate(expression) && !["subquery", "exists", "window", "parameter", "wildcard"].includes(expression.kind) && childExpressions(expression).every(rowLocal);
+    if (!plan.groupBy.every(rowLocal))
+      return void 0;
+    const rewrite = (expression) => {
+      const grouped = groupKeys.get(encodeQueryIdentity(expression));
+      if (grouped !== void 0)
+        return { kind: "column", reference: grouped };
+      if (expression.kind === "call" && hasAggregate(expression)) {
+        if (!["COUNT", "SUM", "AVG"].includes(expression.name) || expression.arguments.length !== 1)
+          throw new TypeError("Not an additive live aggregate");
+        const argument = expression.arguments[0];
+        if (argument === void 0 || !(rowLocal(argument) || expression.name === "COUNT" && argument.kind === "wildcard"))
+          throw new TypeError("Not a row-local aggregate argument");
+        const alias = `__minnow_live_value_${String(aggregates.length)}`;
+        aggregates.push({
+          name: expression.name,
+          alias,
+          argument: argument.kind === "wildcard" ? { kind: "literal", value: 1 } : argument
+        });
+        return { kind: "column", reference: alias };
+      }
+      if (expression.kind === "column" || expression.kind === "window" || expression.kind === "subquery" || expression.kind === "exists")
+        throw new TypeError("Not a grouped live expression");
+      return mapChildExpressions(expression, rewrite);
+    };
+    try {
+      const select = plan.select.map((item) => ({ ...item, expression: rewrite(item.expression) }));
+      const having = plan.having.map((predicate) => ({
+        ...predicate,
+        left: rewrite(predicate.left),
+        right: rewrite(predicate.right)
+      }));
+      const outputAliases = new Set(select.map((item) => item.alias));
+      const orderBy = plan.orderBy.map((term) => ({
+        ...term,
+        expression: term.expression.kind === "column" && outputAliases.has(term.expression.reference) ? term.expression : rewrite(term.expression)
+      }));
+      if (aggregates.length === 0)
+        return void 0;
+      const keyAlias = "__minnow_live_aggregate_key";
+      const inputPlan = {
+        ...plan,
+        select: [
+          { alias: keyAlias, expression: { kind: "column", reference: qualifiedKey } },
+          ...plan.groupBy.map((expression, index) => ({
+            alias: groupAliases[index] ?? "",
+            expression
+          })),
+          ...aggregates.map(({ alias, argument }) => ({ alias, expression: argument }))
+        ],
+        groupBy: [],
+        having: [],
+        orderBy: []
+      };
+      delete inputPlan.limit;
+      delete inputPlan.offset;
+      const outputPlan = {
+        ...plan,
+        base: { table: "__minnow_live_groups", alias: "__minnow_live_groups" },
+        joins: [],
+        select,
+        predicates: having,
+        groupBy: [],
+        having: [],
+        orderBy
+      };
+      return new LiveAggregate(inputPlan, outputPlan, aggregates, groupAliases, keyAlias);
+    } catch {
+      return void 0;
+    }
+  }
+  patch(result, changed, token) {
+    const rows = new Map(this.#rows);
+    const groups = new Map(this.#groups);
+    const touched = /* @__PURE__ */ new Set();
+    const groupFor = (key, keys = []) => {
+      let group = groups.get(key);
+      if (group === void 0) {
+        group = {
+          keys,
+          members: 0,
+          counts: this.#aggregates.map(() => 0),
+          sums: this.#aggregates.map(() => exactNumericValue(0) ?? ""),
+          absolute: this.#aggregates.map(() => 0)
+        };
+        groups.set(key, group);
+        touched.add(key);
+      } else if (!touched.has(key)) {
+        group = {
+          ...group,
+          counts: [...group.counts],
+          sums: [...group.sums],
+          absolute: [...group.absolute]
+        };
+        groups.set(key, group);
+        touched.add(key);
+      }
+      return group;
+    };
+    const apply = (group, values, sign) => {
+      group.members += sign;
+      for (const [index, aggregate] of this.#aggregates.entries()) {
+        const value = values[index] ?? null;
+        if (value === null)
+          continue;
+        group.counts[index] = (group.counts[index] ?? 0) + sign;
+        if (aggregate.name !== "COUNT") {
+          if (typeof value !== "number" && !isExactNumeric(value))
+            throw new TypeError("Live SUM requires numeric values");
+          if (typeof value === "number") {
+            if (!Number.isSafeInteger(value))
+              throw new TypeError("Floating-point aggregates require full execution");
+            group.absolute[index] = (group.absolute[index] ?? 0) + sign * Math.abs(value);
+            if (!Number.isSafeInteger(group.absolute[index]))
+              throw new TypeError("Aggregate sum may round; requires full execution");
+          }
+          const sum = exactNumericBinary(sign === 1 ? "+" : "-", group.sums[index] ?? exactNumericValue(0), exactNumericValue(value));
+          if (sum === null || sum === void 0)
+            throw new TypeError("Invalid numeric aggregate contribution");
+          group.sums[index] = sum;
+        }
+      }
+    };
+    for (const key of changed) {
+      const old = rows.get(key);
+      if (old === void 0)
+        continue;
+      apply(groupFor(old.group), old.values, -1);
+      rows.delete(key);
+    }
+    for (const row of result.rows) {
+      const key = token(row[this.keyAlias] ?? null);
+      const keys = this.#groupAliases.map((alias) => row[alias] ?? null);
+      const group = JSON.stringify(keys.map(encodeSqlEqualityValue));
+      const values = this.#aggregates.map(({ alias }) => row[alias] ?? null);
+      apply(groupFor(group, keys), values, 1);
+      rows.set(key, { group, values });
+    }
+    if (this.#groupAliases.length === 0)
+      groupFor("[]");
+    else
+      for (const key of touched)
+        if (groups.get(key)?.members === 0)
+          groups.delete(key);
+    const domains = this.#aggregates.map(({ alias }, index) => result.columnDomains[result.columns.indexOf(alias)] ?? this.#domains[index] ?? null);
+    return new LiveAggregate(this.inputPlan, this.#outputPlan, this.#aggregates, this.#groupAliases, this.keyAlias, rows, groups, domains, result.columns.map((name, index) => {
+      const domain = result.columnDomains[index];
+      const value = result.rows.find((row) => row[name] !== null)?.[name];
+      const aggregate = this.#aggregates.find((item) => item.alias === name);
+      return {
+        name,
+        type: aggregate?.name === "COUNT" ? "number" : domain !== null && domain !== void 0 ? "string" : typeof value === "number" ? "number" : typeof value === "boolean" ? "boolean" : value instanceof Date ? "datetime" : "string",
+        ...domain === null || domain === void 0 || aggregate?.name === "COUNT" ? {} : { sqlDomain: domain }
+      };
+    }));
+  }
+  result() {
+    const rows = [];
+    for (const group of this.#groups.values()) {
+      const row = {};
+      for (const [index, alias] of this.#groupAliases.entries())
+        row[alias] = group.keys[index] ?? null;
+      for (const [index, aggregate] of this.#aggregates.entries()) {
+        const count = group.counts[index] ?? 0;
+        const domain = this.#domains[index];
+        let value = aggregate.name === "COUNT" ? count : count === 0 ? null : group.sums[index] ?? null;
+        if (value !== null && aggregate.name !== "COUNT") {
+          if (domain?.kind !== "numeric") {
+            value = Number(externalSqlDomainValue(value));
+            if (aggregate.name === "AVG")
+              value /= count;
+          } else if (aggregate.name === "AVG")
+            value = exactNumericBinary("/", value, count, domain.scale) ?? null;
+        }
+        row[aggregate.alias] = value;
+      }
+      rows.push(row);
+    }
+    const result = executeRowQueryInternal(this.#outputPlan, /* @__PURE__ */ new Map([["__minnow_live_groups", rows]]));
+    result.columnDomains = inferResultColumnDomains(this.#outputPlan, /* @__PURE__ */ new Map([["__minnow_live_groups", this.#schema]]));
+    return externalizeQueryResult(result);
+  }
+  get retainedBytes() {
+    let bytes = 256 + encodeQueryIdentity(this.inputPlan).length * 2 + encodeQueryIdentity(this.#outputPlan).length * 2;
+    for (const [key, row] of this.#rows)
+      bytes += 64 + key.length * 2 + row.group.length * 2 + row.values.reduce((sum, value) => sum + (typeof value === "string" ? value.length * 2 + 16 : 16), 0);
+    for (const [key, group] of this.#groups)
+      bytes += 96 + key.length * 2 + group.sums.reduce((sum, value) => sum + value.length * 2 + 24, 0);
+    return bytes;
+  }
+}
+export {
+  LiveAggregate
+};

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

@@ -0,0 +1,21 @@
+import type { QueryResult, QueryRow } from "../plan/model.js";
+import type { LiveQueryDelivery } from "./live.js";
+export type LiveQueryPatch = {
+    readonly type: "reset";
+    readonly result: QueryResult;
+} | {
+    readonly type: "patch";
+    /** Each next position's previous position, or -1 for a changed/new row. */
+    readonly retained: Int32Array;
+    readonly changedRows: ReadonlyArray<{
+        readonly index: number;
+        readonly row: QueryRow;
+    }>;
+};
+export interface LiveQueryPatchOptions {
+    onPatch(patch: LiveQueryPatch, delivery: LiveQueryDelivery): void;
+    onError?(error: unknown): void;
+    onComplete?(): void;
+}
+/** Copy only changed payloads when provenance is available; resets establish a fresh baseline. */
+export declare function createLiveQueryPatch(result: QueryResult, delivery: LiveQueryDelivery): LiveQueryPatch;

package/dist/engine/live-patch.js

@@ -0,0 +1,31 @@
+import { copyDate } from "../date-value.js";
+function copyRow(row) {
+  const copy = { ...row };
+  for (const key of Object.keys(copy)) {
+    const value = copy[key];
+    if (value instanceof Date)
+      copy[key] = copyDate(value);
+  }
+  return copy;
+}
+function createLiveQueryPatch(result, delivery) {
+  if (delivery.retained === void 0 || delivery.initial)
+    return {
+      type: "reset",
+      result: {
+        columns: [...result.columns],
+        columnDomains: structuredClone(result.columnDomains),
+        rows: result.rows.map(copyRow)
+      }
+    };
+  const changedRows = [];
+  for (let index = 0; index < result.rows.length; index += 1) {
+    const row = result.rows[index];
+    if (row !== void 0 && (delivery.retained[index] ?? -1) < 0)
+      changedRows.push({ index, row: copyRow(row) });
+  }
+  return { type: "patch", retained: new Int32Array(delivery.retained), changedRows };
+}
+export {
+  createLiveQueryPatch
+};

package/dist/engine/live.d.ts

@@ -1,3 +1,5 @@
+import { type LiveQueryPatchOptions } from "./live-patch.js";
+export type { LiveQueryPatch, LiveQueryPatchOptions } from "./live-patch.js";
 import { type CatalogProbe, type Manifest, type StoragePage } from "../storage/types.js";
 import { type CompiledQuery, type QueryResult, type QueryValue } from "./query.js";
 /**
@@ -6,8 +8,11 @@ import { type CompiledQuery, type QueryResult, type QueryValue } from "./query.j
  * table sets then decide which prepared queries may be stale. Hints may be lost, duplicated, or
  * reordered without changing correctness.
  *
- * Equal statements share one dependency record and one execution per sweep. Results retain an
- * exact private snapshot: a 32-bit digest is only a fast inequality check, never proof of equality.
+ * A sweep costs what changed, not what is subscribed: the commit window's table set selects the
+ * groups to visit through a per-table index, and a group nobody visits keeps its result on the
+ * strength of the invariant that every window touching one of its tables would have visited it.
+ * Equal statements share one dependency record and one execution per sweep. Results are compared
+ * exactly, row by row, so an unchanged result never reaches a subscriber.
  */
 export interface LiveQueryHintChannel {
     postMessage(message: unknown): void;
@@ -24,6 +29,22 @@ export interface LiveQuerySetOptions {
     readonly maxGroups?: number;
     /** Maximum result/observer subscriptions retained by this set. Defaults to 1,024. */
     readonly maxSubscriptions?: number;
+    /** Maximum modeled resident result and maintenance bytes per set. Defaults to 64 MiB. */
+    readonly maxRetainedBytes?: number;
+    /**
+     * Hand `onChange` the set's retained result instead of a private copy. The result is shared
+     * with every equal subscription and with the next change comparison, so a subscriber must
+     * treat it as read-only. A consumer that only reads it synchronously — the worker host that
+     * encodes it for the channel, a renderer that copies what it displays — saves one full copy
+     * per subscriber per change.
+     */
+    readonly sharedResults?: boolean;
+    /**
+     * Whether the set may patch a retained result from a commit's rows instead of re-running the
+     * statement, for statements the host can maintain that way. Defaults to true; false makes
+     * every relevant commit a full execution, which is useful when comparing the two.
+     */
+    readonly incremental?: boolean;
     /** Called once when the set closes; the owner uses this to drop its reference. */
     readonly onClosed?: () => void;
 }
@@ -33,8 +54,23 @@ export declare const MAX_LIVE_QUERY_GROUPS = 4096;
 export declare const MAX_LIVE_QUERY_SUBSCRIPTIONS = 16384;
 export declare const MAX_LIVE_QUERY_SETS_PER_DATABASE = 256;
 export { LiveQueryLimitError } from "./errors.js";
+/** What a delivered result reflects: the probe it is current as of, and whether it is the first. */
+export interface LiveQueryDelivery {
+    readonly manifestVersion: number | null;
+    readonly catalogEpoch: number;
+    readonly initial: boolean;
+    /**
+     * For each row, the index it held in this subscription's previous delivery, or -1 for a row
+     * that is new or changed. Present when the engine kept row objects across the change — a
+     * patched result keeps every untouched row — and absent after a full execution or on the
+     * first delivery. A consumer that keys on row identity substitutes its own previous objects.
+     */
+    readonly retained?: Int32Array;
+}
 export interface LiveQuerySubscribeOptions {
-    onChange(result: QueryResult): void;
+    /** Borrow the read-only retained result for this subscription instead of copying it. */
+    readonly sharedResults?: boolean;
+    onChange(result: QueryResult, delivery: LiveQueryDelivery): void;
     onError?(error: unknown): void;
     /** Called once when the subscription ends because the subscription or its set closed. */
     onComplete?(): void;
@@ -48,6 +84,14 @@ export interface LiveQueryObserveOptions {
     onInvalidate(invalidation: LiveQueryInvalidation): void;
     onError?(error: unknown): void;
     onComplete?(): void;
+    /**
+     * Execute the statement inside the set on every relevant commit and invalidate only when the
+     * rows changed. The engine keeps that execution in its result memo, so an adapter that then
+     * re-executes the same statement at the same version is served from cache rather than from a
+     * second scan. A commit that leaves the rows as they were costs one execution and reaches no
+     * observer at all — nothing crosses a worker channel and nothing re-renders.
+     */
+    readonly suppressUnchanged?: boolean;
 }
 export interface LiveQuerySubscription {
     readonly dependencyTableIds: readonly string[];
@@ -58,12 +102,26 @@ export interface LiveQueryStats {
     versionChecks: number;
     sweeps: number;
     reruns: number;
+    /** Subscribed groups a sweep did not re-run: nothing they read changed, or a proof said so. */
     rerunsAvoided: number;
     /** Re-runs skipped because the data layer proved the commits could not change the result. */
     zoneSkips: number;
+    /** Deliveries withheld because an execution produced exactly the rows already delivered. */
     notificationsSuppressed: number;
-    /** Observer-only invalidations delivered without executing the statement inside the set. */
+    /** Observer invalidations delivered. */
     invalidations: number;
+    /** Re-runs answered by patching the retained result with the commit's rows instead. */
+    maintained: number;
+    /** Groups a sweep looked at: those whose tables the commits changed, plus any left lagging. */
+    groupsVisited: number;
+    /**
+     * Rows the set currently retains across every group's last result — what its subscriptions
+     * display, counted once per distinct statement. A window's margin beyond its visible rows is
+     * bounded by the engine at 64 rows and is not included.
+     */
+    retainedRows: number;
+    /** Modeled resident result and incremental maintenance bytes, counted once per group. */
+    retainedBytes: number;
     /** Work avoided because equal statements shared one query group or in-flight execution. */
     sharedExecutions: number;
     lastSweepMs: number;
@@ -77,11 +135,50 @@ export type LiveQueryInput = string | {
     kind: "typed-query";
     plan: CompiledQuery;
 };
-interface LiveQueryHost {
+/** What the set already knows when it asks the host to execute a statement. */
+export interface LiveQueryExecuteContext {
+    /**
+     * A freshness probe the set read moments ago. The host may start execution from it instead of
+     * reading its own; a result may still observe a newer commit, and the set treats the probe as
+     * a lower bound on what the result reflects.
+     */
+    readonly probe: CatalogProbe;
+    /**
+     * Whether the host should keep the result in its memo. The set retains its own copy, so a
+     * memo entry only pays off when another caller — an adapter re-executing after an
+     * invalidation — will ask for the same statement at the same version.
+     */
+    readonly memoize: boolean;
+}
+/** A maintainable statement's execution: its result and the host's opaque state for patching it. */
+export interface LiveMaintainedExecution {
+    readonly result: QueryResult;
+    readonly state: unknown;
+    /** Modeled total bytes retained by the result and opaque maintenance state. */
+    readonly retainedBytes?: number;
+}
+export interface LiveMaintainedChange extends LiveMaintainedExecution {
+    readonly changed: boolean;
+    /** For each row of `result`, its index in the previous result, or -1; see `LiveQueryDelivery`. */
+    readonly retained?: Int32Array;
+}
+export interface LiveQueryHost {
     currentProbe(): Promise<CatalogProbe>;
     manifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
-    dependencyTableIds(query: LiveQueryInput): Promise<Set<string>>;
-    execute(query: LiveQueryInput): Promise<QueryResult>;
+    /** The base tables the statement reads, resolved through views; `probe` is a recent read. */
+    dependencyTableIds(query: LiveQueryInput, probe?: CatalogProbe): Promise<Set<string>>;
+    /** Executes the statement; the returned result belongs to the set and is never shared. */
+    execute(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<QueryResult>;
+    /**
+     * Executes a statement the host can later maintain incrementally, or returns undefined when
+     * the statement's shape rules that out; the set then executes it in full from then on.
+     */
+    executeMaintainable?(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<LiveMaintainedExecution | undefined>;
+    /**
+     * Patches a retained result with the row changes the commits in (after, until] made to
+     * `tableIds`, or returns undefined when only a full execution can answer.
+     */
+    maintain?(query: LiveQueryInput, result: QueryResult, state: unknown, tableIds: readonly string[], after: number | null, until: number, probe: CatalogProbe): Promise<LiveMaintainedChange | undefined>;
     /** Returns false only on proof that the commit window cannot affect the statement. */
     changeCanAffect?(query: LiveQueryInput, tableIds: readonly string[], after: number | null, until: number): Promise<boolean>;
 }
@@ -91,7 +188,9 @@ export declare class LiveQuerySet {
     get stats(): LiveQueryStats;
     /** Registers a query, delivers its current result, and shares work with equal statements. */
     subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscription>;
-    /** Observes invalidation without executing the statement inside the set. */
+    /** Delivers resets or changed row payloads without constructing a private full row array per patch. */
+    subscribePatches(query: LiveQueryInput, options: LiveQueryPatchOptions): Promise<LiveQuerySubscription>;
+    /** Observes invalidation; the statement executes inside the set only when asked to compare. */
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscription>;
     /** Called by the owning database after each local write commit; also hints other tabs. */
     notifyLocalCommit(): void;