@minnowdb/core 0.3.0 → 0.4.0

package/dist/testing/simulator.js

@@ -2,6 +2,17 @@ import { MinnowDatabase } from "../engine/database.js";
 import { MemoryBlockStore } from "../storage/index.js";
 import { FaultInjectingBlockStore } from "./index.js";
 import { md5Hex } from "./sqllogictest.js";
+async function collectStoragePages(read) {
+    const records = [];
+    let cursor = null;
+    for (;;) {
+        const page = await read(cursor);
+        records.push(...page.records);
+        if (page.nextCursor === null)
+            return records;
+        cursor = page.nextCursor;
+    }
+}
 /** Chooses every storage completion from a seeded queue and keeps only a bounded trace tail. */
 export class DeterministicScheduler {
     #random;
@@ -40,6 +51,15 @@ export class DeterministicScheduler {
             await Promise.resolve();
             const pending = this.#pending.length;
             if (pending === 0) {
+                // Production maintenance deliberately yields through a timer between bounded pages.
+                // A microtask-only poll can therefore declare deadlock while the next scheduled store
+                // call is merely waiting for its event-loop turn. Let timers advance before counting an
+                // empty turn; the chosen storage completion order remains seeded and deterministic.
+                await nextEventLoopTurn();
+                if (this.#pending.length > 0) {
+                    emptyTurns = 0;
+                    continue;
+                }
                 emptyTurns++;
                 if (emptyTurns > 100) {
                     throw new Error("Deterministic simulator deadlocked with no scheduled storage operation");
@@ -72,6 +92,20 @@ export class DeterministicScheduler {
             this.#trace.shift();
     }
 }
+function nextEventLoopTurn() {
+    if (typeof MessageChannel === "undefined") {
+        return new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            channel.port1.close();
+            channel.port2.close();
+            resolve();
+        };
+        channel.port2.postMessage(undefined);
+    });
+}
 /** Wraps every asynchronous BlockStore entry point in the deterministic completion scheduler. */
 export function scheduledBlockStore(store, scheduler) {
     return new Proxy(store, {
@@ -288,20 +322,20 @@ export async function runSimulation(plan, options = {}) {
         collectionTail.splice(0, collectionTail.length - 8);
     await drive(scheduler, sweeper.close());
     const rows = sortedRows(model);
-    const [blockIds, segments, transactions, manifests, currentManifest, leases, compactions, storageBytes,] = await Promise.all([
-        base.listBlockIds(),
-        base.listSegments(),
-        base.listTransactions(),
-        base.listManifests(),
+    const [segments, transactions, manifests, currentManifest, leases, compactions, storageBytes] = await Promise.all([
+        collectStoragePages((cursor) => base.listSegmentPage(cursor, 256)),
+        collectStoragePages((cursor) => base.listTransactionPage(cursor, 256)),
+        collectStoragePages((cursor) => base.listManifestPage(cursor, 256)),
         base.getCurrentManifest(),
         base.listLeases(),
         base.listCompactionJobs(),
         base.getLogicalStorageBytes(),
     ]);
+    const blockCount = currentManifest?.liveBlockCount ?? 0;
     const blockLimit = plan.keySpace * 16 + 64;
     const segmentLimit = plan.keySpace + 16;
     const transactionLimit = segmentLimit + 16;
-    if (blockIds.length > blockLimit ||
+    if (blockCount > blockLimit ||
         segments.length > segmentLimit ||
         transactions.length > transactionLimit) {
         const transactionStates = transactions.reduce((counts, transaction) => {
@@ -312,12 +346,12 @@ export async function runSimulation(plan, options = {}) {
             counts[compaction.state] = (counts[compaction.state] ?? 0) + 1;
             return counts;
         }, {});
-        throw new Error(`Storage did not compact to a bound: ${String(blockIds.length)}/${String(blockLimit)} blocks, ` +
+        throw new Error(`Storage did not compact to a bound: ${String(blockCount)}/${String(blockLimit)} live blocks, ` +
             `${String(segments.length)}/${String(segmentLimit)} segments, ` +
             `${String(transactions.length)}/${String(transactionLimit)} transactions; ` +
             `${JSON.stringify(transactionStates)} transaction states, ` +
             `${JSON.stringify(compactionStates)} compaction states, ` +
-            `${String(currentManifest?.blockIds.length ?? 0)} current blocks, compaction stopped at ${compactionStop}, ` +
+            `${String(currentManifest?.liveBlockCount ?? 0)} current blocks, compaction stopped at ${compactionStop}, ` +
             `${String(manifests.length)} manifests (${String(manifests.filter((manifest) => manifest.prunedAt !== undefined).length)} pruned) remain after ${String(maintenanceCompactions)} compactions ` +
             `and ${String(collectionPasses)} collection passes; collection tail ${JSON.stringify(collectionTail)}`);
     }
@@ -339,7 +373,7 @@ export async function runSimulation(plan, options = {}) {
         collectionPasses,
         collectionTail,
         rows,
-        blockCount: blockIds.length,
+        blockCount,
         segmentCount: segments.length,
         transactionCount: transactions.length,
         manifestCount: manifests.length,
@@ -435,8 +469,6 @@ function validateSteps(steps, clients, keySpace) {
         "afterBlockWrite",
         "beforeBlockRead",
         "afterBlockRead",
-        "beforeManifestCommit",
-        "afterManifestCommit",
         "beforeTransactionCommit",
         "afterTransactionCommit",
     ]);
@@ -557,4 +589,3 @@ function greatestCommonDivisor(left, right) {
         [a, b] = [b, a % b];
     return a;
 }
-//# sourceMappingURL=simulator.js.map

package/dist/testing/sqllogictest.d.ts

@@ -87,4 +87,3 @@ export declare function renderSqlLogicValue(value: QueryValue, type: SqlLogicTyp
 /** Small browser-safe MD5 implementation for compatibility with the original corpus hashes. */
 export declare function md5Hex(input: string): string;
 export {};
-//# sourceMappingURL=sqllogictest.d.ts.map

package/dist/testing/sqllogictest.js

@@ -432,4 +432,3 @@ const MD5_SHIFTS = [
     10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
 ];
 const MD5_CONSTANTS = Array.from({ length: 64 }, (_, index) => Math.floor(Math.abs(Math.sin(index + 1)) * 2 ** 32));
-//# sourceMappingURL=sqllogictest.js.map

package/dist/transactions/index.d.ts

@@ -1,8 +1,16 @@
-import { type BlockStore, type BlockWrite, type LeaseKind, type LeaseRecord, type ManifestSummary, type RowIdRange, type SegmentRecord, type TransactionRecord, type FtsChanges, type UniqueKeyChanges } from "../storage/index.js";
+import { type BlockStore, type BlockWrite, type LeaseKind, type LeaseRecord, MAX_LEASE_TTL_MS, type ManifestSummary, type RowIdRange, type SegmentRecord, type TableRecord, type TransactionRecord, type FtsChanges, type UniqueKeyChanges } from "../storage/types.js";
 export interface TransactionManagerOptions {
     now?: () => Date;
     createId?: () => string;
+    /** Durable writer deadline; live transactions renew every third of this interval. */
+    transactionTtlMs?: number;
+    /** Test seam for deterministic collection of an abandoned transaction reference. */
+    createWeakRef?: (transaction: DatabaseTransaction) => {
+        deref(): DatabaseTransaction | undefined;
+    };
 }
+export declare const DEFAULT_TRANSACTION_TTL_MS = 30000;
+export { MAX_LEASE_TTL_MS };
 export interface RecoveryOptions {
     staleBefore: Date;
     removePendingBlocks?: boolean;
@@ -23,6 +31,14 @@ export interface OpenLeasedSnapshotOptions {
     kind?: LeaseKind;
     version?: number | null;
 }
+export interface BeginDeferredOptions {
+    /**
+     * Pins the captured snapshot with a renewable durable reader lease until this transaction
+     * either persists its own durable owner or finishes. Enabled by default; tightly bounded
+     * internal statements that cannot idle may opt out to retain the one-write fast path.
+     */
+    durableSnapshot?: boolean;
+}
 export declare class TransactionClosedError extends Error {
     readonly transactionId: string;
     readonly name = "TransactionClosedError";
@@ -35,23 +51,27 @@ export interface TransactionCheckpoint {
     readonly pendingSegmentIds: readonly string[];
     readonly uniqueKeyChanges: readonly UniqueKeyChanges[];
     readonly ftsChanges: readonly FtsChanges[];
-    readonly supersededBlockIds: readonly string[];
+    readonly compactionJobId: string | null;
+    readonly compactionSourceBlockIds: readonly string[];
+    readonly levelZeroSegmentLimits: ReadonlyArray<{
+        tableId: string;
+        limit: number;
+    }>;
     readonly changedTableIds: readonly string[];
     readonly logicallyUnchanged: boolean;
 }
 export declare class Snapshot {
-    #private;
     private readonly store;
     readonly version: number | null;
-    constructor(store: BlockStore, version: number | null, blockIds: readonly string[]);
-    listBlockIds(): string[];
-    hasBlock(id: string): boolean;
+    constructor(store: BlockStore, version: number | null);
+    hasBlock(id: string): Promise<boolean>;
+    hasBlocks(ids: readonly string[]): Promise<boolean[]>;
     getBlock(id: string): Promise<Uint8Array | undefined>;
 }
 export declare class LeasedSnapshot extends Snapshot {
     #private;
     private readonly now;
-    constructor(store: BlockStore, version: number | null, blockIds: readonly string[], record: LeaseRecord, now: () => Date);
+    constructor(store: BlockStore, version: number | null, record: LeaseRecord, now: () => Date);
     get leaseId(): string;
     get expiresAt(): Date;
     getBlock(id: string): Promise<Uint8Array | undefined>;
@@ -63,7 +83,7 @@ export declare class LeasedSnapshot extends Snapshot {
      * (`SnapshotManifestMissingError`, `LeaseConflictError`) leave this snapshot open and pass
      * through.
      */
-    moveTo(version: number | null, ttlMs: number, knownBlockIds?: readonly string[]): Promise<LeasedSnapshot | undefined>;
+    moveTo(version: number | null, ttlMs: number): Promise<LeasedSnapshot | undefined>;
     release(): Promise<void>;
     /** Closes this snapshot without touching the store — for a lease the store no longer holds. */
     discard(): void;
@@ -72,15 +92,44 @@ export declare class DatabaseTransaction {
     #private;
     private readonly store;
     private readonly now;
-    constructor(store: BlockStore, record: TransactionRecord, now: () => Date, options?: {
+    private readonly ttlMs;
+    constructor(store: BlockStore, record: TransactionRecord, now: () => Date, ttlMs: number, createWeakRef: (transaction: DatabaseTransaction) => {
+        deref(): DatabaseTransaction | undefined;
+    }, options?: {
         persisted?: boolean;
+        initialCatalogProbe?: {
+            catalogEpoch: number;
+            manifestVersion: number | null;
+            schemaEpoch: number;
+        };
+        snapshotLease?: LeasedSnapshot;
     });
     get id(): string;
     get status(): TransactionRecord["status"];
     get snapshotVersion(): number | null;
     get pendingBlockIds(): string[];
     get pendingSegmentIds(): string[];
-    get supersededBlockIds(): string[];
+    /** Process-local segments retained for a bounded single-shot commit. */
+    get deferredSegments(): SegmentRecord[];
+    get pendingTableNextRowId(): bigint | undefined;
+    get initialCatalogProbe(): {
+        catalogEpoch: number;
+        manifestVersion: number | null;
+        schemaEpoch: number;
+    } | undefined;
+    /** Exact local commit contribution; undefined until this transaction commits. */
+    get committedCatalogContribution(): {
+        transaction: TransactionRecord;
+        segments: SegmentRecord[];
+        initialCatalogProbe?: {
+            catalogEpoch: number;
+            manifestVersion: number | null;
+            schemaEpoch: number;
+        };
+    } | undefined;
+    get compactionSourceBlockIds(): string[];
+    /** Extends durable ownership; scope owners call this while user code is legitimately waiting. */
+    renew(): Promise<void>;
     /**
      * Counts every registration this transaction carries: staged blocks and segments, unique-key
      * entries, full-text entries, and supersessions. A caller that fails part-way through a
@@ -91,6 +140,8 @@ export declare class DatabaseTransaction {
     get stagedWorkCount(): number;
     /** Captures all publish-relevant state; row-id/autoincrement reservations deliberately burn. */
     checkpoint(): TransactionCheckpoint;
+    /** Conservative retained-size estimate used to refuse savepoint clones before allocating. */
+    checkpointRetainedBytes(): number;
     /** Rewinds staged artifacts and every in-memory commit delta to one earlier checkpoint. */
     rollbackTo(checkpoint: TransactionCheckpoint): Promise<void>;
     snapshot(): Promise<Snapshot>;
@@ -125,6 +176,8 @@ export declare class DatabaseTransaction {
     stageSegment(record: SegmentRecord): Promise<void>;
     /** Reconciles a persisted segment whose journal update was interrupted. */
     stageExistingSegment(segmentId: string): Promise<void>;
+    /** Atomically adopts an exact unpublished output left by an aborted attempt of this job. */
+    adoptAbortedCompactionSegment(record: SegmentRecord, abortedOwner: TransactionRecord): Promise<void>;
     /**
      * Records that this commit changes a table's logical content without staging a segment for
      * it — dropping the table, for instance, whose only publish is the retirement of its blocks.
@@ -147,7 +200,14 @@ export declare class DatabaseTransaction {
      * and token totals summed — so a scope can insert into one FTS table any number of times.
      */
     setFtsChanges(changes: FtsChanges): void;
-    supersedeBlocks(blockIds: readonly string[]): void;
+    /**
+     * Binds a physical retirement to one persisted compaction job. Stores revalidate the job,
+     * source segments, current manifest, and aliases atomically with publication; this in-memory
+     * declaration is intent, never authority to hide arbitrary blocks.
+     */
+    setCompactionIntent(compactionJobId: string, sourceBlockIds: readonly string[]): void;
+    /** Adds an adapter-enforced post-commit level-zero ceiling for one table. */
+    limitLevelZeroSegments(tableId: string, limit: number): void;
     commit(): Promise<ManifestSummary>;
     rebase(): Promise<Snapshot>;
     abort(): Promise<void>;
@@ -157,14 +217,16 @@ export declare class TransactionManager {
     private readonly store;
     constructor(store: BlockStore, options?: TransactionManagerOptions);
     begin(): Promise<DatabaseTransaction>;
+    /** Atomically reserves an invisible catalog table for a create-and-populate transaction. */
+    beginWithPendingTable(record: TableRecord, expectedCatalogEpoch: number): Promise<DatabaseTransaction>;
     /**
-     * Begins a transaction without a storage write: the record is pinned at the current manifest
-     * version (one read) and written only when something is staged through the two-step methods
-     * — or never, when the whole write goes through `stageArtifactsAndCommit` on a store with
-     * the single-shot `writeTransaction`, or the transaction aborts untouched. For writes whose
-     * artifacts need no prior reservation; `beginWithReservation` is the shape for the rest.
+     * Begins without a transaction record. By default a renewable reader lease durably pins the
+     * probed manifest until the first two-step stage hands ownership to a transaction record. The
+     * record and lease are both omitted only for internal, uninterrupted single-shot writes that
+     * opt out and publish through `writeTransaction`. For writes whose artifacts need no prior
+     * reservation; `beginWithReservation` is the shape for the rest.
      */
-    beginDeferred(): Promise<DatabaseTransaction>;
+    beginDeferred(options?: BeginDeferredOptions): Promise<DatabaseTransaction>;
     /**
      * Begins a transaction at the current manifest version and optionally reserves row ids and
      * auto-increment values in the same step. Stores implementing the atomic `beginTransaction`
@@ -186,7 +248,7 @@ export declare class TransactionManager {
     }>;
     resume(transactionId: string): Promise<DatabaseTransaction>;
     openSnapshot(version?: number | null): Promise<Snapshot>;
-    openLeasedSnapshot(options: OpenLeasedSnapshotOptions, knownBlockIds?: readonly string[]): Promise<LeasedSnapshot>;
+    openLeasedSnapshot(options: OpenLeasedSnapshotOptions): Promise<LeasedSnapshot>;
     /**
      * Re-pins an open leased snapshot to another version — one reader moving on to a newer
      * commit. With the store's atomic `moveLease` the record stays and moves in one round trip;
@@ -197,8 +259,7 @@ export declare class TransactionManager {
      */
     moveLeasedSnapshot(snapshot: LeasedSnapshot, options: OpenLeasedSnapshotOptions & {
         version: number | null;
-    }, knownBlockIds?: readonly string[]): Promise<LeasedSnapshot>;
+    }): Promise<LeasedSnapshot>;
     removeExpiredLeases(at?: Date): Promise<string[]>;
     recover(options: RecoveryOptions): Promise<RecoveryReport>;
 }
-//# sourceMappingURL=index.d.ts.map