@minnowdb/core 0.5.0 → 0.6.1

package/dist/engine/worker-host.js

@@ -12,6 +12,54 @@ const stageOps = ["insertBatch", "upsertBatch", "updateBatch", "deleteBatch"];
 function isStageOp(value) {
     return typeof value === "string" && stageOps.includes(value);
 }
+/**
+ * Root methods whose arguments and results are already structured-clone-safe. `satisfies` makes
+ * a removed or renamed database method a compile error, while the runtime guard below fails
+ * closed if a caller supplies a malformed database object through the manual host seam.
+ */
+const directRootMethods = [
+    "createTable",
+    "createView",
+    "dropView",
+    "dropColumn",
+    "dropTable",
+    "createIndex",
+    "dropIndex",
+    "buildFtsIndex",
+    "introspect",
+    "listTables",
+    "insertBatch",
+    "insert",
+    "upsertBatch",
+    "upsert",
+    "updateBatch",
+    "update",
+    "deleteBatch",
+    "delete",
+    "runStatement",
+    "explain",
+    "execute",
+    "listVisibleSegmentPage",
+    "cleanupQuerySpill",
+    "compactTable",
+    "compactTableStep",
+    "resumeCompactionJob",
+    "listCompactionJobs",
+    "cancelCompactionJob",
+    "collectGarbage",
+    "collectGarbageStep",
+    "resumeGarbageCollectionJob",
+    "bufferPoolStats",
+    "maintenanceStatus",
+    "checkIntegrity",
+    "storageStats",
+    "inspectInterruptedImport",
+    "abortInterruptedImport",
+    "listGarbageCollectionJobs",
+];
+function isDirectRootMethod(value) {
+    return directRootMethods.includes(value);
+}
 /**
  * A call result that travels as a columnar frame with its buffers transferred. Only query
  * results take this path: rows of objects are what structured clone is slowest at, so they are
@@ -120,10 +168,17 @@ class SnapshotImportChunkQueue {
 function snapshotQueueError(value) {
     return value instanceof Error ? value : new Error("Snapshot transfer failed", { cause: value });
 }
+function abortError(message) {
+    const error = new Error(message);
+    error.name = "AbortError";
+    return error;
+}
 /** Hard per-connection ceiling for resident worker resources abandoned by a client. */
 export const MAX_WORKER_HANDLES_PER_CONNECTION = 256;
 const DEFAULT_WRITE_HANDLE_IDLE_TIMEOUT_MS = 30_000;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Shared by RPC methods that do not expose cancellation, avoiding one controller per call. */
+const passiveRpcSignal = new AbortController().signal;
 class DatabaseRpcServer {
     database;
     scope;
@@ -132,6 +187,7 @@ class DatabaseRpcServer {
     #reservedHandleIds = new Set();
     #openingHandlePromises = new Set();
     #settlingWritePromises = new Set();
+    #requestAborts = new Map();
     #disposed = false;
     #inFlightRpcCount = 0;
     #inFlightRpcDrain;
@@ -154,6 +210,12 @@ class DatabaseRpcServer {
             this.scope.postMessage(rpcResult(request.requestId, { ready: true }));
             return;
         }
+        if (request.kind === "rpc-cancel") {
+            this.#requestAborts
+                .get(request.requestId)
+                ?.abort(abortError("Database request was cancelled"));
+            return;
+        }
         const bypassLimit = request.method === "dispose";
         if (!bypassLimit && this.#inFlightRpcCount >= MAX_DATABASE_RPC_IN_FLIGHT) {
             this.scope.postMessage(rpcFailure(request.requestId, new RangeError(`A database worker connection cannot hold more than ${String(MAX_DATABASE_RPC_IN_FLIGHT)} in-flight requests`)));
@@ -161,12 +223,19 @@ class DatabaseRpcServer {
         }
         if (!bypassLimit)
             this.#inFlightRpcCount += 1;
+        const abort = request.method === "query" ? new AbortController() : undefined;
+        if (abort !== undefined)
+            this.#requestAborts.set(request.requestId, abort);
+        const context = {
+            requestId: request.requestId,
+            signal: abort?.signal ?? passiveRpcSignal,
+        };
         try {
             if (this.#disposed)
                 throw new Error("Database connection is disposed");
             const result = request.handleId === null
-                ? await this.#callRoot(request.method, request.args)
-                : await this.#callHandle(request.handleId, request.method, request.args);
+                ? await this.#callRoot(request.method, request.args, context)
+                : await this.#callHandle(request.handleId, request.method, request.args, context);
             if (result instanceof ColumnarResult) {
                 this.scope.postMessage(rpcResult(request.requestId, result.encoded.payload), {
                     transfer: result.encoded.transfer,
@@ -190,6 +259,8 @@ class DatabaseRpcServer {
             this.scope.postMessage(rpcFailure(request.requestId, error));
         }
         finally {
+            if (abort !== undefined)
+                this.#requestAborts.delete(request.requestId);
             if (!bypassLimit)
                 this.#inFlightRpcCount -= 1;
             if (this.#inFlightRpcCount === 0 && this.#resolveInFlightRpcDrain !== undefined) {
@@ -200,50 +271,44 @@ class DatabaseRpcServer {
             }
         }
     }
-    async #callRoot(method, args) {
+    async #callRoot(method, args, context) {
         const database = this.database;
+        if (isDirectRootMethod(method)) {
+            const operation = database[method];
+            if (operation === undefined) {
+                throw new Error(`Database root method is unavailable: ${method}`);
+            }
+            return operation.apply(this.database, args);
+        }
         switch (method) {
-            case "createTable":
-            case "introspect":
-            case "listTables":
-            case "insertBatch":
-            case "insert":
-            case "upsertBatch":
-            case "upsert":
-            case "updateBatch":
-            case "update":
-            case "deleteBatch":
-            case "delete":
-            case "runStatement":
-            case "explain":
-            case "execute":
-            case "listVisibleSegmentPage":
-            case "cleanupQuerySpill":
-            case "compactTable":
-            case "compactTableStep":
-            case "resumeCompactionJob":
-            case "listCompactionJobs":
-            case "cancelCompactionJob":
-            case "collectGarbage":
-            case "collectGarbageStep":
-            case "resumeGarbageCollectionJob":
-            case "bufferPoolStats":
-            case "maintenanceStatus":
-            case "checkIntegrity":
-            case "storageStats":
-            case "inspectInterruptedImport":
-            case "abortInterruptedImport":
-            case "listGarbageCollectionJobs":
-                return database[method]?.(...args);
             case "query": {
-                const [sql, options] = args;
-                return new ColumnarResult(encodeQueryResult(await this.database.query(sql, options)));
+                const [sql, options, reportStats = false] = args;
+                return new ColumnarResult(encodeQueryResult(await this.database.query(sql, {
+                    ...options,
+                    signal: context.signal,
+                    ...(reportStats
+                        ? {
+                            onStats: (stats) => {
+                                this.scope.postMessage(rpcEvent(context.requestId, "stats", stats));
+                            },
+                        }
+                        : {}),
+                })));
             }
             case "queryCursorOpen": {
                 const handleId = this.#claimHandleId(args[0]);
-                const [sql, options] = args.slice(1);
+                const [sql, options, reportStats = false] = args.slice(1);
                 try {
-                    const iterator = this.database.queryCursor(sql, options);
+                    const iterator = this.database.queryCursor(sql, {
+                        ...options,
+                        ...(reportStats
+                            ? {
+                                onStats: (stats) => {
+                                    this.scope.postMessage(rpcEvent(handleId, "stats", stats));
+                                },
+                            }
+                            : {}),
+                    });
                     this.#publishHandle(handleId, { type: "query-cursor", iterator });
                 }
                 catch (error) {
@@ -465,14 +530,14 @@ class DatabaseRpcServer {
         void opening.then(() => this.#openingHandlePromises.delete(opening), () => this.#openingHandlePromises.delete(opening));
         return opening;
     }
-    async #callHandle(handleId, method, args) {
+    async #callHandle(handleId, method, args, context) {
         const handle = this.#handles.get(handleId);
         if (handle === undefined)
             throw new Error(`Unknown handle: ${handleId}`);
         if (handle.type === "write") {
             this.#beginWriteHandleCall(handle);
             try {
-                return await this.#callWriteHandle(handleId, handle, method, args);
+                return await this.#callWriteHandle(handleId, handle, method, args, context);
             }
             finally {
                 this.#endWriteHandleCall(handleId, handle);
@@ -523,10 +588,20 @@ class DatabaseRpcServer {
             }
         }
     }
-    async #callWriteHandle(handleId, handle, method, args) {
+    async #callWriteHandle(handleId, handle, method, args, context) {
         if (method === "query") {
-            const [sql, options] = args;
-            return new ColumnarResult(encodeQueryResult(await handle.session.query(sql, options)));
+            const [sql, options, reportStats = false] = args;
+            return new ColumnarResult(encodeQueryResult(await handle.session.query(sql, {
+                ...options,
+                signal: context.signal,
+                ...(reportStats
+                    ? {
+                        onStats: (stats) => {
+                            this.scope.postMessage(rpcEvent(context.requestId, "stats", stats));
+                        },
+                    }
+                    : {}),
+            })));
         }
         if (method === "execute") {
             const [sql, params] = args;

package/dist/plan/index.d.ts

@@ -7,10 +7,11 @@
  * Exposing them here lets an external builder produce plans the engine treats as indistinguishable
  * from parsed SQL.
  *
- * This module re-exports rather than owns: the plan types still live beside the parser that
- * produces them. Splitting them into a leaf module of their own is the next step, and it will not
- * change this entry point.
+ * The recursive logical model lives in the dependency-light `model` leaf; executable assembly
+ * and validation stay with the compiler. This entry point keeps that distinction invisible to
+ * consumers.
  */
-export { assembleSelectBlock, compoundSelectBlock, derivedTableSource, hasAggregate, splitCondition, validateLimit, validateOffset, type AggregateName, type CompiledQuery, type CompiledStatement, type Expression, type JoinPlan, type Predicate, type PredicateOperator, type QueryResult, type QueryRow, type QueryValue, type SelectItem, type SetOperator, type TableSource, type WindowFunctionName, } from "../engine/query.js";
+export { assembleSelectBlock, compoundSelectBlock, derivedTableSource, hasAggregate, splitCondition, validateLimit, validateOffset, type CompiledStatement, } from "../engine/query.js";
+export type { AggregateName, CompiledQuery, Expression, JoinPlan, Predicate, PredicateOperator, QueryResult, QueryRow, QueryValue, SelectItem, SetOperator, TableSource, WindowFunctionName, } from "./model.js";
 export { optimizePlan, renderPlan } from "../engine/optimizer.js";
 export { validateFtsQuery } from "../engine/fts.js";

package/dist/plan/index.js

@@ -7,9 +7,9 @@
  * Exposing them here lets an external builder produce plans the engine treats as indistinguishable
  * from parsed SQL.
  *
- * This module re-exports rather than owns: the plan types still live beside the parser that
- * produces them. Splitting them into a leaf module of their own is the next step, and it will not
- * change this entry point.
+ * The recursive logical model lives in the dependency-light `model` leaf; executable assembly
+ * and validation stay with the compiler. This entry point keeps that distinction invisible to
+ * consumers.
  */
 export { assembleSelectBlock, compoundSelectBlock, derivedTableSource, hasAggregate, splitCondition, validateLimit, validateOffset, } from "../engine/query.js";
 export { optimizePlan, renderPlan } from "../engine/optimizer.js";

package/dist/plan/model.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The dependency-light logical plan shared by the SQL compiler, optimizer, vector executor, and
+ * external typed-query builders. Keep executable parser/engine code out of this module: importing
+ * these types must never create a runtime dependency edge.
+ */
+import type { SqlDomain } from "../storage/types.js";
+export type QueryValue = boolean | number | string | Date | null;
+export type QueryRow = Record<string, QueryValue>;
+export interface QueryResult {
+    columns: string[];
+    /** Logical SQL domain for each output column, positionally aligned with `columns`. */
+    columnDomains: Array<SqlDomain | null>;
+    rows: QueryRow[];
+}
+export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "||";
+export type ComparisonOperator = "=" | "!=" | "<>" | ">" | ">=" | "<" | "<=";
+export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX" | "JSON_ARRAYAGG" | "STRING_AGG"
+/** Optimizer-only aggregate that enforces scalar-subquery cardinality. */
+ | "MINNOW_SINGLE_VALUE";
+export type ScalarFunctionName = "ROUND" | "COALESCE" | "DATE_TRUNC" | "DATE_ADD" | "UPPER" | "LOWER" | "LENGTH" | "ABS" | "TRIM" | "LTRIM" | "RTRIM" | "SUBSTR" | "REPLACE" | "INSTR" | "NULLIF" | "GREATEST" | "LEAST" | "FLOOR" | "CEIL" | "MOD" | "POWER" | "SQRT" | "EXTRACT" | "CAST" | "OCTET_LENGTH" | "LPAD" | "RPAD" | "OVERLAY" | "CURRENT_DATE" | "CURRENT_TIMESTAMP" | "LOCALTIME" | "GROUPING" | "JSON_VALUE" | "JSON_QUERY" | "JSON_EXISTS" | "JSON_OBJECT" | "JSON_ARRAY" | "IS_JSON" | "ARRAY"
+/** Optimizer-only, prefix-free equality key for hashable multi-column decorrelation. */
+ | "MINNOW_TUPLE_KEY"
+/** Parser-produced wrapper carrying one explicit collation through ordering/comparison. */
+ | "MINNOW_COLLATE" | "NEXTVAL" | "CURRVAL" | "RANDOM" | "GEN_RANDOM_UUID";
+/** Exact BM25 corpus statistics attached to a cloned scoring node before execution. */
+export interface FtsStats {
+    /** Every row of the corpus, including all-null documents. */
+    docCount: number;
+    /** Total tokens across all documents. */
+    totalTokens: number;
+    /** Documents containing each query term, aligned with the query's term order. */
+    dfByTerm: number[];
+}
+export type Expression = {
+    kind: "literal";
+    value: QueryValue;
+    internalSqlValue?: true;
+    sqlDomain?: SqlDomain;
+}
+/** A `?` or `$n` placeholder; `index` is 0-based. Replaced by a literal at bind time. */
+ | {
+    kind: "parameter";
+    index: number;
+} | {
+    kind: "column";
+    reference: string;
+}
+/** `*`, or `alias.*` when `table` is set. */
+ | {
+    kind: "wildcard";
+    table?: string;
+} | {
+    kind: "binary";
+    operator: BinaryOperator;
+    left: Expression;
+    right: Expression;
+} | {
+    kind: "call";
+    name: AggregateName | ScalarFunctionName;
+    arguments: Expression[];
+    distinct?: boolean;
+    aggregateOrderBy?: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+} | {
+    kind: "list";
+    items: Expression[];
+} | {
+    kind: "subquery";
+    block: CompiledQuery;
+} | {
+    kind: "condition";
+    operator: PredicateOperator;
+    left: Expression;
+    right: Expression;
+    escape?: string;
+} | {
+    kind: "logical";
+    operator: "and" | "or";
+    left: Expression;
+    right: Expression;
+} | {
+    kind: "not";
+    operand: Expression;
+} | {
+    kind: "exists";
+    block: CompiledQuery;
+    negated: boolean;
+} | {
+    kind: "case";
+    branches: Array<{
+        when: Expression;
+        then: Expression;
+    }>;
+    otherwise?: Expression;
+} | {
+    kind: "window";
+    name: WindowFunctionName;
+    partitionBy: Expression[];
+    orderBy: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+    argument?: Expression;
+    offset?: number;
+    fallback?: QueryValue;
+    frame?: WindowFrame;
+} | {
+    kind: "fts";
+    op: "match" | "bm25";
+    /** Column references forming the document, or `*` for all searchable scan columns. */
+    columns: Expression[] | "*";
+    query: string;
+    queryParameter?: number;
+    stats?: FtsStats;
+};
+export type WindowFunctionName = "ROW_NUMBER" | "RANK" | "DENSE_RANK" | "PERCENT_RANK" | "CUME_DIST" | "NTILE" | "LAG" | "LEAD" | "FIRST_VALUE" | "LAST_VALUE" | "NTH_VALUE" | AggregateName;
+export interface WindowFrameBound {
+    kind: "unbounded-preceding" | "preceding" | "current-row" | "following" | "unbounded-following";
+    offset?: number;
+}
+export type WindowFrameExclusion = "no-others" | "current-row" | "group" | "ties";
+export interface WindowFrame {
+    unit: "rows" | "range" | "groups";
+    start: WindowFrameBound;
+    end: WindowFrameBound;
+    exclude?: WindowFrameExclusion;
+}
+export interface WindowSpec {
+    alias: string;
+    name: WindowFunctionName;
+    partitionAliases: string[];
+    orderAliases: Array<{
+        alias: string;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+    argumentAlias?: string;
+    offset?: number;
+    fallback?: QueryValue;
+    frame?: WindowFrame;
+}
+export interface SelectItem {
+    expression: Expression;
+    alias: string;
+}
+export interface TableSource {
+    table: string;
+    alias: string;
+    derived?: CompiledQuery;
+    union?: {
+        blocks: CompiledQuery[];
+        ops: SetOperator[];
+    };
+    recursive?: RecursiveCte;
+    windowed?: {
+        block: CompiledQuery;
+        windows: WindowSpec[];
+    };
+    columnAliases?: string[];
+    lateral?: true;
+}
+export interface JoinPlan extends TableSource {
+    kind: "inner" | "left" | "semi" | "anti";
+    left: Expression;
+    right: Expression;
+    on?: Expression;
+    full?: boolean;
+    natural?: boolean;
+}
+export type SetOperator = "union" | "union all" | "intersect" | "intersect all" | "except" | "except all";
+export interface RecursiveCte {
+    reference: string;
+    base: CompiledQuery;
+    step: CompiledQuery;
+    all: boolean;
+}
+export type PredicateOperator = ComparisonOperator | `${ComparisonOperator} ANY` | `${ComparisonOperator} ALL` | "IN" | "NOT IN" | "IS NULL" | "IS NOT NULL" | "LIKE" | "NOT LIKE" | "ILIKE" | "NOT ILIKE" | "SIMILAR TO" | "NOT SIMILAR TO" | "IS DISTINCT FROM" | "IS NOT DISTINCT FROM" | "IS TRUE";
+export interface Predicate {
+    left: Expression;
+    operator: PredicateOperator;
+    right: Expression;
+    escape?: string;
+}
+export interface CompiledQuery {
+    sql: string;
+    base: TableSource;
+    joins: JoinPlan[];
+    select: SelectItem[];
+    predicates: Predicate[];
+    groupBy: Expression[];
+    having: Predicate[];
+    orderBy: Array<{
+        expression: Expression;
+        direction: "asc" | "desc";
+        nulls?: "first" | "last";
+    }>;
+    limit?: number;
+    offset?: number;
+    distinctWildcard?: boolean;
+    limitParameter?: number;
+    offsetParameter?: number;
+    /** Optimizer-relocated LIMIT placeholders that still need bind-time numeric/range validation. */
+    limitValidationParameters?: number[];
+    /** Optimizer-relocated OFFSET placeholders that still need bind-time numeric/range validation. */
+    offsetValidationParameters?: number[];
+    limitWithTies?: boolean;
+    parameterCount?: number;
+    usesStatementDatetime?: boolean;
+    usesSequenceCalls?: boolean;
+    usesVolatileFunctions?: boolean;
+}
+/** ORDER BY / LIMIT / OFFSET tail of a select or set operation. */
+export interface SelectTail {
+    orderBy: CompiledQuery["orderBy"];
+    limit?: number;
+    offset?: number;
+    limitParameter?: number;
+    offsetParameter?: number;
+    limitWithTies?: boolean;
+}

package/dist/plan/model.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/types.d.ts

@@ -136,6 +136,11 @@ export type ColumnDefault = {
 } | {
     kind: "autoincrement";
 };
+/** A stored generated-column expression, evaluated from the row on every insert and update. */
+export interface ColumnGenerated {
+    readonly kind: "stored";
+    readonly sql: string;
+}
 export interface TableColumnRecord {
     id: string;
     name: string;
@@ -152,6 +157,8 @@ export interface TableColumnRecord {
     nullable: boolean;
     /** Fills omitted or SQL `DEFAULT` slots at insert time; explicit NULL is never replaced. */
     defaultValue?: ColumnDefault;
+    /** Recomputed from sibling columns on every insert and update; callers cannot assign it. */
+    generatedValue?: ColumnGenerated;
     /**
      * What rows written before this column existed read as, instead of NULL.
      *

package/dist/storage/types.js

@@ -141,6 +141,22 @@ export function validateTableColumns(columns) {
                 ...(column.enumValues === undefined ? {} : { enumValues: column.enumValues }),
             }, column.defaultValue);
         }
+        if (column.generatedValue !== undefined) {
+            const generated = column.generatedValue;
+            if (typeof generated !== "object" ||
+                generated === null ||
+                !("kind" in generated) ||
+                generated.kind !== "stored" ||
+                !("sql" in generated) ||
+                typeof generated.sql !== "string" ||
+                generated.sql.length === 0 ||
+                generated.sql.trim() !== generated.sql) {
+                throw new TypeError(`Generated SQL must be a trimmed non-empty expression: ${column.name}`);
+            }
+            if (column.defaultValue !== undefined || column.backfill !== undefined || column.hidden) {
+                throw new TypeError(`Generated columns cannot have defaults, backfills, or hidden metadata: ${column.name}`);
+            }
+        }
         if (column.backfill !== undefined) {
             const value = column.backfill;
             const validType = column.type === "datetime"

package/dist/transactions/index.d.ts

@@ -195,9 +195,11 @@ export declare class DatabaseTransaction {
     setUniqueKeyChanges(changes: UniqueKeyChanges): void;
     /**
      * Attaches one batch's full-text deltas; applied atomically with the publish. A second
-     * batch for the same table merges per column — postings re-sorted by term (each batch's
-     * reserved row ids are strictly above the last, so rowIds stay ascending within a term)
-     * and token totals summed — so a scope can insert into one FTS table any number of times.
+     * batch for the same table merges per column — postings stay sorted by term and row ID,
+     * duplicate row locators collapse to their greatest term frequency, and token totals are
+     * summed — so a scope can mutate one indexed table any number of times. Secondary indexes
+     * use stable hashed key locators rather than reserved row IDs, so operation order does not
+     * imply locator order.
      */
     setFtsChanges(changes: FtsChanges): void;
     /**

package/dist/transactions/index.js

@@ -712,9 +712,11 @@ export class DatabaseTransaction {
     }
     /**
      * Attaches one batch's full-text deltas; applied atomically with the publish. A second
-     * batch for the same table merges per column — postings re-sorted by term (each batch's
-     * reserved row ids are strictly above the last, so rowIds stay ascending within a term)
-     * and token totals summed — so a scope can insert into one FTS table any number of times.
+     * batch for the same table merges per column — postings stay sorted by term and row ID,
+     * duplicate row locators collapse to their greatest term frequency, and token totals are
+     * summed — so a scope can mutate one indexed table any number of times. Secondary indexes
+     * use stable hashed key locators rather than reserved row IDs, so operation order does not
+     * imply locator order.
      */
     setFtsChanges(changes) {
         this.#assertActive();
@@ -746,6 +748,7 @@ export class DatabaseTransaction {
                 });
                 continue;
             }
+            let duplicateTokens = 0;
             for (const posting of column.postings) {
                 const held = present.postings.get(posting.term);
                 if (held === undefined) {
@@ -756,13 +759,18 @@ export class DatabaseTransaction {
                     });
                 }
                 else {
-                    for (const rowId of posting.rowIds)
-                        held.rowIds.push(rowId);
-                    for (const tf of posting.tf)
-                        held.tf.push(tf);
+                    const merged = mergeFtsPostingRows(held, posting);
+                    duplicateTokens = safeWholeNumberSum([
+                        duplicateTokens,
+                        postingTokenCount(held) + postingTokenCount(posting) - postingTokenCount(merged),
+                    ], "Duplicate posting token count");
+                    present.postings.set(posting.term, merged);
                 }
             }
-            present.totalTokens = tokenTotals.get(column.columnId) ?? present.totalTokens;
+            const totalTokens = tokenTotals.get(column.columnId) ?? present.totalTokens;
+            if (duplicateTokens > totalTokens)
+                throw new Error("Posting token merge is inconsistent");
+            present.totalTokens = totalTokens - duplicateTokens;
         }
     }
     #materializedFtsChanges() {
@@ -1615,6 +1623,48 @@ function safeWholeNumberSum(values, label) {
     }
     return total;
 }
+/** Linear merge of two canonical postings for one term. */
+function mergeFtsPostingRows(left, right) {
+    if (left.term !== right.term)
+        throw new TypeError("Posting terms differ during transaction merge");
+    const rowIds = [];
+    const tf = [];
+    let leftIndex = 0;
+    let rightIndex = 0;
+    const push = (rowId, frequency) => {
+        const previous = rowIds[rowIds.length - 1];
+        if (previous === rowId) {
+            tf[tf.length - 1] = Math.max(tf[tf.length - 1] ?? 1, frequency);
+            return;
+        }
+        rowIds.push(rowId);
+        tf.push(frequency);
+    };
+    while (leftIndex < left.rowIds.length && rightIndex < right.rowIds.length) {
+        const leftRowId = left.rowIds[leftIndex] ?? 0n;
+        const rightRowId = right.rowIds[rightIndex] ?? 0n;
+        if (leftRowId <= rightRowId) {
+            push(leftRowId, left.tf[leftIndex] ?? 1);
+            leftIndex += 1;
+        }
+        if (rightRowId <= leftRowId) {
+            push(rightRowId, right.tf[rightIndex] ?? 1);
+            rightIndex += 1;
+        }
+    }
+    while (leftIndex < left.rowIds.length) {
+        push(left.rowIds[leftIndex] ?? 0n, left.tf[leftIndex] ?? 1);
+        leftIndex += 1;
+    }
+    while (rightIndex < right.rowIds.length) {
+        push(right.rowIds[rightIndex] ?? 0n, right.tf[rightIndex] ?? 1);
+        rightIndex += 1;
+    }
+    return { term: left.term, rowIds, tf };
+}
+function postingTokenCount(posting) {
+    return safeWholeNumberSum(posting.tf, "Posting token count");
+}
 function requiredCompactionJobId(id) {
     if (id === null)
         throw new Error("Compaction source blocks require a compaction job");