@minnowdb/core 0.4.1 → 0.6.0

package/dist/engine/worker-host.js

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

package/dist/plan/index.d.ts

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

package/dist/plan/index.js

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

package/dist/plan/model.d.ts

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

package/dist/plan/model.js

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

package/dist/storage/indexeddb.js

@@ -1,4 +1,4 @@
-import { CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, CompactionBacklogError, createManifest, createGarbageCollectionJobRecord, storeNames, advanceGarbageCollectionJobRecord as advanceGarbageCollectionJobRecordUnchecked, BlockReadBatchTooLargeError, activePostingStorageColumnIds, assertTempRunPageBatchLimits, assertStorageBulkReadItems, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, boundedMaintenanceBatchItems, canonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, collectFtsPostings, ftsPostingQueryMatches, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_FTS_CANDIDATE_ROW_IDS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_CHUNK_BYTES, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_ORDERED_READ_BYTES, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_BLOCK_READ_BATCH_BYTES, MAX_STORAGE_ID_CHARACTERS, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TRANSACTIONS, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_RETIRED_HISTORY_BYTES, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_ACTIVE_FTS_BASE_BUILDS, MAX_ACTIVE_SECONDARY_INDEX_BUILDS, MAX_ACCELERATOR_BUILD_STAGED_BYTES_TOTAL, MAX_ACCELERATOR_BUILD_STAGED_ENTRIES_TOTAL, MAX_POSTING_BUILD_TTL_MS, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, MAX_SNAPSHOT_METADATA_FRAME_BYTES, SNAPSHOT_FRAME_KINDS, MAX_LEVEL_ZERO_SEGMENTS, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, StorageCorruptionError, StorageFormatVersionError, IndexedDbSchemaUpgradeBlockedError, StorageResourceLimitError, SnapshotManifestMissingError, SnapshotImportConflictError, PostingBuildConflictError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, MAX_TEMP_OWNER_TTL_MS, MAX_ACTIVE_TEMP_OWNERS, MAX_TEMP_RUNS_PER_OWNER, MAX_TEMP_PAGES_PER_OWNER, MAX_TEMP_RUNS_TOTAL, MAX_TEMP_PAGES_TOTAL, MAX_TEMP_BYTES_PER_OWNER, MAX_TEMP_BYTES_TOTAL, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, SchemaConflictError, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord as updateCompactionJobRecordUnchecked, updateGarbageCollectionPlanningRecord, updateTransactionRecord as updateTransactionRecordUnchecked, validateColumnDefault, validateCatalogName, validateCanonicalManifestChangedTableIds, validateEnumValues, validateFtsOrderedReadLimits, validateFtsPostingQueries, validateStorageId, validateStorageDatabaseName, validateTableColumns, validateSecondaryIndexes, validateTableRecordBounds, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, WriteConflictError, } from "./types.js";
+import { CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, CompactionBacklogError, createManifest, createGarbageCollectionJobRecord, storeNames, advanceGarbageCollectionJobRecord as advanceGarbageCollectionJobRecordUnchecked, BlockReadBatchTooLargeError, activePostingStorageColumnIds, assertTempRunPageBatchLimits, assertStorageBulkReadItems, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, boundedMaintenanceBatchItems, canonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, collectFtsPostings, ftsPostingQueryMatches, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_FTS_CANDIDATE_ROW_IDS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_CHUNK_BYTES, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_ORDERED_READ_BYTES, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_BLOCK_READ_BATCH_BYTES, MAX_STORAGE_ID_CHARACTERS, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TRANSACTIONS, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_RETIRED_HISTORY_BYTES, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_ACTIVE_FTS_BASE_BUILDS, MAX_ACTIVE_SECONDARY_INDEX_BUILDS, MAX_ACCELERATOR_BUILD_STAGED_BYTES_TOTAL, MAX_ACCELERATOR_BUILD_STAGED_ENTRIES_TOTAL, MAX_POSTING_BUILD_TTL_MS, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, MAX_SNAPSHOT_METADATA_FRAME_BYTES, SNAPSHOT_FRAME_KINDS, MAX_LEVEL_ZERO_SEGMENTS, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, StorageCorruptionError, StorageFormatVersionError, IndexedDbSchemaUpgradeBlockedError, StorageResourceLimitError, SnapshotManifestMissingError, SnapshotImportConflictError, PostingBuildConflictError, validateTableForeignKey, TableInUseError, TableRecordConflictError, TempOwnerConflictError, MAX_TEMP_OWNER_TTL_MS, MAX_ACTIVE_TEMP_OWNERS, MAX_TEMP_RUNS_PER_OWNER, MAX_TEMP_PAGES_PER_OWNER, MAX_TEMP_RUNS_TOTAL, MAX_TEMP_PAGES_TOTAL, MAX_TEMP_BYTES_PER_OWNER, MAX_TEMP_BYTES_TOTAL, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, SchemaConflictError, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord as updateCompactionJobRecordUnchecked, updateGarbageCollectionPlanningRecord, updateTransactionRecord as updateTransactionRecordUnchecked, validateColumnDefault, validateCatalogName, validateCanonicalManifestChangedTableIds, validateEnumValues, validateFtsOrderedReadLimits, validateFtsPostingQueries, validateStorageId, validateStorageDatabaseName, validateTableColumns, validateSecondaryIndexes, validateTableRecordBounds, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, WriteConflictError, } from "./types.js";
 import { crc32, verifyStoredBlock } from "../block-format/index.js";
 import { dateIsoString } from "../date-value.js";
 import { decodeSnapshotMetadataItems, encodeSnapshotMetadataPage, extendSnapshotFrameStreamChecksum, prepareSnapshotFrameStreamHeader, snapshotFrameEnvelopeParts, snapshotFrameStreamHeaderIdentity, } from "./snapshot-stream.js";
@@ -9678,7 +9678,7 @@ function asTableRecord(value, location = "catalog/table") {
         }
         for (const [index, foreignKey] of rawForeignKeys.entries()) {
             if (isRecord(foreignKey)) {
-                assertKnownFields(foreignKey, ["name", "columns", "parentTable", "parentColumns", "onDelete"], `${location}/foreignKeys/${String(index)}`);
+                assertKnownFields(foreignKey, ["name", "columns", "parentTable", "parentColumns", "onDelete", "enforced"], `${location}/foreignKeys/${String(index)}`);
             }
             if (!isRecord(foreignKey) ||
                 !isCatalogName(foreignKey.name) ||
@@ -9690,6 +9690,7 @@ function asTableRecord(value, location = "catalog/table") {
                 foreignKey.parentColumns.length === 0 ||
                 foreignKey.columns.length !== foreignKey.parentColumns.length ||
                 !["restrict", "cascade", "set null"].includes(String(foreignKey.onDelete)) ||
+                (foreignKey.enforced !== undefined && typeof foreignKey.enforced !== "boolean") ||
                 foreignKey.parentColumns.some((columnName) => !isCatalogName(columnName))) {
                 throw corruption(`${location}/foreignKeys/${String(index)}`, "foreign-key metadata is invalid");
             }
@@ -11965,16 +11966,7 @@ async function assertTableForeignKeysInTransaction(catalog, record) {
         if (parent === undefined) {
             throw new TypeError(`FOREIGN KEY ${key.name} references a missing table: ${key.parentTable}`);
         }
-        const addressIds = parent.primaryKeyColumnIds?.length
-            ? parent.primaryKeyColumnIds
-            : parent.uniqueKeyColumnId === undefined
-                ? []
-                : [parent.uniqueKeyColumnId];
-        const addressNames = addressIds.map((id) => parent.columns.find((column) => column.id === id)?.name ?? "");
-        if (addressNames.length !== key.parentColumns.length ||
-            addressNames.some((name, index) => name !== key.parentColumns[index])) {
-            throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
-        }
+        validateTableForeignKey(record, key, parent);
     }
 }
 async function updateRetiredHistoryLedger(store, deltaBytes) {

package/dist/storage/toolkit/record-core.js

@@ -1,4 +1,4 @@
-import { CompactionBacklogError, CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, createManifest, createGarbageCollectionJobRecord, advanceGarbageCollectionJobRecord, collectFtsCandidates, collectFtsPostingsBounded, activePostingStorageColumnIds, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TEMP_OWNERS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_ACTIVE_TRANSACTIONS, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_RETIRED_HISTORY_BYTES, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_TEMP_OWNER_TTL_MS, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_ID_CHARACTERS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, SnapshotManifestMissingError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, assertTempRunPageBatchLimits, assertStorageBulkReadItems, boundedMaintenanceBatchItems, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord, updateTransactionRecord, updateGarbageCollectionPlanningRecord, validateTableColumns, validateSecondaryIndexes, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, validateFtsPostingQueries, validateCanonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, snapshotAcceleratorItemRetainedUsage, assertSnapshotImportAcceleratorUsage, SchemaConflictError, WriteConflictError, } from "../types.js";
+import { CompactionBacklogError, CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, createManifest, createGarbageCollectionJobRecord, advanceGarbageCollectionJobRecord, collectFtsCandidates, collectFtsPostingsBounded, activePostingStorageColumnIds, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TEMP_OWNERS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_ACTIVE_TRANSACTIONS, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_RETIRED_HISTORY_BYTES, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_TEMP_OWNER_TTL_MS, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_ID_CHARACTERS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, SnapshotManifestMissingError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, assertTempRunPageBatchLimits, assertStorageBulkReadItems, boundedMaintenanceBatchItems, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord, updateTransactionRecord, updateGarbageCollectionPlanningRecord, validateTableColumns, validateTableForeignKey, validateSecondaryIndexes, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, validateFtsPostingQueries, validateCanonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, snapshotAcceleratorItemRetainedUsage, assertSnapshotImportAcceleratorUsage, SchemaConflictError, WriteConflictError, } from "../types.js";
 import { dateIsoString } from "../../date-value.js";
 import { assertWellFormedString, crc32, MAX_STORED_BLOCK_BYTE_LENGTH, } from "../../block-format/index.js";
 const postingTextEncoder = new TextEncoder();
@@ -1300,16 +1300,7 @@ export class RecordCore {
             if (parent === undefined) {
                 throw new TypeError(`FOREIGN KEY ${key.name} references a missing table: ${key.parentTable}`);
             }
-            const addressIds = parent.primaryKeyColumnIds?.length
-                ? parent.primaryKeyColumnIds
-                : parent.uniqueKeyColumnId === undefined
-                    ? []
-                    : [parent.uniqueKeyColumnId];
-            const addressNames = addressIds.map((id) => parent.columns.find((column) => column.id === id)?.name ?? "");
-            if (addressNames.length !== key.parentColumns.length ||
-                addressNames.some((name, index) => name !== key.parentColumns[index])) {
-                throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
-            }
+            validateTableForeignKey(record, key, parent);
         }
     }
     getTable(id) {
@@ -1342,7 +1333,7 @@ export class RecordCore {
         }
         if (update.columns !== undefined)
             validateTableColumns(update.columns);
-        const { ftsColumns: previousFts, secondaryIndexes: previousSecondary, triggers: previousTriggers, view: previousView, ...base } = record;
+        const { ftsColumns: previousFts, secondaryIndexes: previousSecondary, triggers: previousTriggers, view: previousView, foreignKeys: previousForeignKeys, ...base } = record;
         let nextFts = update.ftsColumns === undefined ? previousFts : update.ftsColumns;
         let nextSecondary = update.secondaryIndexes === undefined ? previousSecondary : update.secondaryIndexes;
         const retainedColumnIds = update.columns === undefined
@@ -1373,6 +1364,7 @@ export class RecordCore {
         }
         const nextTriggers = update.triggers === undefined ? previousTriggers : update.triggers;
         const nextView = update.view === undefined ? previousView : update.view;
+        const nextForeignKeys = update.foreignKeys ?? previousForeignKeys;
         validateTableView(nextView ?? undefined);
         const updated = {
             ...base,
@@ -1386,10 +1378,12 @@ export class RecordCore {
             ...(nextTriggers === null || nextTriggers === undefined
                 ? {}
                 : { triggers: structuredClone(nextTriggers) }),
+            ...(nextForeignKeys === undefined ? {} : { foreignKeys: structuredClone(nextForeignKeys) }),
             ...(nextView === null || nextView === undefined ? {} : { view: structuredClone(nextView) }),
             revision: safeWholeIncrement(expectedRevision, "Table revision"),
         };
         validateSecondaryIndexes(updated);
+        this.#assertTableForeignKeys(updated);
         this.#assertTableTriggerOwnership(updated);
         let autoIncrementCounter;
         if (update.autoIncrementSeed !== undefined) {
@@ -5552,16 +5546,7 @@ function validateRecordCoreState(state, physical) {
             if (parent === undefined) {
                 throw new TypeError(`FOREIGN KEY ${key.name} references a missing table: ${key.parentTable}`);
             }
-            const addressIds = parent.primaryKeyColumnIds?.length
-                ? parent.primaryKeyColumnIds
-                : parent.uniqueKeyColumnId === undefined
-                    ? []
-                    : [parent.uniqueKeyColumnId];
-            const addressNames = addressIds.map((id) => parent.columns.find((column) => column.id === id)?.name ?? "");
-            if (addressNames.length !== key.parentColumns.length ||
-                addressNames.some((name, index) => name !== key.parentColumns[index])) {
-                throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
-            }
+            validateTableForeignKey(table, key, parent);
         }
     }
     const terminalTransactionCount = state.transactions.filter((transaction) => transaction.status !== "active").length;