@minnowdb/core 0.3.0 → 0.4.0

package/dist/storage/toolkit/record-core.d.ts

@@ -1,5 +1,4 @@
-import { type BeginTransactionInput, type BeginTransactionResult, type CommitTransactionInput, type CompactionJobRecord, type CompactionJobRecordUpdate, type CreateGarbageCollectionJobInput, type CatalogProbe, type TriggerRecord, type FtsCandidates, type FtsColumnIndexRecord, type FtsPostingQuery, type FtsPosting, type GarbageCollectionJobRecord, type GarbageCollectionStepResult, type LeaseRecord, type Manifest, type ManifestSummary, type PublishManifestInput, type QueryCatalogState, type RowIdRange, type RunGarbageCollectionStepInput, type SegmentRecord, type StageTransactionArtifactsInput, type StoragePage, type TableColumnRecord, type TableRecord, type SecondaryIndexRecord, type TempOwnerRecord, type TempRunPage, type TransactionRecord, type TransactionRecordUpdate, type WriteTransactionInput } from "../types.js";
-import { type DatabaseSnapshot } from "../snapshot.js";
+import { type BeginTransactionInput, type BeginTransactionResult, type AbortTransactionIfExpiredInput, type AdoptAbortedSegmentInput, type RenewTransactionInput, type CommitTransactionInput, type CompactionJobRecord, type CompactionJobRecordUpdate, type CreateGarbageCollectionJobInput, type UpdateGarbageCollectionPlanningInput, type DropTableColumnInput, type DropTableInput, type CatalogProbe, type FtsCandidates, type FtsPostingQuery, type FtsPosting, type GarbageCollectionJobRecord, type GarbageCollectionStepResult, type LeaseRecord, type MoveLeaseInput, type RenewLeaseInput, type RenewTempOwnerInput, type Manifest, type ManifestBlockRecord, type ListManifestBlockPageInput, type ListRetiredManifestBlockPageInput, type ManifestBlockPage, type ManifestSummary, type RowIdRange, type RunGarbageCollectionStepInput, type SegmentRecord, type RollbackTransactionArtifactsInput, type StageTransactionArtifactsInput, type StoragePage, type CatalogMutationOptions, type TableRecord, type TableRecordUpdate, type TempOwnerRecord, type TempRunPage, type TransactionRecord, type TransactionRecordUpdate, type UniqueKeyBuildRecord, type BeginUniqueKeyBuildInput, type RenewUniqueKeyBuildInput, type AppendUniqueKeyBuildChunkInput, type FinishUniqueKeyBuildInput, type AbortUniqueKeyBuildInput, type WriteTransactionInput, type SnapshotCatalogItem, type SnapshotMetadataItem, type SnapshotFrameStreamHeader, type SnapshotPostingItem, type SnapshotSegmentItem, type SnapshotTransactionItem, type SnapshotUniqueItem } from "../types.js";
 /**
  * How the record core sees block bytes it does not hold. The core owns every small record —
  * catalog, manifests, transactions, leases, jobs, counters, keys — but block payloads live
@@ -10,12 +9,68 @@ export interface PhysicalBlocks {
     hasBlock(id: string): boolean;
     /** `undefined` means the block does not exist. */
     blockByteLength(id: string): number | undefined;
+    /** Exact stored-payload CRC when the adapter persists manifest provenance. */
+    blockChecksum?(id: string): number | undefined;
+}
+type OrderedKey = string | number;
+/**
+ * A small chunked ordered index. Random UUID insertion only shifts one bounded chunk, while a
+ * cursor seek binary-searches chunks and keys before walking the requested page sequentially.
+ */
+/** @internal Exported only so the storage hardening suite can assert operation counts. */
+export declare class OrderedKeyIndex<Key> {
+    #private;
+    static readonly CHUNK_SIZE = 128;
+    constructor(compare: (left: Key, right: Key) => number);
+    clear(): void;
+    get empty(): boolean;
+    add(key: Key): void;
+    delete(key: Key): void;
+    after(after: Key | null): IterableIterator<Key>;
+}
+/** Membership lookup plus stable lexical streaming without sorting on every bulk write. */
+/** @internal Exported only so storage hardening tests can exercise lazy-index transitions. */
+export declare class OrderedStringSet extends Set<string> {
+    #private;
+    constructor(values?: Iterable<string>);
+    add(value: string): this;
+    /**
+     * Adds a commit delta without maintaining snapshot order token-by-token. Membership remains
+     * eager and exact; the snapshot-only index is rebuilt once, deterministically, if ordered
+     * iteration is later requested. Clearing a stale index also releases its duplicate references.
+     */
+    addMany(values: Iterable<string>): this;
+    delete(value: string): boolean;
+    clear(): void;
+    orderedValues(): IterableIterator<string>;
+}
+declare class OrderedRecordMap<Key extends OrderedKey, Value> extends Map<Key, Value> {
+    #private;
+    constructor(onChange?: (previous: Value | undefined, next: Value | undefined) => void);
+    set(key: Key, value: Value): this;
+    delete(key: Key): boolean;
+    clear(): void;
+    orderedValues(after: Key | null): IterableIterator<Value>;
+}
+/** @internal Exported only so the storage hardening suite can exercise table-local traversal. */
+export declare class SegmentRecordMap extends OrderedRecordMap<string, SegmentRecord> {
+    #private;
+    set(id: string, record: SegmentRecord): this;
+    delete(id: string): boolean;
+    clear(): void;
+    tableValues(tableId: string): IterableIterator<SegmentRecord>;
+    blockReferenceCount(blockId: string): number;
+    tableBlockReferenceCount(tableId: string, blockId: string): number;
+    segmentIdsForBlock(blockId: string): ReadonlySet<string>;
+    ownerReferenceCount(transactionId: string): number;
 }
 /** `RecordCore.dump()`'s shape; see there. Arrays rather than Maps so the value serializes. */
 export interface RecordCoreState {
     currentVersion: number | null;
     catalogEpoch: number;
+    schemaEpoch: number;
     manifests: Manifest[];
+    manifestBlocks: ManifestBlockRecord[];
     transactions: TransactionRecord[];
     tables: TableRecord[];
     segments: SegmentRecord[];
@@ -34,6 +89,7 @@ export interface RecordCoreState {
         totalTokens: number;
     }]>]>;
     uniqueKeys: Array<readonly [string, string[]]>;
+    uniqueKeyBuilds: Array<readonly [UniqueKeyBuildRecord, string[][], FinishUniqueKeyBuildInput | null]>;
     tempOwners: TempOwnerRecord[];
 }
 /**
@@ -58,9 +114,12 @@ export interface RecordCoreState {
 export declare class RecordCore {
     #private;
     constructor(physical: PhysicalBlocks);
+    /** Reconstructs and validates time-sensitive pinned-retired quotas after durable recovery. */
+    validatePinnedRetiredLimits(expiresAtCutoff: string): void;
     createTempOwner(record: TempOwnerRecord): void;
     getTempOwner(ownerId: string): TempOwnerRecord | undefined;
-    renewTempOwner(ownerId: string, expectedRevision: number, expiresAt: string): TempOwnerRecord;
+    renewTempOwner(input: RenewTempOwnerInput): TempOwnerRecord;
+    listExpiredTempOwnerPage(expiresAtCutoff: string, afterCursor: string | null, limit: number): StoragePage<string, string>;
     /**
      * Removes the owner record when it is absent or expired, and reports whether the caller
      * should also remove the owner's physical pages. Page bytes are the enclosing store's.
@@ -73,29 +132,19 @@ export declare class RecordCore {
      * expiry sweep can reclaim them.
      */
     listTempOwnerIdsPage(afterOwnerId: string | null, limit: number, extraOwnerIds: Iterable<string>): StoragePage<string, string>;
-    addTable(record: TableRecord): void;
+    addTable(record: TableRecord, options?: CatalogMutationOptions): void;
     getTable(id: string): TableRecord | undefined;
-    updateTable(id: string, expectedRevision: number, update: {
-        columns?: TableColumnRecord[];
-        ftsColumns?: Record<string, FtsColumnIndexRecord> | null;
-        secondaryIndexes?: Record<string, SecondaryIndexRecord> | null;
-        expectedManifestVersion?: {
-            value: number | null;
-        };
-        uniqueKeySeed?: {
-            namespaceId: string;
-            keyTokens: readonly string[];
-        };
-        triggers?: TriggerRecord[] | null;
-    }): TableRecord;
-    removeTable(id: string, expectedRevision: number): void;
+    updateTable(id: string, expectedRevision: number, update: TableRecordUpdate): TableRecord;
+    removeTable(id: string, expectedRevision: number, options?: CatalogMutationOptions): void;
+    dropTable(input: DropTableInput): ManifestSummary;
+    dropTableColumn(input: DropTableColumnInput): ManifestSummary;
     writeFtsBase(tableId: string, columnId: string, input: {
         coversVersion: number;
         chunks: FtsPosting[][];
         totalTokens: number;
     }): void;
     removeFtsColumn(tableId: string, columnId: string): void;
-    readFtsCandidates(tableId: string, columnId: string, terms: readonly FtsPostingQuery[], upToVersion: number): FtsCandidates & {
+    readFtsCandidates(tableId: string, columnId: string, terms: readonly FtsPostingQuery[], upToVersion: number, maxRowIds?: number): FtsCandidates & {
         deltaChunkCount: number;
         totalTokens: number;
         coversVersion: number;
@@ -111,8 +160,9 @@ export declare class RecordCore {
         deltaChunkCount: number;
         deltaTokens: number;
     };
-    readFtsPostings(tableId: string, columnId: string, upToVersion: number): {
+    readFtsPostings(tableId: string, columnId: string, upToVersion: number, maxRowIds?: number, maxRetainedBytes?: number): {
         postings: FtsPosting[];
+        overflow: boolean;
         deltaChunkCount: number;
         coversVersion: number;
         hasBase: boolean;
@@ -130,43 +180,51 @@ export declare class RecordCore {
         job: GarbageCollectionJobRecord;
         prunedManifestVersions: readonly number[];
         reclaimedSegmentIds: readonly string[];
-        reclaimedTransactionIds?: readonly string[];
+        reclaimedBlockIds: readonly string[];
+        reclaimedTransactionIds: readonly string[];
         updatedAt: string;
     }): void;
     getTableByName(name: string): TableRecord | undefined;
     /** For stores that compose lookups over their own overridable methods. */
     getTableIdByName(name: string): string | undefined;
     listTables(): TableRecord[];
-    addSegment(record: SegmentRecord): void;
     getSegment(id: string): SegmentRecord | undefined;
-    listSegments(tableId?: string): SegmentRecord[];
     listSegmentPage(afterId: string | null, limit: number): StoragePage<SegmentRecord, string>;
-    removeSegment(id: string): void;
+    listTableSegmentPage(tableId: string, afterId: string | null, limit: number): StoragePage<SegmentRecord, string>;
+    removeAbortedSegment(id: string, expectedTransactionId: string): boolean;
+    adoptAbortedSegment(input: AdoptAbortedSegmentInput): TransactionRecord;
     reserveRowIds(tableId: string, count: number): RowIdRange;
     reserveAutoIncrement(tableId: string, columnId: string, count: number, atLeast?: bigint): RowIdRange;
     getExistingUniqueKeys(tableId: string, keyTokens: readonly string[]): string[];
+    /** O(1) staged UNIQUE usage for enclosing adapters' cross-accelerator admission. */
+    uniqueKeyBuildStagedUsage(): {
+        bytes: number;
+        entries: number;
+    };
+    beginUniqueKeyBuild(input: BeginUniqueKeyBuildInput): UniqueKeyBuildRecord;
+    getUniqueKeyBuild(buildId: string): UniqueKeyBuildRecord | undefined;
+    renewUniqueKeyBuild(input: RenewUniqueKeyBuildInput): UniqueKeyBuildRecord;
+    appendUniqueKeyBuildChunk(input: AppendUniqueKeyBuildChunkInput): UniqueKeyBuildRecord;
+    finishUniqueKeyBuild(input: FinishUniqueKeyBuildInput): TableRecord;
+    abortUniqueKeyBuild(input: AbortUniqueKeyBuildInput): boolean;
     getCurrentManifestVersion(): number | null;
     getCatalogProbe(): CatalogProbe;
-    getQueryCatalogState(tableNames: readonly string[]): QueryCatalogState;
+    hasManifestBlocks(version: number | null, ids: readonly string[]): boolean[];
+    listManifestBlockPage(input: ListManifestBlockPageInput): ManifestBlockPage;
+    listRetiredManifestBlockPage(input: ListRetiredManifestBlockPageInput): ManifestBlockPage;
     getCurrentManifest(): Manifest | undefined;
     getManifest(version: number): Manifest | undefined;
-    listManifests(): Manifest[];
     listManifestPage(afterVersion: number | null, limit: number): StoragePage<Manifest, number>;
-    /**
-     * RecordCore keeps resolved manifests. A tombstone below the first readable manifest is no
-     * longer needed for delta resolution, but its narrowed block list remains the collector's
-     * durable discovery record until every named payload has actually gone. Deleting it sooner
-     * loses garbage left behind by a bounded planning pass.
-     */
-    removePrunedManifestRecords(): number[];
-    publishManifest(input: PublishManifestInput): Manifest;
+    /** Removes only bounded summary tombstones; block discovery lives in provenance intervals. */
+    removePrunedManifestRecords(maxItems: number): number;
     beginTransaction(input: BeginTransactionInput): BeginTransactionResult;
     createTransaction(record: TransactionRecord): void;
     getTransaction(id: string): TransactionRecord | undefined;
     getTransactions(ids: readonly string[]): Array<TransactionRecord | undefined>;
-    listTransactions(): TransactionRecord[];
     listTransactionPage(afterId: string | null, limit: number): StoragePage<TransactionRecord, string>;
     updateTransaction(id: string, expectedRevision: number, update: TransactionRecordUpdate): TransactionRecord;
+    renewTransaction(input: RenewTransactionInput): boolean;
+    abortTransactionIfExpired(input: AbortTransactionIfExpiredInput): TransactionRecord | undefined;
     /**
      * Validates and applies the record half of staging: the journal update and the segment
      * records. Block bytes are the enclosing store's to write — after this returns, in the same
@@ -179,7 +237,16 @@ export declare class RecordCore {
          * the check would misread them as duplicates.
          */
         blocksPrevalidated?: boolean;
+        /** Exact persisted byte lengths when prevalidated adapter bodies omit payload bytes. */
+        blockByteLengths?: ReadonlyMap<string, number>;
     }): TransactionRecord;
+    /**
+     * Runs the complete staging preflight without changing record state. Persistent adapters use
+     * this before allocating payload storage; the real apply repeats it under the same writer lock.
+     */
+    preflightTransactionArtifactStage(input: StageTransactionArtifactsInput): void;
+    /** Validates and applies the record/segment half of an atomic savepoint rewind. */
+    rollbackTransactionArtifacts(input: RollbackTransactionArtifactsInput): TransactionRecord;
     commitTransaction(input: CommitTransactionInput): ManifestSummary;
     /**
      * The single-shot write: begin or continue a transaction, journal the artifacts, and commit
@@ -190,24 +257,37 @@ export declare class RecordCore {
     writeTransaction(input: WriteTransactionInput, options?: {
         /** As on `stageTransactionArtifacts`: the enclosing store already checked the block ids. */
         blocksPrevalidated?: boolean;
+        /** Exact persisted lengths when an adapter replays placement-only block bodies. */
+        blockByteLengths?: ReadonlyMap<string, number>;
+        /** Exact persisted checksums when an adapter replays placement-only block bodies. */
+        blockChecksums?: ReadonlyMap<string, number>;
     }): ManifestSummary;
+    /** Complete, non-mutating preflight used before a persistent adapter allocates block bytes. */
+    preflightWriteTransaction(input: WriteTransactionInput): void;
     createLease(record: LeaseRecord): void;
     getLease(id: string): LeaseRecord | undefined;
     listLeases(): LeaseRecord[];
-    renewLease(id: string, expectedRevision: number, expiresAt: string): LeaseRecord;
-    moveLease(id: string, expectedRevision: number, manifestVersion: number | null, expiresAt: string): LeaseRecord;
+    listExpiredLeasePage(expiresAtCutoff: string, afterCursor: string | null, limit: number): StoragePage<LeaseRecord, string>;
+    renewLease(input: RenewLeaseInput): LeaseRecord;
+    moveLease(input: MoveLeaseInput): LeaseRecord;
     removeLeaseIfExpired(id: string, expectedRevision: number, expiresAtCutoff: string): boolean;
-    removeLease(id: string): void;
+    removeLease(input: {
+        id: string;
+        ownerId: string;
+    }): boolean;
     createCompactionJob(record: CompactionJobRecord): void;
     getCompactionJob(id: string): CompactionJobRecord | undefined;
     listCompactionJobs(tableId?: string): CompactionJobRecord[];
     listCompactionJobPage(afterId: string | null, limit: number): StoragePage<CompactionJobRecord, string>;
     updateCompactionJob(id: string, expectedRevision: number, update: CompactionJobRecordUpdate): CompactionJobRecord;
     cancelCompactionJob(id: string, expectedRevision: number, cancelledAt: string): CompactionJobRecord;
-    removeCompactionJob(id: string): void;
+    removeCompactionJob(id: string): boolean;
+    canRemoveCompactionJob(id: string): boolean;
     createGarbageCollectionJob(input: CreateGarbageCollectionJobInput): GarbageCollectionJobRecord;
+    updateGarbageCollectionPlanning(input: UpdateGarbageCollectionPlanningInput): GarbageCollectionJobRecord;
     getGarbageCollectionJob(id: string): GarbageCollectionJobRecord | undefined;
     listGarbageCollectionJobs(): GarbageCollectionJobRecord[];
+    listGarbageCollectionJobPage(afterId: string | null, limit: number): StoragePage<GarbageCollectionJobRecord, string>;
     /**
      * Advances the job and mutates every record it reclaims. Physical block bytes are the
      * caller's to delete afterwards, from the result's `reclaimedBlockIds` — in the same atomic
@@ -216,32 +296,55 @@ export declare class RecordCore {
     runGarbageCollectionStep(input: RunGarbageCollectionStepInput): GarbageCollectionStepResult;
     removeGarbageCollectionJob(id: string): void;
     /**
-     * Copies the current version out as a portable snapshot. The caller provides the block bytes
-     * and the atomicity — run this where no commit can interleave.
+     * Streams the canonical metadata half of a framed snapshot while the enclosing adapter holds
+     * its writer queue. The iterator never builds a database-sized array: ordered indexes yield
+     * one record at a time and UNIQUE membership is split into bounded immutable generations.
+     * Posting generations are substrate-specific (OPFS keeps bases outside this core) and are
+     * therefore emitted by the adapter after these five record families.
      *
-     * Only blocks the current manifest still points at are copied, which drops every superseded
-     * block a compaction left behind, and only full-text bases that already cover this exact
-     * version are carried; any other indexed column is exported as `invalid` so the loaded
-     * database rebuilds it. That costs a rebuild, never a wrong answer — the index is a pruning
-     * accelerator and the scan re-verifies every candidate.
+     * @internal The returned records alias immutable-at-the-call-boundary core state. Exhaust the
+     * iterator before releasing the enclosing writer lock.
      */
-    exportSnapshot(readBlockBytes: (id: string) => Uint8Array | undefined): DatabaseSnapshot;
+    snapshotFrameMetadataItems(): IterableIterator<SnapshotCatalogItem | SnapshotSegmentItem | SnapshotTransactionItem | SnapshotUniqueItem>;
     /**
-     * The record half of `exportSnapshot`, for stores whose block bytes need asynchronous reads:
-     * capture the records synchronously at one version, then read the immutable (and pinned)
-     * block files at leisure.
+     * Streams complete current posting generations in canonical storage-column/term order.
+     * The merge retains only one term's row map and one bounded output chunk; it never builds a
+     * second database-sized postings array. A cheap first pass derives exact descriptor totals,
+     * then a second pass yields the immutable chunks.
+     *
+     * @internal Memory-backed framed snapshot export. OPFS streams its extent-backed bases.
      */
-    exportSnapshotRecords(): {
-        records: Omit<DatabaseSnapshot, "blocks">;
-        blockIds: string[];
+    snapshotFramePostingItems(): IterableIterator<SnapshotPostingItem>;
+    /** Exact bounded snapshot block summary; payload IDs remain in the provenance page index. */
+    snapshotFrameManifest(): ManifestSummary;
+    /** O(1) counters for diagnostics; callers never need to clone the full durable state. */
+    storageRecordStats(): {
+        manifestCount: number;
+        transactionCount: number;
+        segmentCount: number;
+        tableCount: number;
+        leaseCount: number;
+        compactionJobCount: number;
+        garbageCollectionJobCount: number;
+        rowCounterCount: number;
+        autoIncrementCounterCount: number;
+        ftsBaseCount: number;
+        ftsDeltaCount: number;
+        uniqueNamespaceCount: number;
+        uniqueKeyBuildCount: number;
+        tempOwnerCount: number;
+        liveBlockCount: number;
+        liveBlockBytes: number;
     };
-    /** Refuses to load over an existing database; see `loadSnapshot` for the load itself. */
-    importSnapshot(snapshot: DatabaseSnapshot, storeBlockBytes: (id: string, bytes: Uint8Array) => void): void;
-    loadSnapshot(snapshot: DatabaseSnapshot, storeBlockBytes: (id: string, bytes: Uint8Array) => void): void;
-    /** The record half of a snapshot load; block bytes are the caller's, ids theirs to name. */
-    loadSnapshotRecords(snapshot: Omit<DatabaseSnapshot, "blocks"> & {
-        blocks?: undefined;
-    }, blockIds: readonly string[]): void;
+    /**
+     * Atomically promotes one already-decoded framed snapshot generation. The caller supplies a
+     * streaming iterable over metadata pages and the final physical block identities; this method
+     * builds a disposable core, validates every cross-reference, then swaps state only after the
+     * complete generation proves self-consistent.
+     *
+     * @internal Framed adapters call this only at the durable finish boundary.
+     */
+    loadSnapshotFrameItems(header: SnapshotFrameStreamHeader, items: Iterable<SnapshotMetadataItem>, blocks: Iterable<Pick<ManifestBlockRecord, "blockId" | "byteLength" | "checksum">>): void;
     /**
      * The complete record state as one value — the checkpoint payload of a log-structured store.
      * Everything `load` needs to reproduce this core exactly, including operational state the
@@ -258,9 +361,19 @@ export declare class RecordCore {
     load(state: RecordCoreState): void;
 }
 export declare function validateId(id: string): void;
+/** Validates payload ownership at the public storage boundary without copying the hot path. */
+export declare function validateBlockWriteBytes(bytes: unknown): asserts bytes is Uint8Array;
+export declare function validateFtsBaseInput(input: {
+    coversVersion: number;
+    chunks: FtsPosting[][];
+    totalTokens: number;
+}, label: string): void;
+/** Validates each canonical term-sorted postings chunk without copying it. */
+export declare function validateFtsPostingChunks(chunks: unknown, label: string): number;
+export declare function validateSegmentRuntimeRecord(value: unknown, label: string): SegmentRecord;
 export declare function validateAutoIncrementReservation(count: number, atLeast: bigint | undefined): void;
 export declare function validateBeginTransactionInput(input: BeginTransactionInput): void;
 export declare function validateLeaseExpiration(expiresAt: string): void;
 export declare function validateTempRunPage(page: TempRunPage): void;
 export declare function validateTempRunPageIdentity(ownerId: string, runId: string, pageIndex: number): void;
-//# sourceMappingURL=record-core.d.ts.map
+export {};