@minnowdb/core 0.6.9 → 0.7.0

package/dist/engine/database.js

@@ -15,12 +15,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_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, planContainsFts, planHasNaturalJoins, planHasSourceColumnAliases, planReadsTable, planReadsViews, planReadsBeyondSingleScan, projectResultColumns, queryResultNeedsExternalization, resolveStatementDatetimes, subqueryResolutionSteps, topLevelFtsMatchConjuncts, transparentProjectionSource, unknownColumnDomains, validateDefaultExpression, windowOutputDomain, windowOutputType, } from "./query.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, } 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 } from "./sql-semantics.js";
+import { encodeSqlEqualityValue, parseSqlTimestampText } from "./sql-semantics.js";
 import { exactNumericAsNumber, 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";
@@ -40,8 +40,14 @@ const SEQUENCE_PREFIX = "\u0000minnow_sequence:";
  * shape is not selective enough and handing the scan back to the vectorized executor.
  */
 const MAX_POINT_READ_CANDIDATES = 1_024;
+/** A keyed replay decoding more blocks than this leaves the read to the ordinary path. */
+const MAX_POINT_READ_DELTA_BLOCKS = 256;
 /** Delta-chunk tail length past which a search schedules a fold-by-rebuild of the base. */
 const FTS_FOLD_DELTA_CHUNKS = 16;
+/** Candidate lists wider than this scan their blocks instead of probing for exact rows. */
+const SECONDARY_INDEX_ROW_SELECTION_CAP = 4096;
+/** Candidate results at most this wide are pooled across snapshots by (column, version, terms). */
+const MAX_POOLED_FTS_CANDIDATE_ROW_IDS = 65_536;
 /** Persistent rebuild failure cannot let an accelerator append one durable delta per commit. */
 const FTS_HARD_DELTA_CHUNKS = 64;
 const DEFAULT_COMPACTION_TARGET_BLOCK_BYTES = 2 * 1024 * 1024;
@@ -292,6 +298,66 @@ function isTransactionalStatement(statement) {
         statement.kind === "delete" ||
         statement.kind === "select");
 }
+/**
+ * Evaluates RETURNING expression items over the affected rows (every visible column of the
+ * post-image for INSERT and UPDATE, the pre-image for DELETE) through the row executor, so a
+ * function, arithmetic, or CASE in RETURNING has exactly the semantics it has in a SELECT.
+ */
+function projectReturningItems(table, alias, items, rows, facts) {
+    // The same catalog normalization a SELECT receives, and the same columnar executor: the
+    // affected rows become a one-table input whose values carry the execution form a stored row
+    // reads with, so `amount * 2` over a NUMERIC column is exact arithmetic here as well.
+    const plan = normalizePlanDomainLiterals({
+        sql: "(returning)",
+        base: { table: table.name, alias },
+        joins: [],
+        select: items.map((item) => ({
+            expression: structuredClone(item.expression),
+            alias: item.alias,
+        })),
+        predicates: [],
+        groupBy: [],
+        having: [],
+        orderBy: [],
+    }, facts.domains, facts.types);
+    const visible = visibleTableColumns(table);
+    const columns = new Map(visible.map((column) => [
+        column.name,
+        {
+            type: column.type,
+            values: rows.map((row) => {
+                const value = row[column.name] ?? null;
+                return typeof value === "string" && value.charCodeAt(0) !== 0
+                    ? executionSqlValueFromInput(column, value)
+                    : value;
+            }),
+        },
+    ]));
+    const input = createColumnarTable(table.name, columns);
+    const typedSchemas = new Map([
+        [
+            table.name,
+            visible.map(({ name, type, integer, sqlDomain }) => ({
+                name,
+                type,
+                ...(integer === true ? { integer: true } : {}),
+                ...(sqlDomain === undefined ? {} : { sqlDomain }),
+            })),
+        ],
+    ]);
+    const memory = new QueryMemoryContext(undefined);
+    const prepared = createPreparedColumnarQuery(plan, new Map([[table.name, input]]), memory);
+    try {
+        return {
+            returnedRows: prepared.execute().rows,
+            returnedColumns: items.map((item) => item.alias),
+            returnedColumnDomains: inferResultColumnDomains(plan, typedSchemas),
+        };
+    }
+    finally {
+        prepared.close();
+    }
+}
 function returningExecuteFields(table, columns, rows) {
     return {
         returnedRows: rows,
@@ -328,6 +394,13 @@ function boundInsertValue(value) {
     return value;
 }
 /** Keeps SQL DEFAULT distinct from explicit NULL while pivoting INSERT rows. */
+/** The non-null unique-key values an insert batch proposes, in row order. */
+function insertBatchKeyValues(input, keyColumn) {
+    const values = "columns" in input
+        ? (input.columns[keyColumn] ?? [])
+        : input.map((row) => row[keyColumn] ?? null);
+    return values.filter((value) => value !== null);
+}
 function insertStatementBatch(statement) {
     const columns = {};
     const omitted = {};
@@ -2738,6 +2811,11 @@ export class MinnowDatabase {
     async #prepareCompiledPlan(plan, options = {}, probe) {
         options = this.#effectiveQueryOptions(options);
         throwIfAborted(options.signal);
+        // One statement clock for the whole plan tree, fixed before any nested block executes on
+        // its own: a scalar subquery reading CURRENT_TIMESTAMP is resolved here, not left for the
+        // executor that only ever sees the block it runs.
+        if (plan.usesStatementDatetime === true)
+            plan = resolveStatementDatetimes(plan, this.#now());
         // The ORDER-BY-expression desugar's wrapper is projection-only: prepare the inner block
         // directly (no derived materialization) and project each result to the visible aliases,
         // so `.search()` costs the same whether or not the caller also selects the score.
@@ -3312,6 +3390,9 @@ export class MinnowDatabase {
             // cannot tell a fresh answer from a stale one.
             plan.usesStatementDatetime !== true &&
             plan.usesVolatileFunctions !== true &&
+            // A sequence call advances connection state on every execution; a memo hit would both
+            // repeat the old value and skip the advance.
+            plan.usesSequenceCalls !== true &&
             options.version === undefined &&
             options.executionMemoryBudgetBytes === undefined &&
             options.spillToStorage === undefined &&
@@ -3461,7 +3542,7 @@ export class MinnowDatabase {
         // read has to ask the catalog. It asks by epoch — an O(1) probe the store already serves for
         // result memoization — and only re-reads the view set when the catalog has actually moved.
         // A database with no views therefore pays one probe, not a catalog scan per query.
-        const { views, domains, columns: catalogColumns } = await this.#catalogFacts(probe);
+        const { views, domains, types, columns: catalogColumns } = await this.#catalogFacts(probe);
         let rewritten = plan.usesSequenceCalls === true ? await this.#resolveSequenceCalls(plan) : plan;
         if (views.size > 0 && planReadsViews(plan, (name) => views.has(name))) {
             const bodies = new Map();
@@ -3477,8 +3558,8 @@ export class MinnowDatabase {
                 return compiled;
             });
         }
-        if (domains.size > 0 && planReadsTable(rewritten, (name) => domains.has(name))) {
-            rewritten = normalizePlanDomainLiterals(rewritten, domains);
+        if (planReadsTable(rewritten, (name) => domains.has(name) || types.has(name))) {
+            rewritten = normalizePlanDomainLiterals(rewritten, domains, types);
         }
         const columnsOf = (name) => {
             const columns = catalogColumns.get(name);
@@ -3494,6 +3575,22 @@ export class MinnowDatabase {
         const qualified = qualifyCorrelatedReferences(rewritten, catalogColumns);
         return qualified === rewritten ? rewritten : optimizePlan(qualified);
     }
+    /** Replaces a statement's whole-row RETURNING payload with its expression items. */
+    async #projectReturningItems(statement, result) {
+        if ((statement.kind !== "insert" && statement.kind !== "update" && statement.kind !== "delete") ||
+            statement.returningItems === undefined ||
+            (result.kind !== "insert" && result.kind !== "update" && result.kind !== "delete") ||
+            result.returnedRows === undefined) {
+            return result;
+        }
+        const table = await this.#findTable(statement.table);
+        const alias = statement.kind !== "insert" && statement.alias !== undefined ? statement.alias : table.name;
+        const facts = await this.#catalogFacts();
+        return {
+            ...result,
+            ...projectReturningItems(table, alias, statement.returningItems, result.returnedRows, facts),
+        };
+    }
     /** Resolves connection-local sequence calls before either synchronous executor sees the plan. */
     async #resolveSequenceCalls(plan) {
         const usesSequence = (expression) => (expression.kind === "call" &&
@@ -3514,8 +3611,12 @@ export class MinnowDatabase {
                 throw new TypeError("NEXTVAL and CURRVAL are supported in the SELECT list");
             }
         });
-        if (sequenceExpressions.length === 0)
+        if (sequenceExpressions.length === 0) {
+            if (blockCallsFunctions(plan, sequenceFunctionNames)) {
+                throw new TypeError("NEXTVAL and CURRVAL are supported in the SELECT list of a SELECT without FROM");
+            }
             return plan;
+        }
         if (plan.base.table !== DUAL_TABLE || plan.joins.length > 0) {
             throw new TypeError("NEXTVAL and CURRVAL currently require a SELECT without FROM");
         }
@@ -3599,8 +3700,11 @@ export class MinnowDatabase {
         const childKeys = new Map();
         const domains = new Map();
         const columns = new Map();
+        const types = new Map();
         for (const table of await this.store.listTables()) {
-            columns.set(table.name, table.columns.filter(({ hidden }) => hidden !== true).map(({ name }) => name));
+            const visible = table.columns.filter(({ hidden }) => hidden !== true);
+            columns.set(table.name, visible.map(({ name }) => name));
+            types.set(table.name, new Map(visible.map((column) => [column.name, column.type])));
             const tableDomains = new Map(table.columns.flatMap((column) => column.sqlDomain === undefined ? [] : [[column.name, column.sqlDomain]]));
             if (tableDomains.size > 0)
                 domains.set(table.name, tableDomains);
@@ -3614,7 +3718,7 @@ export class MinnowDatabase {
                     existing.push({ table, key });
             }
         }
-        const facts = { views, childKeys, domains, columns };
+        const facts = { views, childKeys, domains, columns, types };
         this.#catalogCache = { epoch, facts };
         return facts;
     }
@@ -3742,7 +3846,10 @@ export class MinnowDatabase {
         // paths cross the result boundary through the same externalizeQueryResult call, so
         // reporting the column's domain below makes the answers identical by construction.
         const projected = [];
-        for (const item of shape.select) {
+        const selected = shape.select === "*"
+            ? visibleTableColumns(table).map((column) => ({ column: column.name, alias: column.name }))
+            : shape.select;
+        for (const item of selected) {
             const column = columnByName.get(item.column);
             if (column === undefined || column.hidden === true)
                 return undefined;
@@ -3753,7 +3860,17 @@ export class MinnowDatabase {
             const kind = segment.kind;
             return kind !== "insert" && kind !== "base";
         })) {
-            return undefined;
+            // Update and delete deltas are replayed for the one key instead of the whole table: a
+            // scalar key identifies its row in every segment, so the row's history is a handful of
+            // small blocks. A composite (hidden) key keeps the ordinary replay.
+            if (keyColumn.hidden === true ||
+                segments.some((segment) => {
+                    const kind = segment.kind;
+                    return kind !== "insert" && kind !== "base" && kind !== "update" && kind !== "delete";
+                })) {
+                return undefined;
+            }
+            return this.#pointReadThroughDeltas(shape, keyColumn, segments, equalityColumns, projected, snapshot, options);
         }
         // The most selective searchable component wins nothing provable without statistics, so
         // prefer a numeric component (zone-map pruning plus binary search) over a string one
@@ -3904,7 +4021,177 @@ export class MinnowDatabase {
             }
         }
         return {
-            columns: shape.select.map((item) => item.alias),
+            columns: projected.map((item) => item.alias),
+            columnDomains: projected.map((item) => item.column.sqlDomain ?? null),
+            rows,
+        };
+    }
+    /**
+     * The slots of one block's vector holding `target`: a sorted null-free numeric block by run
+     * search, otherwise by scan; a string block through its reverse dictionary. Undefined when
+     * the block cannot be searched for this target.
+     */
+    #keySlotsInBlock(blockId, decoded, column, target) {
+        const vector = this.#blockColumnVector(blockId, decoded);
+        if (vector.kind !== column.type)
+            return undefined;
+        const slots = [];
+        if ((vector.kind === "number" || vector.kind === "datetime") && typeof target === "number") {
+            if (decoded.description.nullCount === 0 && valuesAreAscending(vector.values)) {
+                const run = equalRunRange(vector.values, target);
+                for (let slot = run.begin; slot < run.end; slot += 1)
+                    slots.push(slot);
+            }
+            else {
+                for (let slot = 0; slot < vector.length; slot += 1) {
+                    if (vector.values[slot] === target && vectorValue(vector, slot) !== null) {
+                        slots.push(slot);
+                    }
+                }
+            }
+            return slots;
+        }
+        if (vector.kind === "string" && typeof target === "string") {
+            const code = this.#dictionaryCode(blockId, vector, target);
+            if (code === undefined)
+                return slots;
+            for (let slot = 0; slot < vector.length; slot += 1) {
+                if (vector.codes[slot] === code)
+                    slots.push(slot);
+            }
+            return slots;
+        }
+        if (vector.kind === "boolean" && typeof target === "boolean") {
+            for (let slot = 0; slot < vector.length; slot += 1) {
+                if (vectorValue(vector, slot) === target)
+                    slots.push(slot);
+            }
+            return slots;
+        }
+        return undefined;
+    }
+    /**
+     * A keyed point read over a mutation history: the segments are walked in visible order,
+     * an insert lands the row, a delete unmaps it, and an update patches the columns it carries
+     * — the same last-writer-wins replay the streamed mutation table performs, applied to one
+     * key. The remaining equalities are checked on the row as it stands at the end, since an
+     * update may have changed a filtered column. Falls back when the history is wide enough
+     * that decoding it would not beat the ordinary path.
+     */
+    async #pointReadThroughDeltas(shape, keyColumn, segments, equalityColumns, projected, snapshot, options) {
+        const keyEquality = shape.equalities.find((equality) => equality.column === keyColumn.name);
+        if (keyEquality === undefined)
+            return undefined;
+        const target = keyEquality.value instanceof Date ? dateMilliseconds(keyEquality.value) : keyEquality.value;
+        const neededColumns = [
+            ...new Set([...equalityColumns.values(), ...projected.map((item) => item.column)]),
+        ];
+        let current;
+        let decodedBlocks = 0;
+        for (const segment of segments) {
+            throwIfAborted(options.signal);
+            if (segment.rowCount === 0)
+                continue;
+            const keyBlockIds = segment.columnBlockIds[keyColumn.id] ?? [];
+            if (keyBlockIds.length === 0)
+                return undefined;
+            let blockIndexes = keyBlockIds.map((_, index) => index);
+            if (typeof target === "number" && keyBlockIds.length > 1) {
+                const descriptions = await this.#zoneDescriptions(keyBlockIds, snapshot);
+                blockIndexes = blockIndexes.filter((blockIndex) => {
+                    const zone = descriptions.get(keyBlockIds[blockIndex] ?? "")?.metadata.zoneMap;
+                    return zone === undefined || (zone.min <= target && target <= zone.max);
+                });
+            }
+            if (blockIndexes.length === 0)
+                continue;
+            decodedBlocks += blockIndexes.length;
+            if (decodedBlocks > MAX_POINT_READ_DELTA_BLOCKS)
+                return undefined;
+            const keyBlocks = await this.#decodedBlocksThroughCache(blockIndexes.map((blockIndex) => keyBlockIds[blockIndex] ?? ""), snapshot);
+            for (const [position, blockIndex] of blockIndexes.entries()) {
+                const decoded = keyBlocks[position];
+                if (decoded === undefined)
+                    return undefined;
+                const blockId = keyBlockIds[blockIndex] ?? "";
+                const slots = this.#keySlotsInBlock(blockId, decoded, keyColumn, target);
+                if (slots === undefined)
+                    return undefined;
+                if (slots.length === 0)
+                    continue;
+                if (slots.length > 1)
+                    return undefined;
+                const slot = slots[0] ?? 0;
+                if (segment.kind === "delete") {
+                    current = undefined;
+                    continue;
+                }
+                if (segment.kind === "update" && current === undefined)
+                    continue;
+                const carried = segment.kind === "update"
+                    ? neededColumns.filter((column) => column.id !== keyColumn.id && segment.columnBlockIds[column.id] !== undefined)
+                    : neededColumns.filter((column) => column.id !== keyColumn.id);
+                const blockIds = carried.map((column) => segment.columnBlockIds[column.id]?.[blockIndex]);
+                if (blockIds.some((id) => id === undefined))
+                    return undefined;
+                decodedBlocks += blockIds.length;
+                if (decodedBlocks > MAX_POINT_READ_DELTA_BLOCKS)
+                    return undefined;
+                const blocks = await this.#decodedBlocksThroughCache(blockIds, snapshot);
+                const values = segment.kind === "update" && current !== undefined
+                    ? current
+                    : new Map();
+                if (segment.kind !== "update") {
+                    if (current !== undefined)
+                        return undefined;
+                    values.set(keyColumn.name, vectorValue(this.#blockColumnVector(blockId, decoded), slot));
+                }
+                for (const [index, column] of carried.entries()) {
+                    const block = blocks[index];
+                    const columnBlockId = blockIds[index];
+                    if (block === undefined || columnBlockId === undefined)
+                        return undefined;
+                    if (block.column.rowCount !== decoded.column.rowCount)
+                        return undefined;
+                    const vector = this.#blockColumnVector(columnBlockId, block);
+                    if (vector.kind !== column.type)
+                        return undefined;
+                    values.set(column.name, vectorValue(vector, slot));
+                }
+                current = values;
+            }
+        }
+        const rows = [];
+        if (current !== undefined) {
+            let matches = true;
+            for (const equality of shape.equalities) {
+                const stored = current.get(equality.column);
+                const wanted = equality.value;
+                const equal = wanted instanceof Date
+                    ? stored instanceof Date && dateMilliseconds(stored) === dateMilliseconds(wanted)
+                    : stored === wanted;
+                if (!equal) {
+                    matches = false;
+                    break;
+                }
+            }
+            if (matches) {
+                const row = {};
+                for (const item of projected) {
+                    const value = current.get(item.column.name);
+                    if (value === undefined)
+                        return undefined;
+                    if (typeof value === "string" && value.charCodeAt(0) === 0) {
+                        if (item.column.sqlDomain === undefined || !isSqlDomainValue(value))
+                            return undefined;
+                    }
+                    row[item.alias] = value;
+                }
+                rows.push(row);
+            }
+        }
+        return {
+            columns: projected.map((item) => item.alias),
             columnDomains: projected.map((item) => item.column.sqlDomain ?? null),
             rows,
         };
@@ -6212,8 +6499,12 @@ export class MinnowDatabase {
         else {
             notes.push("materializes inputs at preparation");
         }
-        const table = reported.base.derived ?? reported.base.union ?? reported.base.windowed;
-        if (table === undefined && reported.joins.length === 0) {
+        const table = reported.base.derived ??
+            reported.base.union ??
+            reported.base.windowed ??
+            reported.base.recursive;
+        // A FROM-less query reads the dual row, which has no catalog record to report on.
+        if (table === undefined && reported.joins.length === 0 && reported.base.table !== DUAL_TABLE) {
             const record = await this.#findTable(reported.base.table);
             const pointTemplate = record.view === undefined ? cachedPointReadTemplate(reported) : null;
             if (pointTemplate !== null) {
@@ -6314,9 +6605,9 @@ export class MinnowDatabase {
             if (!isTransactionalStatement(boundStatement)) {
                 throw new TypeError(`${boundStatement.kind.toUpperCase().replace("-", " ")} is not allowed inside a transaction`);
             }
-            return externalizeExecuteResult(await this.#duringTransaction(open, () => open.session.executeStatement(boundStatement)));
+            return externalizeExecuteResult(await this.#projectReturningItems(boundStatement, await this.#duringTransaction(open, () => open.session.executeStatement(boundStatement))));
         }
-        return externalizeExecuteResult(await this.runStatement(bindStatementParameters(statement, params)));
+        return externalizeExecuteResult(await this.#projectReturningItems(statement, await this.runStatement(bindStatementParameters(statement, params))));
     }
     /**
      * E141-04 on the child side: every non-null value written into a referencing column must name
@@ -6942,13 +7233,16 @@ export class MinnowDatabase {
     async #filterConflictingInsertRows(statement, writer) {
         const table = await this.#findTable(statement.table);
         const keyColumn = getUniqueKeyColumn(table);
-        const conflictColumns = statement.onConflict?.columns ??
-            (statement.onConflict === undefined ? [] : [statement.onConflict.column]);
         const addressColumns = keyColumn?.hidden === true
             ? primaryKeyColumns(table).map(({ name }) => name)
             : keyColumn === undefined
                 ? []
                 : [keyColumn.name];
+        // A targetless DO NOTHING means "any unique key", which for a Minnow table is its key.
+        const conflictColumns = statement.onConflict?.anyTarget === true
+            ? addressColumns
+            : (statement.onConflict?.columns ??
+                (statement.onConflict === undefined ? [] : [statement.onConflict.column]));
         if (keyColumn === undefined ||
             conflictColumns.length !== addressColumns.length ||
             conflictColumns.some((name, index) => name !== addressColumns[index])) {
@@ -7008,6 +7302,37 @@ export class MinnowDatabase {
             }),
         };
     }
+    /** Rejects an INSERT staged into a scope whose keys already exist there or in committed rows. */
+    async #assertStagedInsertKeysFree(table, keyColumn, input, writer) {
+        if (keyColumn.hidden === true)
+            return;
+        const keys = insertBatchKeyValues(input, keyColumn.name);
+        if (keys.length === 0)
+            return;
+        const plan = {
+            sql: "(staged insert keys)",
+            base: { table: table.name, alias: table.name },
+            joins: [],
+            select: [{ expression: { kind: "column", reference: keyColumn.name }, alias: "key" }],
+            predicates: [
+                {
+                    left: { kind: "column", reference: keyColumn.name },
+                    operator: "IN",
+                    right: { kind: "list", items: keys.map((value) => ({ kind: "literal", value })) },
+                },
+            ],
+            groupBy: [],
+            having: [],
+            orderBy: [],
+        };
+        const existing = (await writer.queryPlan(plan)).rows[0]?.key;
+        if (typeof existing === "string" ||
+            typeof existing === "number" ||
+            typeof existing === "boolean" ||
+            existing instanceof Date) {
+            throw new UniqueConstraintError(table.name, keyColumn.name, existing);
+        }
+    }
     /**
      * MERGE (F312). One pass over the source, joined to the target on the match condition, decides
      * each row's branch; the branches then apply as ordinary batched writes inside a single write
@@ -7586,10 +7911,14 @@ export class MinnowDatabase {
         if (statement.kind === "insert") {
             statement = await this.#materializeInsertExpressions(statement, statementNow);
         }
-        // A RETURNING clause parsed from SQL text applies unless the caller overrides it.
+        // A RETURNING clause parsed from SQL text applies unless the caller overrides it. Expression
+        // items read every column of the affected rows here; execute() projects them afterwards.
         if (statement.returning !== undefined && options.returning === undefined) {
             options = { ...options, returning: statement.returning };
         }
+        else if (statement.returningItems !== undefined && options.returning === undefined) {
+            options = { ...options, returning: "*" };
+        }
         if (statement.kind === "insert" && statement.onConflict?.action === "nothing") {
             statement = await this.#filterConflictingInsertRows(statement, options.writer);
         }
@@ -7654,6 +7983,20 @@ export class MinnowDatabase {
                 }
             }
             const writer = options.writer;
+            const stagedKeyColumn = writer === undefined ? undefined : getUniqueKeyColumn(table);
+            if (writer !== undefined && !viaUpsert && stagedKeyColumn !== undefined) {
+                // Statement validity first, so an invalid projection reports as itself, not as a
+                // duplicate the invalid statement would also have hit.
+                const assignedGenerated = table.columns.find((column) => column.generatedValue !== undefined && statement.columns.includes(column.name));
+                if (assignedGenerated !== undefined) {
+                    throw new TypeError(`Generated column cannot be assigned: ${assignedGenerated.name}`);
+                }
+                // Inside BEGIN ... COMMIT a duplicate key must fail the INSERT itself, as it does in
+                // PostgreSQL, not surface at COMMIT after the application has moved on. The scope's
+                // read sees committed rows plus everything it staged, so one keyed lookup settles it;
+                // commit still re-validates as the last word.
+                await this.#assertStagedInsertKeysFree(table, stagedKeyColumn, input, writer);
+            }
             // A scope stages and reports rows; a standalone write also publishes a version and any
             // values the engine generated. Both shapes answer here, and the narrow one has less to
             // report rather than something different.
@@ -7723,21 +8066,26 @@ export class MinnowDatabase {
                 }));
             })();
         const referenced = new Set([keyColumn.name, ...(returningColumns ?? [])]);
-        if (statement.kind === "update") {
-            for (const assignment of updateAssignments) {
-                for (const column of expressionColumnNames(assignment.expression)) {
-                    referenced.add(column.split(".").at(-1) ?? column);
-                }
-            }
-        }
+        // Each assignment rides the read as a hidden select item, so a scalar subquery in SET —
+        // correlated or not — resolves through the ordinary query pipeline (decorrelation, one
+        // snapshot for the uncorrelated) instead of a per-row evaluator that cannot run one.
+        const assignmentAlias = (column) => `\u0000set:${column}`;
         const plan = optimizePlan({
             sql: `(${statement.kind})`,
-            base: { table: table.name, alias: table.name },
+            base: { table: table.name, alias: statement.alias ?? table.name },
             joins: [],
-            select: [...referenced].map((name) => ({
-                expression: { kind: "column", reference: name },
-                alias: name,
-            })),
+            select: [
+                ...[...referenced].map((name) => ({
+                    expression: { kind: "column", reference: name },
+                    alias: name,
+                })),
+                ...(statement.kind === "update"
+                    ? updateAssignments.map((assignment) => ({
+                        expression: assignment.expression,
+                        alias: assignmentAlias(assignment.column),
+                    }))
+                    : []),
+            ],
             predicates: statement.predicates,
             groupBy: [],
             having: [],
@@ -7834,7 +8182,7 @@ export class MinnowDatabase {
                 throw new TypeError(`Unknown column: ${assignment.column}`);
             const executionValues = returnedChanges === undefined ? undefined : [];
             changes[assignment.column] = rows.map((row) => {
-                const value = evaluateRowExpression(assignment.expression, table.name, row);
+                const value = row[assignmentAlias(assignment.column)] ?? null;
                 if (typeof value === "number" && !Number.isFinite(value)) {
                     throw new TypeError(`UPDATE assignment produced a non-finite number: ${assignment.column}`);
                 }
@@ -8007,8 +8355,11 @@ export class MinnowDatabase {
             throwIfAborted(options.signal);
             const baseSegments = indexed.segments;
             // Zone-map elimination composes after index pruning: whole row groups whose statistics
-            // reject the plan's predicates never stream at all.
-            const zonePruned = await this.#zonePrunedStreamSegments(plan, freshBaseTable, projectedBaseColumns, baseSegments, snapshot);
+            // reject the plan's predicates never stream at all. An exact index row selection is
+            // numbered over the pruned blocks, so it is used as is.
+            const zonePruned = indexed.rows === undefined
+                ? await this.#zonePrunedStreamSegments(plan, freshBaseTable, projectedBaseColumns, baseSegments, snapshot)
+                : undefined;
             throwIfAborted(options.signal);
             const baseView = this.#streamedViewFactory(baseTable, projectedBaseColumns, zonePruned?.segments ?? baseSegments, snapshot, zonePruned?.storedBlocks, zonePruned !== undefined || indexed.pruned);
             if (baseView === undefined)
@@ -8049,7 +8400,7 @@ export class MinnowDatabase {
                         if (table.name === baseTable.name)
                             continue;
                         const requestedColumns = columns.get(table.name) ?? [];
-                        inputTables.set(table.name, await this.#materializeColumnarTableAtSnapshot(table, snapshot, requestedColumns.length === 0 ? [] : resolveReadColumns(table, requestedColumns), visibility));
+                        inputTables.set(table.name, await this.#materializeColumnarTableAtSnapshot(table, snapshot, requestedColumns.length === 0 ? [] : resolveReadColumns(table, requestedColumns), visibility, plan));
                         throwIfAborted(options.signal);
                     }
                     prepared = createPreparedColumnarQuery(plan, inputTables, memory, {
@@ -8093,6 +8444,9 @@ export class MinnowDatabase {
                         try {
                             const streamedResult = await prepared.executeAsync({
                                 loadScanWindow: streamed.load,
+                                ...(indexed.rows === undefined
+                                    ? {}
+                                    : { scanRows: streamed.remapScanRows?.(indexed.rows) ?? indexed.rows }),
                                 ...(options.signal === undefined ? {} : { signal: options.signal }),
                             });
                             options.onStats?.({ peakMemoryBytes: memory.usage.peakBytes });
@@ -8108,6 +8462,9 @@ export class MinnowDatabase {
                         ...(spillPageRows === undefined ? {} : { spillPageRows }),
                         spillStore: this.#leasedSpillStore(),
                         loadScanWindow: streamed.load,
+                        ...(indexed.rows === undefined
+                            ? {}
+                            : { scanRows: streamed.remapScanRows?.(indexed.rows) ?? indexed.rows }),
                         ...(options.signal === undefined ? {} : { signal: options.signal }),
                     });
                     options.onStats?.({ peakMemoryBytes: memory.usage.peakBytes });
@@ -8466,6 +8823,33 @@ export class MinnowDatabase {
      * dictionary objects that stay identical across queries, which keeps per-dictionary
      * expression caches (equality codes, LIKE match sets) hot between statements.
      */
+    /**
+     * Secondary-index key locators for one block's key column, mapped to the block rows that
+     * carry them, pooled by block id. A locator is a hash, so two keys may share one; the scan's
+     * own predicate settles such collisions.
+     */
+    #blockKeyLocators(blockId, vector, type) {
+        const cached = this.#cacheGet(`dkl ${blockId}`);
+        if (cached !== undefined)
+            return cached;
+        const locators = new Map();
+        for (let row = 0; row < vector.length; row += 1) {
+            const value = vectorValue(vector, row);
+            if (value === null)
+                continue;
+            const locator = secondaryKeyLocator(type, value);
+            const existing = locators.get(locator);
+            if (existing === undefined)
+                locators.set(locator, row);
+            else if (typeof existing === "number")
+                locators.set(locator, [existing, row]);
+            else
+                existing.push(row);
+        }
+        // A Map entry for a small bigint and a row number: key, value, hash slot, chain pointer.
+        this.#cachePut(`dkl ${blockId}`, locators, 64 + locators.size * 48);
+        return locators;
+    }
     #blockColumnVector(blockId, decoded) {
         const cached = this.#cacheGet(`dbv ${blockId}`);
         if (cached !== undefined)
@@ -8757,6 +9141,26 @@ export class MinnowDatabase {
             cursorBase = baseEnd;
             return start + liveRows;
         };
+        // Index-selected rows are numbered over the base scan; the replay removes dead rows, so a
+        // selected row's output position is its base position less the dead rows before it, and a
+        // dead selected row is not visited at all.
+        const remapScanRows = (rows) => {
+            const remapped = [];
+            let removedBefore = 0;
+            let scanned = 0;
+            for (const row of rows) {
+                if (row >= baseRows)
+                    break;
+                for (; scanned < row; scanned += 1) {
+                    if (((dead[scanned >>> 3] ?? 0) & (1 << (scanned & 7))) !== 0)
+                        removedBefore += 1;
+                }
+                if (((dead[row >>> 3] ?? 0) & (1 << (row & 7))) !== 0)
+                    continue;
+                remapped.push(row - removedBefore);
+            }
+            return remapped;
+        };
         return {
             table: {
                 name: table.name,
@@ -8764,6 +9168,7 @@ export class MinnowDatabase {
                 columns: new Map(states.map((state) => [state.column.name, state.vector])),
             },
             load,
+            remapScanRows,
         };
     }
     /**
@@ -9108,6 +9513,10 @@ export class MinnowDatabase {
             return undefined;
         if (!this.#artifactCache.enabled)
             return undefined;
+        // A block whose value is not a function of the data — RANDOM(), a sequence call, an
+        // unresolved clock — must run every time; the version key cannot tell its answers apart.
+        if (blockCallsFunctions(block, nonDeterministicFunctionNames))
+            return undefined;
         // Staged writes can change repeatedly without changing either the pinned manifest version or
         // their transaction id. Do not cache them under an identity that could become stale.
         if (visibility.overlayTransactionId !== undefined)
@@ -13235,11 +13644,29 @@ export class MinnowDatabase {
         const cached = memo.get(key);
         if (cached !== undefined)
             return cached;
+        // The result is a function of the postings at one version, so it is also pooled across
+        // snapshots: a repeated point lookup then skips the chunk read and validation entirely.
+        const pooled = this.#cacheGet(`ftc\0${key}`);
+        if (pooled !== undefined)
+            return Promise.resolve(pooled);
         // Shared leases live across queries at one version; results are version-deterministic, but
         // candidate arrays can be large, so the memo sheds wholesale rather than growing unbounded.
         if (memo.size >= 1)
             memo.clear();
-        const read = this.store.readFtsCandidates(tableId, columnId, terms, upToVersion, MAX_FTS_CANDIDATE_ROW_IDS);
+        const read = this.store
+            .readFtsCandidates(tableId, columnId, terms, upToVersion, MAX_FTS_CANDIDATE_ROW_IDS)
+            .then((result) => {
+            const rowIds = result.rowIdsByTerm.reduce((total, ids) => total + ids.length, 0);
+            // Only a complete answer is pooled: a missing base or a build past the asked version
+            // is transient state the next read must observe again, not a fact about the version.
+            if (result.hasBase &&
+                !result.overflow &&
+                result.coversVersion <= upToVersion &&
+                rowIds <= MAX_POOLED_FTS_CANDIDATE_ROW_IDS) {
+                this.#cachePut(`ftc\0${key}`, result, 128 + key.length * 2 + rowIds * 16);
+            }
+            return result;
+        });
         memo.set(key, read);
         return read;
     }
@@ -13440,6 +13867,23 @@ export class MinnowDatabase {
         if (candidates === undefined)
             return { segments, pruned: false };
         const candidateSet = keyColumn === undefined ? undefined : new Set(candidates);
+        // With a key column and only appended segments, the block locator maps give the exact scan
+        // rows, in the streamed scan's numbering over the kept blocks: an equality lookup then
+        // visits a handful of rows instead of every block that holds one. Mutation segments replay
+        // keys and renumber rows, so they keep block-level pruning. A very wide candidate list is
+        // cheaper to scan than to probe.
+        // Positions count the scan segments' kept rows only; update and delete deltas are replayed
+        // over that numbering by the streamed mutation table, which remaps the selection past the
+        // rows the deltas removed.
+        const rowPositions = keyColumn !== undefined &&
+            candidates.length <= SECONDARY_INDEX_ROW_SELECTION_CAP &&
+            segments.every((segment) => segment.kind === "insert" ||
+                segment.kind === "base" ||
+                segment.kind === "update" ||
+                segment.kind === "delete")
+            ? []
+            : undefined;
+        let selectedRowStart = 0;
         const selected = [];
         for (const segment of segments) {
             const anchorColumn = keyColumn ?? table.columns[0];
@@ -13473,15 +13917,43 @@ export class MinnowDatabase {
                     if (block.column.type !== keyColumn.type) {
                         return { segments, pruned: false };
                     }
-                    const vector = this.#blockColumnVector(anchorIds[blockIndex] ?? "", block);
-                    let matches = false;
-                    for (let row = 0; row < vector.length && !matches; row += 1) {
-                        const value = vectorValue(vector, row);
-                        if (value !== null && candidateSet?.has(secondaryKeyLocator(keyColumn.type, value))) {
-                            matches = true;
+                    const blockId = anchorIds[blockIndex] ?? "";
+                    const vector = this.#blockColumnVector(blockId, block);
+                    // A block's key locators are a pure function of its immutable bytes, so they are
+                    // hashed once and pooled; a lookup then probes the (few) candidates against the
+                    // block's set instead of re-hashing every stored key on every query. A candidate
+                    // list wider than the block walks the block's locators against the candidate set.
+                    const locators = this.#blockKeyLocators(blockId, vector, keyColumn.type);
+                    const positions = [];
+                    const collect = (hit) => {
+                        if (hit === undefined)
+                            return false;
+                        if (typeof hit === "number")
+                            positions.push(hit);
+                        else
+                            positions.push(...hit);
+                        return rowPositions === undefined;
+                    };
+                    if (candidates.length <= locators.size) {
+                        for (const candidate of candidates)
+                            if (collect(locators.get(candidate)))
+                                break;
+                    }
+                    else if (candidateSet !== undefined) {
+                        for (const [locator, hit] of locators) {
+                            if (candidateSet.has(locator) && collect(hit))
+                                break;
                         }
                     }
-                    if (matches) {
+                    if (positions.length > 0) {
+                        if (rowPositions !== undefined &&
+                            (segment.kind === "insert" || segment.kind === "base")) {
+                            positions.sort((a, b) => a - b);
+                            const keptRows = rowCounts.reduce((total, count) => total + count, 0);
+                            for (const position of positions) {
+                                rowPositions.push(selectedRowStart + keptRows + position);
+                            }
+                        }
                         blockIndexes.push(blockIndex);
                         rowCounts.push(vector.length);
                     }
@@ -13492,16 +13964,21 @@ export class MinnowDatabase {
                 return { segments, pruned: false };
             if (blockIndexes.length === 0)
                 continue;
+            const keptRowCount = rowCounts.reduce((total, count) => total + count, 0);
+            if (segment.kind === "insert" || segment.kind === "base")
+                selectedRowStart += keptRowCount;
             selected.push({
                 ...segment,
-                rowCount: rowCounts.reduce((total, count) => total + count, 0),
+                rowCount: keptRowCount,
                 columnBlockIds: Object.fromEntries(Object.entries(segment.columnBlockIds).map(([columnId, ids]) => [
                     columnId,
                     blockIndexes.map((blockIndex) => ids[blockIndex] ?? ""),
                 ])),
             });
         }
-        return { segments: selected, pruned: true };
+        return rowPositions === undefined
+            ? { segments: selected, pruned: true }
+            : { segments: selected, pruned: true, rows: rowPositions };
     }
     #scheduleSecondaryIndexBuild(table, indexId) {
         if (this.#closed)
@@ -13687,6 +14164,21 @@ export class MinnowDatabase {
             const projectedKey = keyColumn !== undefined && projectedColumns.some((column) => column.id === keyColumn.id)
                 ? keyColumn.name
                 : undefined;
+            // An exact row selection materializes just those rows: a join side narrowed to a handful
+            // of rows is then a handful of rows, not a table's worth of decoded columns. The rows
+            // come from a secondary index, or from the unique key itself when the plan pins it to
+            // literals (zone maps and sorted-run search locate them without an index).
+            if (keyColumn !== undefined) {
+                const rows = indexed.rows ??
+                    (plan === undefined
+                        ? undefined
+                        : await this.#uniqueKeyRowSelection(table, keyColumn, segments, plan, snapshot));
+                if (rows !== undefined) {
+                    const selected = await this.#materializeSelectedRows(table, keyColumn, projectedColumns, segments, rows, snapshot, projectedKey);
+                    if (selected !== undefined)
+                        return selected;
+                }
+            }
             // Zone-map pruning shrinks the scan the same way index pruning does, so a scoring plan
             // whose statistics come from the scan (no index serving it) must see the whole corpus.
             const zonePruningAllowed = plan === undefined ||
@@ -14317,7 +14809,170 @@ export class MinnowDatabase {
             return decoded;
         });
     }
+    /**
+     * Scan positions of the rows whose unique key the plan pins to literals (`alias.key = 4`,
+     * `alias.key IN (...)`), over append-only segments: zone maps skip blocks a numeric key
+     * cannot be in, a sorted block is searched by run, and a string key goes through the block
+     * dictionary. Undefined when the plan does not pin the key or a block cannot be searched.
+     */
+    async #uniqueKeyRowSelection(table, keyColumn, segments, plan, snapshot) {
+        const members = uniqueKeyMembers(plan, table, keyColumn);
+        if (members === undefined || members.length > SECONDARY_INDEX_ROW_SELECTION_CAP) {
+            return undefined;
+        }
+        const targets = new Set(members.map((value) => (value instanceof Date ? dateMilliseconds(value) : value)));
+        const numericTargets = [...targets].filter((value) => typeof value === "number");
+        const rows = [];
+        let rowStart = 0;
+        for (const segment of segments) {
+            const segmentStart = rowStart;
+            const blockIds = segment.columnBlockIds[keyColumn.id] ?? [];
+            if (blockIds.length === 0 && segment.rowCount > 0)
+                return undefined;
+            if (Object.values(segment.columnBlockIds).some((ids) => ids.length !== blockIds.length)) {
+                return undefined;
+            }
+            const descriptions = keyColumn.type === "number" || keyColumn.type === "datetime"
+                ? await this.#zoneDescriptions(blockIds, snapshot)
+                : undefined;
+            for (const blockId of blockIds) {
+                const description = descriptions?.get(blockId);
+                const zone = description?.metadata.zoneMap;
+                if (description !== undefined && zone !== undefined) {
+                    if (!numericTargets.some((target) => zone.min <= target && target <= zone.max)) {
+                        rowStart += description.rowCount;
+                        continue;
+                    }
+                }
+                const [decoded] = await this.#decodedBlocksThroughCache([blockId], snapshot);
+                if (decoded === undefined)
+                    return undefined;
+                const vector = this.#blockColumnVector(blockId, decoded);
+                if (vector.kind !== keyColumn.type)
+                    return undefined;
+                const found = [];
+                if (vector.kind === "number" || vector.kind === "datetime") {
+                    if (decoded.description.nullCount === 0 && valuesAreAscending(vector.values)) {
+                        for (const target of numericTargets) {
+                            const run = equalRunRange(vector.values, target);
+                            for (let slot = run.begin; slot < run.end; slot += 1)
+                                found.push(slot);
+                        }
+                    }
+                    else {
+                        for (let slot = 0; slot < vector.length; slot += 1) {
+                            const value = vector.values[slot] ?? 0;
+                            if (targets.has(value) && vectorValue(vector, slot) !== null)
+                                found.push(slot);
+                        }
+                    }
+                }
+                else if (vector.kind === "string") {
+                    const codes = new Set();
+                    for (const target of targets) {
+                        if (typeof target !== "string")
+                            continue;
+                        const code = this.#dictionaryCode(blockId, vector, target);
+                        if (code !== undefined)
+                            codes.add(code);
+                    }
+                    if (codes.size > 0) {
+                        for (let slot = 0; slot < vector.length; slot += 1) {
+                            const code = vector.codes[slot];
+                            if (code !== undefined && codes.has(code))
+                                found.push(slot);
+                        }
+                    }
+                }
+                else {
+                    for (let slot = 0; slot < vector.length; slot += 1) {
+                        if (targets.has(vectorValue(vector, slot)))
+                            found.push(slot);
+                    }
+                }
+                found.sort((a, b) => a - b);
+                for (const slot of found)
+                    rows.push(rowStart + slot);
+                rowStart += vector.length;
+            }
+            if (rowStart - segmentStart !== segment.rowCount)
+                return undefined;
+        }
+        return rows;
+    }
+    /**
+     * Materializes the rows at ascending scan positions over append-only segments, reading only
+     * the blocks that hold a selected row. Undefined when the block layout does not line up,
+     * which sends the caller to the whole-segment path.
+     */
+    async #materializeSelectedRows(table, keyColumn, projectedColumns, segments, rows, snapshot, projectedKey) {
+        const values = projectedColumns.map(() => []);
+        let cursor = 0;
+        let rowStart = 0;
+        for (const segment of segments) {
+            const anchorIds = segment.columnBlockIds[keyColumn.id] ?? [];
+            const anchorBlocks = await this.#decodedBlocksThroughCache(anchorIds, snapshot);
+            for (let blockIndex = 0; blockIndex < anchorIds.length; blockIndex += 1) {
+                const count = anchorBlocks[blockIndex]?.column.rowCount ?? 0;
+                const end = rowStart + count;
+                const local = [];
+                while (cursor < rows.length && (rows[cursor] ?? Number.POSITIVE_INFINITY) < end) {
+                    local.push((rows[cursor] ?? 0) - rowStart);
+                    cursor += 1;
+                }
+                rowStart = end;
+                if (local.length === 0)
+                    continue;
+                const blockIds = projectedColumns.map((column) => segment.columnBlockIds[column.id]?.[blockIndex]);
+                if (blockIds.some((id) => id === undefined))
+                    return undefined;
+                const decoded = await this.#decodedBlocksThroughCache(blockIds, snapshot);
+                for (let index = 0; index < projectedColumns.length; index += 1) {
+                    const column = projectedColumns[index];
+                    const block = decoded[index];
+                    const blockId = blockIds[index];
+                    if (column === undefined || block === undefined || blockId === undefined)
+                        return undefined;
+                    if (block.column.rowCount !== count || block.column.type !== column.type)
+                        return undefined;
+                    const vector = plainTextExecutionVector(column, this.#blockColumnVector(blockId, block));
+                    const output = values[index];
+                    if (output === undefined)
+                        return undefined;
+                    for (const row of local)
+                        output.push(vectorValue(vector, row));
+                }
+            }
+        }
+        if (cursor !== rows.length)
+            return undefined;
+        return createColumnarTable(table.name, new Map(projectedColumns.map((column, index) => [
+            column.name,
+            { type: column.type, values: values[index] ?? [] },
+        ])), projectedKey);
+    }
+    /**
+     * A whole-segment column vector is a pure function of its immutable blocks, so the plain
+     * shape (no caller-supplied bytes or row expectations) is pooled by segment list: a
+     * dimension table joined on every query is then decoded once, not per query.
+     */
     async #materializeAppendColumnVector(column, segments, snapshot, rowCount, storedBlocks, expectedRows) {
+        const poolable = storedBlocks === undefined && expectedRows === undefined;
+        const key = poolable
+            ? `mav\0${column.id}\0${String(rowCount)}\0${segments.map((segment) => segment.id).join("\0")}`
+            : undefined;
+        if (key !== undefined) {
+            const cached = this.#cacheGet(key);
+            if (cached !== undefined)
+                return cached;
+        }
+        const vector = await this.#buildAppendColumnVector(column, segments, snapshot, rowCount, storedBlocks, expectedRows);
+        if (key !== undefined && key.length <= MAX_CACHEABLE_TEXT_CHARACTERS) {
+            this.#cachePut(key, vector, 128 + columnVectorPayloadBytes(vector));
+        }
+        return vector;
+    }
+    async #buildAppendColumnVector(column, segments, snapshot, rowCount, storedBlocks, expectedRows) {
         const validity = new Uint8Array(Math.ceil(rowCount / 8));
         const values = column.type === "boolean"
             ? new Uint8Array(rowCount)
@@ -16146,10 +16801,42 @@ function normalizeDomainUpdate(table, input) {
         : input.keys.map((value) => normalizeColumnLogicalValue(key, value));
     return changed || keys !== input.keys ? { keys, changes } : input;
 }
-/** Coerces literals and bound parameters opposite a domain column before planning/index probes. */
-function normalizePlanDomainLiterals(input, domains) {
-    const plan = structuredClone(input);
+/**
+ * Coerces literals and bound parameters opposite a domain column before planning/index probes,
+ * and reads an untyped string constant beside a datetime, number, or boolean column in that
+ * column's type — `joined >= '2026-01-01'`, `id = '5'`, `active = 't'` — the way PostgreSQL
+ * types an unknown-typed literal by its context. Text that does not parse is left alone and
+ * fails at comparison time as a type mismatch. Coercing here, rather than only at comparison,
+ * keeps the typed kernels, zone-map pruning, and the keyed point read on the fast paths.
+ */
+function normalizePlanDomainLiterals(input, domains, types = new Map()) {
+    // Most plans have nothing to coerce. A probing pass over the shared (cached) plan finds out
+    // without touching it; only a plan that needs a rewrite is cloned and rewritten, so the
+    // per-query cost of a plan that compares typed columns to typed literals is one walk, not a
+    // structured clone.
+    const pass = { probing: true, needed: false };
+    const coerceText = (type, text) => {
+        if (type === "datetime")
+            return parseSqlTimestampText(text);
+        if (type === "number") {
+            const trimmed = text.trim();
+            if (trimmed === "")
+                return undefined;
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        }
+        if (type === "boolean") {
+            const lowered = text.trim().toLowerCase();
+            if (lowered === "t" || lowered === "true" || lowered === "1")
+                return true;
+            if (lowered === "f" || lowered === "false" || lowered === "0")
+                return false;
+        }
+        return undefined;
+    };
     const rewriteBlock = (block) => {
+        if (pass.probing && pass.needed)
+            return;
         for (const source of [block.base, ...block.joins]) {
             if (source.derived !== undefined)
                 rewriteBlock(source.derived);
@@ -16162,27 +16849,55 @@ function normalizePlanDomainLiterals(input, domains) {
             }
         }
         const sources = [block.base, ...block.joins];
-        const domainFor = (reference) => {
+        const lookup = (reference, catalog) => {
             const separator = reference.indexOf(".");
             if (separator !== -1) {
                 const alias = reference.slice(0, separator);
                 const name = reference.slice(separator + 1);
                 const source = sources.find((candidate) => candidate.alias === alias);
-                return source === undefined ? undefined : domains.get(source.table)?.get(name);
+                return source === undefined ? undefined : catalog.get(source.table)?.get(name);
             }
             const matches = sources.flatMap((source) => {
-                const domain = domains.get(source.table)?.get(reference);
-                return domain === undefined ? [] : [domain];
+                const found = catalog.get(source.table)?.get(reference);
+                return found === undefined ? [] : [found];
             });
             return matches.length === 1 ? matches[0] : undefined;
         };
+        const domainFor = (reference) => lookup(reference, domains);
+        const coerceTyped = (column, value) => {
+            if (column.kind !== "column")
+                return;
+            const type = lookup(column.reference, types);
+            if (type === undefined || type === "string")
+                return;
+            const literals = value.kind === "literal" ? [value] : value.kind === "list" ? value.items : [];
+            for (const literal of literals) {
+                if (literal.kind !== "literal" || typeof literal.value !== "string")
+                    continue;
+                if (literal.internalSqlValue === true)
+                    continue;
+                const coerced = coerceText(type, literal.value);
+                if (coerced === undefined)
+                    continue;
+                if (pass.probing)
+                    pass.needed = true;
+                else
+                    literal.value = coerced;
+            }
+        };
         const coercePair = (column, value) => {
             if (column.kind !== "column")
                 return;
             const domain = domainFor(column.reference);
-            if (domain === undefined)
+            if (domain === undefined) {
+                coerceTyped(column, value);
                 return;
+            }
             if (value.kind === "literal") {
+                if (pass.probing) {
+                    pass.needed = true;
+                    return;
+                }
                 value.value = normalizeSqlDomainValue(domain, value.value);
                 value.internalSqlValue = true;
                 value.sqlDomain = domain;
@@ -16190,6 +16905,10 @@ function normalizePlanDomainLiterals(input, domains) {
             else if (value.kind === "list") {
                 for (const item of value.items) {
                     if (item.kind === "literal") {
+                        if (pass.probing) {
+                            pass.needed = true;
+                            return;
+                        }
                         item.value = normalizeSqlDomainValue(domain, item.value);
                         item.internalSqlValue = true;
                         item.sqlDomain = domain;
@@ -16265,6 +16984,11 @@ function normalizePlanDomainLiterals(input, domains) {
         for (const order of block.orderBy)
             order.expression = rewrite(order.expression);
     };
+    rewriteBlock(input);
+    if (!pass.needed)
+        return input;
+    pass.probing = false;
+    const plan = structuredClone(input);
     rewriteBlock(plan);
     return plan;
 }
@@ -16665,6 +17389,19 @@ function createStreamedColumnVector(type, length) {
  * deliberately keep their tags; ordinary TEXT only copies the rare dictionary that collides
  * with that namespace, preserving the cached zero-copy vector for every normal dictionary.
  */
+/** Bytes a materialized vector retains, for the buffer pool's accounting. */
+function columnVectorPayloadBytes(vector) {
+    let total = vector.validity.byteLength;
+    if (vector.kind === "string") {
+        total += vector.codes.byteLength;
+        for (const value of vector.dictionary)
+            total += 16 + value.length * 2;
+    }
+    else {
+        total += vector.values.byteLength;
+    }
+    return total;
+}
 function plainTextExecutionVector(column, vector) {
     if (column.type !== "string" ||
         column.sqlDomain !== undefined ||
@@ -17463,13 +18200,23 @@ function zonePredicates(plan, table) {
 }
 /** Top-level scalar predicates a ready index can answer through a leftmost key prefix. */
 function secondaryIndexPredicates(plan, table) {
-    if (plan.joins.length > 0 || plan.base.table !== table.name)
+    // The table may be the base or one join source; a self-join names it twice, and a
+    // predicate on one alias says nothing about the other, so that shape gets no index.
+    const sources = [plan.base, ...plan.joins].filter((source) => source.table === table.name);
+    const source = sources[0];
+    if (source === undefined || sources.length !== 1)
         return [];
+    // In a join, an unqualified reference is resolved at execution against every source, so only
+    // a reference qualified by this source's alias (or the table name) can be claimed for its
+    // index.
+    const joined = plan.joins.length > 0;
     const resolveColumn = (reference) => {
         const parts = reference.split(".");
-        if (parts.length === 2 && parts[0] !== plan.base.alias && parts[0] !== table.name) {
+        if (parts.length === 2 && parts[0] !== source.alias && parts[0] !== table.name) {
             return undefined;
         }
+        if (parts.length !== 2 && joined)
+            return undefined;
         const name = parts.length === 2 ? parts[1] : parts[0];
         return table.columns.find((candidate) => candidate.name === name);
     };
@@ -17728,6 +18475,118 @@ function firstMemberAtLeast(members, value) {
     }
     return low;
 }
+const sequenceFunctionNames = new Set(["NEXTVAL", "CURRVAL"]);
+const nonDeterministicFunctionNames = new Set([
+    ...volatileScalarFunctionNames,
+    ...sequenceFunctionNames,
+    "CURRENT_DATE",
+    "CURRENT_TIMESTAMP",
+    "CURRENT_TIME",
+    "LOCALTIME",
+    "LOCALTIMESTAMP",
+    "NOW",
+]);
+/** Whether any expression of a block, or of a block nested anywhere under it, calls a name. */
+function blockCallsFunctions(block, names) {
+    const state = { found: false };
+    const visit = (expression) => {
+        if (state.found)
+            return;
+        if (expression.kind === "call" && names.has(expression.name)) {
+            state.found = true;
+            return;
+        }
+        if (expression.kind === "subquery" || expression.kind === "exists") {
+            if (blockCallsFunctions(expression.block, names))
+                state.found = true;
+            return;
+        }
+        childExpressions(expression).forEach(visit);
+    };
+    forEachBlockExpression(block, visit);
+    forEachNestedBlock(block, (nested) => {
+        if (!state.found && blockCallsFunctions(nested, names))
+            state.found = true;
+    });
+    return state.found;
+}
+/**
+ * The literal values a plan's conjunctive predicates pin one table's unique key to, through
+ * `alias.key = literal` and `alias.key IN (literals)`; undefined when the key is unconstrained.
+ * References are resolved with the same alias rules as secondary-index predicates.
+ */
+function uniqueKeyMembers(plan, table, keyColumn) {
+    const sources = [plan.base, ...plan.joins].filter((source) => source.table === table.name);
+    const source = sources[0];
+    if (source === undefined || sources.length !== 1)
+        return undefined;
+    const joined = plan.joins.length > 0;
+    const isKey = (expression) => {
+        if (expression.kind !== "column")
+            return false;
+        const parts = expression.reference.split(".");
+        if (parts.length === 2) {
+            return (parts[0] === source.alias || parts[0] === table.name) && parts[1] === keyColumn.name;
+        }
+        return !joined && parts[0] === keyColumn.name;
+    };
+    const literal = (expression) => {
+        if (expression.kind !== "literal" || expression.value === null)
+            return undefined;
+        let value = expression.value;
+        if (keyColumn.type === "datetime" && isDateDomainValue(value)) {
+            const datetime = normalizedDatetimeLiteral(value);
+            if (datetime === undefined)
+                return undefined;
+            value = datetime;
+        }
+        if (keyColumn.type === "datetime" && !(value instanceof Date))
+            return undefined;
+        if (keyColumn.type === "number" && typeof value !== "number")
+            return undefined;
+        if (keyColumn.type === "string" && typeof value !== "string")
+            return undefined;
+        if (keyColumn.type === "boolean" && typeof value !== "boolean")
+            return undefined;
+        return value;
+    };
+    let members;
+    for (const predicate of plan.predicates) {
+        let found;
+        if (predicate.operator === "=") {
+            const value = isKey(predicate.left)
+                ? literal(predicate.right)
+                : isKey(predicate.right)
+                    ? literal(predicate.left)
+                    : undefined;
+            if (value !== undefined)
+                found = [value];
+        }
+        else if (predicate.operator === "IN" &&
+            isKey(predicate.left) &&
+            predicate.right.kind === "list") {
+            const values = [];
+            for (const item of predicate.right.items) {
+                const value = literal(item);
+                if (value === undefined) {
+                    if (item.kind === "literal" && item.value === null)
+                        continue;
+                    values.length = 0;
+                    break;
+                }
+                values.push(value);
+            }
+            if (values.length > 0)
+                found = values;
+        }
+        if (found === undefined)
+            continue;
+        // Two constraints on the key intersect; the narrower one is enough for a superset.
+        if (members === undefined || found.length < members.length)
+            members = found;
+    }
+    return members;
+}
 function reverseComparison(operator) {
     if (operator === ">")
         return "<";