@minnowdb/core 0.6.1 → 0.6.2

package/dist/engine/artifact-cache.d.ts

@@ -10,6 +10,11 @@ export interface ArtifactCacheStats {
 /**
  * Byte-bounded LRU for decoded blocks, vectors, derived results, and memoized query results.
  * Payloads are immutable by convention; callers own the byte estimates for their artifact type.
+ *
+ * Recency lives on an intrusive doubly-linked list rather than Map insertion order: a hit
+ * relinks four pointers instead of deleting and re-inserting the key, which re-hashed the
+ * long block-identity keys twice per touch and was the single hottest frame of a cached point
+ * lookup.
  */
 export declare class ArtifactCache {
     #private;

package/dist/engine/artifact-cache.js

@@ -1,10 +1,19 @@
 /**
  * Byte-bounded LRU for decoded blocks, vectors, derived results, and memoized query results.
  * Payloads are immutable by convention; callers own the byte estimates for their artifact type.
+ *
+ * Recency lives on an intrusive doubly-linked list rather than Map insertion order: a hit
+ * relinks four pointers instead of deleting and re-inserting the key, which re-hashed the
+ * long block-identity keys twice per touch and was the single hottest frame of a cached point
+ * lookup.
  */
 export class ArtifactCache {
     #limitBytes;
     #entries = new Map();
+    /** Least recently used end of the recency list. */
+    #oldest;
+    /** Most recently used end of the recency list. */
+    #newest;
     #usedBytes = 0;
     #hits = 0;
     #misses = 0;
@@ -18,6 +27,26 @@ export class ArtifactCache {
     get enabled() {
         return this.#limitBytes > 0;
     }
+    #unlink(entry) {
+        if (entry.previous !== undefined)
+            entry.previous.next = entry.next;
+        else
+            this.#oldest = entry.next;
+        if (entry.next !== undefined)
+            entry.next.previous = entry.previous;
+        else
+            this.#newest = entry.previous;
+        entry.previous = undefined;
+        entry.next = undefined;
+    }
+    #appendNewest(entry) {
+        entry.previous = this.#newest;
+        entry.next = undefined;
+        if (this.#newest !== undefined)
+            this.#newest.next = entry;
+        this.#newest = entry;
+        this.#oldest ??= entry;
+    }
     get(key) {
         if (!this.enabled)
             return undefined;
@@ -27,8 +56,10 @@ export class ArtifactCache {
             return undefined;
         }
         this.#hits += 1;
-        this.#entries.delete(key);
-        this.#entries.set(key, entry);
+        if (this.#newest !== entry) {
+            this.#unlink(entry);
+            this.#appendNewest(entry);
+        }
         return entry.payload;
     }
     put(key, payload, bytes) {
@@ -39,24 +70,44 @@ export class ArtifactCache {
         }
         const existing = this.#entries.get(key);
         if (existing !== undefined) {
-            this.#entries.delete(key);
             this.#usedBytes -= existing.bytes;
+            existing.payload = payload;
+            existing.bytes = bytes;
+            this.#usedBytes += bytes;
+            if (this.#newest !== existing) {
+                this.#unlink(existing);
+                this.#appendNewest(existing);
+            }
+        }
+        else {
+            const entry = {
+                key,
+                payload,
+                bytes,
+                previous: undefined,
+                next: undefined,
+            };
+            this.#entries.set(key, entry);
+            this.#appendNewest(entry);
+            this.#usedBytes += bytes;
         }
-        this.#entries.set(key, { payload, bytes });
-        this.#usedBytes += bytes;
-        for (const [oldestKey, entry] of this.#entries) {
-            if (this.#usedBytes <= this.#limitBytes)
-                break;
-            if (oldestKey === key)
-                continue;
-            this.#entries.delete(oldestKey);
-            this.#usedBytes -= entry.bytes;
-            this.#evictions += 1;
+        let oldest = this.#oldest;
+        while (this.#usedBytes > this.#limitBytes && oldest !== undefined) {
+            const next = oldest.next;
+            if (oldest.key !== key) {
+                this.#unlink(oldest);
+                this.#entries.delete(oldest.key);
+                this.#usedBytes -= oldest.bytes;
+                this.#evictions += 1;
+            }
+            oldest = next;
         }
     }
     /** Releases every retained payload while preserving lifetime counters for final diagnostics. */
     clear() {
         this.#entries.clear();
+        this.#oldest = undefined;
+        this.#newest = undefined;
         this.#usedBytes = 0;
     }
     stats() {

package/dist/engine/database.js

@@ -24,6 +24,7 @@ import { externalSqlDomainValue, externalSqlTextValue, isDateDomainValue, isSqlD
 import { toCatalog } from "./catalog.js";
 import { applyColumnSteps, assertColumnDroppable, compileGeneratedColumnExpression, declaredForeignKeys, isDestructiveStep, planMigration, } from "./schema.js";
 import { columnarTableFromRows, createColumnarTable, vectorValue, } from "./vector.js";
+import { cachedPointReadTemplate, equalRunRange, pointReadTestHooks, resolvePointReadShape, valuesAreAscending, } from "./point-read.js";
 // The on-disk format is little-endian; the bulk Float64 copy reads platform order.
 const PLATFORM_LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
 const vectorTextDecoder = new TextDecoder("utf-8", { fatal: true });
@@ -33,6 +34,11 @@ const NULL_STRING_VECTOR_CODE = 0xffffffff;
 const COMPOSITE_KEY_COLUMN_NAME = "\u0000minnow_primary_key";
 const ENUM_TYPE_PREFIX = "\u0000minnow_enum_type:";
 const SEQUENCE_PREFIX = "\u0000minnow_sequence:";
+/**
+ * Candidate rows the point-read fast path will verify per statement before conceding that the
+ * shape is not selective enough and handing the scan back to the vectorized executor.
+ */
+const MAX_POINT_READ_CANDIDATES = 1_024;
 /** Delta-chunk tail length past which a search schedules a fold-by-rebuild of the base. */
 const FTS_FOLD_DELTA_CHUNKS = 16;
 /** Persistent rebuild failure cannot let an accelerator append one durable delta per commit. */
@@ -1901,10 +1907,10 @@ export class MinnowDatabase {
             const plannedColumn = writeColumnValues(keyColumn.type, values);
             const ranges = writeBlockRanges([plannedColumn], values.length, this.#rowsPerBlock, this.#targetBlockBytes);
             for (const [part, { start, end }] of ranges.entries()) {
-                await blockStager.prepare(maximumWriteBlockStoredBytes(plannedColumn, start, end, this.#compression));
+                await blockStager.prepare(maximumWriteBlockStoredBytes(plannedColumn, start, end, "raw"));
                 const slice = values.slice(start, end);
                 const encodeStarted = performance.now();
-                const bytes = await this.#encodeColumnBlock(keyColumn.id, asColumnInput(keyColumn.type, slice));
+                const bytes = await this.#encodeColumnBlock(keyColumn.id, asColumnInput(keyColumn.type, slice), "raw");
                 encodeMs += performance.now() - encodeStarted;
                 const blockId = [
                     "table",
@@ -3139,7 +3145,30 @@ export class MinnowDatabase {
             // this transaction has staged, and nothing another writer published in between.
             return externalizeQueryResult(await this.#duringTransaction(open, () => open.session.query(sql, options)));
         }
-        const plan = bindPlanParameters(this.#compileCached(sql), options.params);
+        const compiled = this.#compileCached(sql);
+        // The keyed point-read fast path answers an eligible statement before parameter binding
+        // ever clones the plan. A shape, parameter, catalog, or physical-history condition it
+        // cannot prove falls through to the ordinary executor below, which owns all error
+        // reporting; the count check mirrors bind-time validation so a parameter-arity mistake
+        // still reports through the canonical path.
+        if (!pointReadTestHooks.disabled &&
+            options.version === undefined &&
+            options.spillToStorage === undefined &&
+            options.spillPageRows === undefined &&
+            options.executionMemoryBudgetBytes === undefined &&
+            (compiled.parameterCount ?? 0) === (options.params?.length ?? 0)) {
+            const template = cachedPointReadTemplate(compiled);
+            if (template !== null) {
+                const shape = resolvePointReadShape(template, options.params ?? []);
+                if (shape !== undefined) {
+                    const point = await this.#pointReadResult(shape, options);
+                    throwIfAborted(options.signal);
+                    if (point !== undefined)
+                        return externalizeQueryResult(point);
+                }
+            }
+        }
+        const plan = bindPlanParameters(compiled, options.params);
         // Result memoization is a pure cache over the freshness probe: the catalog epoch is part
         // of the key, so any commit or DDL changes the key and a hit can never be stale. Only
         // plain current-version queries memoize — explicit versions, budgets, and spill options
@@ -3526,6 +3555,231 @@ export class MinnowDatabase {
             prepared.close();
         }
     }
+    /**
+     * The keyed point-read fast path: a single-table conjunction of column-equals-literal
+     * predicates covering the unique key names at most one row, so it is answered directly from
+     * cached decoded blocks — no plan binding, streamed view, or vector pipeline. Undefined means
+     * the statement, catalog, or physical history is not provably eligible and the ordinary
+     * executor (which owns all error reporting and general semantics) must run. Every literal
+     * must already match its column's storage type exactly; any coercion case falls back, so the
+     * fast path only ever reproduces what the ordinary path would answer.
+     */
+    async #pointReadResult(shape, options) {
+        pointReadTestHooks.attempted += 1;
+        const result = await this.#withSharedCatalogSnapshot([shape.table], (snapshot, realTables, visibility) => this.#pointReadAtSnapshot(shape, snapshot, realTables, visibility, options));
+        if (result !== undefined) {
+            pointReadTestHooks.served += 1;
+            options.onStats?.({ peakMemoryBytes: 0 });
+        }
+        return result;
+    }
+    async #pointReadAtSnapshot(shape, snapshot, realTables, visibility, options) {
+        const table = realTables.get(shape.table);
+        if (table === undefined || table.view !== undefined)
+            return undefined;
+        const columnByName = new Map(table.columns.map((column) => [column.name, column]));
+        const matchesStorageType = (column, value) => column.sqlDomain === undefined &&
+            column.hidden !== true &&
+            ((column.type === "number" && typeof value === "number") ||
+                (column.type === "string" && typeof value === "string") ||
+                (column.type === "boolean" && typeof value === "boolean") ||
+                (column.type === "datetime" && value instanceof Date));
+        const equalityColumns = new Map();
+        for (const equality of shape.equalities) {
+            const column = columnByName.get(equality.column);
+            if (column === undefined || !matchesStorageType(column, equality.value))
+                return undefined;
+            equalityColumns.set(column.name, column);
+        }
+        // Key coverage is the selectivity proof: the conjunction addresses at most one row, so
+        // per-row candidate verification cannot degrade into an unvectorized table scan.
+        const keyColumn = getUniqueKeyColumn(table);
+        if (keyColumn === undefined)
+            return undefined;
+        const keyComponents = keyColumn.hidden === true ? primaryKeyColumns(table) : [keyColumn];
+        if (keyComponents.length === 0)
+            return undefined;
+        if (!keyComponents.every((component) => equalityColumns.has(component.name))) {
+            return undefined;
+        }
+        const projected = [];
+        for (const item of shape.select) {
+            const column = columnByName.get(item.column);
+            if (column === undefined || column.hidden === true || column.sqlDomain !== undefined) {
+                return undefined;
+            }
+            projected.push({ column, alias: item.alias });
+        }
+        const segments = await this.#visibleSegmentRecords(table, snapshot, visibility);
+        if (segments.some((segment) => {
+            const kind = segment.kind;
+            return kind !== "insert" && kind !== "base";
+        })) {
+            return undefined;
+        }
+        // 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
+        // (per-block reverse dictionary), and fall back to any equality column on the key.
+        const searchColumn = keyComponents.find((component) => component.type === "number" || component.type === "datetime") ??
+            keyComponents.find((component) => component.type === "string") ??
+            keyComponents[0];
+        if (searchColumn === undefined)
+            return undefined;
+        const searchEquality = shape.equalities.find((equality) => equality.column === searchColumn.name);
+        if (searchEquality === undefined)
+            return undefined;
+        const searchTarget = searchEquality.value instanceof Date
+            ? dateMilliseconds(searchEquality.value)
+            : searchEquality.value;
+        const neededColumns = [
+            ...new Set([...equalityColumns.values(), ...projected.map((item) => item.column)]),
+        ];
+        const rows = [];
+        let candidateBudget = MAX_POINT_READ_CANDIDATES;
+        for (const segment of segments) {
+            throwIfAborted(options.signal);
+            if (segment.rowCount === 0)
+                continue;
+            const searchBlockIds = segment.columnBlockIds[searchColumn.id] ?? [];
+            if (searchBlockIds.length === 0)
+                return undefined;
+            for (const column of neededColumns) {
+                if ((segment.columnBlockIds[column.id]?.length ?? 0) !== searchBlockIds.length) {
+                    return undefined;
+                }
+            }
+            let blockIndexes = searchBlockIds.map((_, index) => index);
+            // A single block cannot be pruned, so skip the zone lookup entirely for the hot
+            // one-block OLTP table shape.
+            if (typeof searchTarget === "number" && searchBlockIds.length > 1) {
+                const descriptions = await this.#zoneDescriptions(searchBlockIds, snapshot);
+                blockIndexes = blockIndexes.filter((blockIndex) => {
+                    const zone = descriptions.get(searchBlockIds[blockIndex] ?? "")?.metadata.zoneMap;
+                    return zone === undefined || (zone.min <= searchTarget && searchTarget <= zone.max);
+                });
+            }
+            if (blockIndexes.length === 0)
+                continue;
+            const searchBlocks = await this.#decodedBlocksThroughCache(blockIndexes.map((blockIndex) => searchBlockIds[blockIndex] ?? ""), snapshot);
+            for (const [position, blockIndex] of blockIndexes.entries()) {
+                throwIfAborted(options.signal);
+                const decoded = searchBlocks[position];
+                if (decoded === undefined)
+                    return undefined;
+                const blockId = searchBlockIds[blockIndex] ?? "";
+                const vector = this.#blockColumnVector(blockId, decoded);
+                if (vector.kind !== searchColumn.type)
+                    return undefined;
+                const candidates = [];
+                if ((vector.kind === "number" || vector.kind === "datetime") &&
+                    typeof searchTarget === "number") {
+                    if (decoded.description.nullCount === 0 && valuesAreAscending(vector.values)) {
+                        const run = equalRunRange(vector.values, searchTarget);
+                        for (let slot = run.begin; slot < run.end; slot += 1)
+                            candidates.push(slot);
+                    }
+                    else {
+                        for (let slot = 0; slot < vector.length; slot += 1) {
+                            if (vector.values[slot] === searchTarget) {
+                                // A null slot's backing value is unspecified; confirm through validity.
+                                const value = vectorValue(vector, slot);
+                                if (value !== null)
+                                    candidates.push(slot);
+                            }
+                        }
+                    }
+                }
+                else if (vector.kind === "string" && typeof searchTarget === "string") {
+                    const code = this.#dictionaryCode(blockId, vector, searchTarget);
+                    if (code === undefined)
+                        continue;
+                    for (let slot = 0; slot < vector.length; slot += 1) {
+                        if (vector.codes[slot] === code)
+                            candidates.push(slot);
+                    }
+                }
+                else if (vector.kind === "boolean" && typeof searchTarget === "boolean") {
+                    for (let slot = 0; slot < vector.length; slot += 1) {
+                        if (vectorValue(vector, slot) === searchTarget)
+                            candidates.push(slot);
+                    }
+                }
+                else {
+                    return undefined;
+                }
+                if (candidates.length === 0)
+                    continue;
+                candidateBudget -= candidates.length;
+                if (candidateBudget < 0)
+                    return undefined;
+                const remainingColumns = neededColumns.filter((column) => column.id !== searchColumn.id);
+                const rowBlockIds = remainingColumns.map((column) => segment.columnBlockIds[column.id]?.[blockIndex] ?? "");
+                const rowBlocks = await this.#decodedBlocksThroughCache(rowBlockIds, snapshot);
+                const vectors = new Map([[searchColumn.name, vector]]);
+                for (const [index, column] of remainingColumns.entries()) {
+                    const block = rowBlocks[index];
+                    if (block === undefined)
+                        return undefined;
+                    const columnVector = this.#blockColumnVector(rowBlockIds[index] ?? "", block);
+                    if (columnVector.kind !== column.type)
+                        return undefined;
+                    vectors.set(column.name, columnVector);
+                }
+                for (const slot of candidates) {
+                    let matches = true;
+                    for (const equality of shape.equalities) {
+                        const columnVector = vectors.get(equality.column);
+                        if (columnVector === undefined)
+                            return undefined;
+                        const stored = vectorValue(columnVector, slot);
+                        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)
+                        continue;
+                    const row = {};
+                    for (const item of projected) {
+                        const columnVector = vectors.get(item.column.name);
+                        if (columnVector === undefined)
+                            return undefined;
+                        const value = vectorValue(columnVector, slot);
+                        // A stored plain-text value in the protected NUL namespace crosses the result
+                        // boundary through the ordinary executor's wrapping rules; reproducing them here
+                        // is not worth the risk, so the whole statement falls back.
+                        if (typeof value === "string" && value.charCodeAt(0) === 0)
+                            return undefined;
+                        row[item.alias] = value;
+                    }
+                    rows.push(row);
+                }
+            }
+        }
+        return {
+            columns: shape.select.map((item) => item.alias),
+            columnDomains: shape.select.map(() => null),
+            rows,
+        };
+    }
+    /** The dictionary code for a value in one block's string vector, reverse-mapped and cached. */
+    #dictionaryCode(blockId, vector, value) {
+        let reverse = this.#cacheGet(`drd ${blockId}`);
+        if (reverse === undefined) {
+            reverse = new Map();
+            for (const [code, entry] of vector.dictionary.entries())
+                reverse.set(entry, code);
+            let bytes = 64;
+            for (const entry of vector.dictionary)
+                bytes += 32 + entry.length;
+            this.#cachePut(`drd ${blockId}`, reverse, bytes);
+        }
+        return reverse.get(value);
+    }
     /**
      * Streams a one-column snapshot projection into bounded pages. DELETE uses this before its
      * first staged write: selection keeps all ordinary pruning/predicate semantics without
@@ -5322,9 +5576,9 @@ export class MinnowDatabase {
         const plannedColumn = writeColumnValues(keyColumn.type, values);
         const ranges = writeBlockRanges([plannedColumn], values.length, this.#rowsPerBlock, this.#targetBlockBytes);
         for (const [part, { start, end }] of ranges.entries()) {
-            await blockStager.prepare(maximumWriteBlockStoredBytes(plannedColumn, start, end, this.#compression));
+            await blockStager.prepare(maximumWriteBlockStoredBytes(plannedColumn, start, end, "raw"));
             const slice = values.slice(start, end);
-            const bytes = await this.#encodeColumnBlock(keyColumn.id, asColumnInput(keyColumn.type, slice));
+            const bytes = await this.#encodeColumnBlock(keyColumn.id, asColumnInput(keyColumn.type, slice), "raw");
             const blockId = [
                 "table",
                 table.id,
@@ -5817,6 +6071,20 @@ export class MinnowDatabase {
         const table = reported.base.derived ?? reported.base.union ?? reported.base.windowed;
         if (table === undefined && reported.joins.length === 0) {
             const record = await this.#findTable(reported.base.table);
+            const pointTemplate = record.view === undefined ? cachedPointReadTemplate(reported) : null;
+            if (pointTemplate !== null) {
+                const keyColumn = getUniqueKeyColumn(record);
+                const keyComponents = keyColumn === undefined
+                    ? []
+                    : keyColumn.hidden === true
+                        ? primaryKeyColumns(record)
+                        : [keyColumn];
+                const covered = new Set(pointTemplate.equalities.map((equality) => equality.column));
+                if (keyComponents.length > 0 &&
+                    keyComponents.every((component) => covered.has(component.name))) {
+                    notes.push("key-covering equality answers as a point read when the visible history allows");
+                }
+            }
             if (zonePredicates(reported, record).length > 0) {
                 notes.push("zone-map pruning applies to the unbudgeted scan");
             }
@@ -14183,8 +14451,15 @@ export class MinnowDatabase {
      * the codec each block actually used is recorded in the block itself, so a wrong guess costs
      * bytes and never correctness.
      */
-    async #encodeColumnBlock(columnId, input) {
-        return this.#encodePreferredBlock(columnId, this.#compression, columnInputBytesBelow(input, GZIP_MINIMUM_INPUT_BYTES), (compression) => encodeBlock(input, compression));
+    async #encodeColumnBlock(columnId, input, 
+    /**
+     * "raw" for delete-key blocks: they hold only the doomed keys, compaction folds them away,
+     * and a 50k-key range delete otherwise spends more time in gzip than in the whole rest of
+     * the statement. The stored format carries the codec per block, so nothing changes on disk
+     * beyond the byte count.
+     */
+    preferred = this.#compression) {
+        return this.#encodePreferredBlock(columnId, preferred, columnInputBytesBelow(input, GZIP_MINIMUM_INPUT_BYTES), (compression) => encodeBlock(input, compression));
     }
     /**
      * Applies the same adaptive gzip rule to ordinary writes and compaction output. `gzip` is a

package/dist/engine/point-read.d.ts

@@ -0,0 +1,57 @@
+import type { CompiledQuery, QueryValue } from "../plan/model.js";
+export type PointReadValue = boolean | number | string | Date;
+export interface PointReadEquality {
+    column: string;
+    value: PointReadValue;
+}
+export interface PointReadShape {
+    table: string;
+    /** Conjunctive equalities, in predicate order; may repeat a column. */
+    equalities: PointReadEquality[];
+    /** Plain column projections, in select order. */
+    select: Array<{
+        column: string;
+        alias: string;
+    }>;
+}
+/** The statement-shaped half of the analysis, computed once per cached plan. */
+interface PointReadTemplate {
+    table: string;
+    equalities: Array<{
+        column: string;
+        value: PointReadValue;
+    } | {
+        column: string;
+        parameter: number;
+    }>;
+    select: Array<{
+        column: string;
+        alias: string;
+    }>;
+}
+/**
+ * Test-only escape hatch and counters. Not exported from any public entry point: in-repo
+ * differential suites import this module directly to force the ordinary executor and to
+ * assert the fast path actually served eligible statements.
+ */
+export declare const pointReadTestHooks: {
+    disabled: boolean;
+    attempted: number;
+    served: number;
+};
+/** The template for a cached compiled plan, analyzed once per statement. */
+export declare function cachedPointReadTemplate(plan: CompiledQuery): PointReadTemplate | null;
+/**
+ * Substitutes this call's parameters into the statement template. Undefined means a parameter
+ * carries a value the fast path cannot compare exactly (NULL, a non-finite number, an invalid
+ * Date, or a non-storage value), and the ordinary executor must decide what it means.
+ */
+export declare function resolvePointReadShape(template: PointReadTemplate, params: readonly QueryValue[]): PointReadShape | undefined;
+/** Whether the array is non-strictly ascending; memoized per immutable decoded array. */
+export declare function valuesAreAscending(values: Float64Array): boolean;
+/** The [begin, end) run of slots equal to `target` over an ascending array. */
+export declare function equalRunRange(values: Float64Array, target: number): {
+    begin: number;
+    end: number;
+};
+export {};