@ahmadmoussawi/webdb 0.0.0-stage → 0.1.1

package/dist/host/storage/opfs.d.ts

@@ -0,0 +1,31 @@
+import { IVfsAdapter } from './vfs.js';
+export declare class OpfsVfsAdapter implements IVfsAdapter {
+    readonly name: "opfs";
+    readonly isSynchronous: boolean;
+    private dbName;
+    private rootDir;
+    private dbFileHandle;
+    private walFileHandle;
+    private dbSyncHandle;
+    private walSyncHandle;
+    constructor(dbName: string);
+    private initHandles;
+    readPage(pageId: number): Promise<Uint8Array | null>;
+    writePage(pageId: number, data: Uint8Array): Promise<void>;
+    writePages(pages: Array<{
+        pageId: number;
+        data: Uint8Array;
+    }>): Promise<void>;
+    flush(): Promise<void>;
+    truncate(pageCount: number): Promise<void>;
+    readWalHeader(): Promise<Uint8Array | null>;
+    writeWalHeader(header: Uint8Array): Promise<void>;
+    readWalFrame(frameIndex: number): Promise<Uint8Array | null>;
+    readWalFrames(startFrameIndex: number, maxFrames?: number): Promise<Uint8Array[]>;
+    appendWalFrames(frames: Uint8Array[]): Promise<void>;
+    flushWal(): Promise<void>;
+    truncateWal(frameIndex: number): Promise<void>;
+    getWalFrameCount(): Promise<number>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=opfs.d.ts.map

package/dist/host/storage/opfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opfs.d.ts","sourceRoot":"","sources":["../../../src/host/storage/opfs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,qBAAa,cAAe,YAAW,WAAW;IAChD,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,aAAa,CAAqC;IAG1D,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,aAAa,CAAa;gBAEtB,MAAM,EAAE,MAAM;YAKZ,WAAW;IAqBnB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmBpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc1C,aAAa,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAe3C,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjD,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkB5D,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAcjF,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAanC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAa7B"}

package/dist/host/storage/vfs.d.ts

@@ -0,0 +1,36 @@
+export interface IVfsAdapter {
+    readonly name: 'memory' | 'opfs' | 'idb';
+    readonly isSynchronous: boolean;
+    /** Reads a 4KB page from storage into a Uint8Array */
+    readPage(pageId: number): Promise<Uint8Array | null>;
+    /** Writes a 4KB page from memory to persistent storage */
+    writePage(pageId: number, data: Uint8Array): Promise<void>;
+    /** Atomically commits a batch of dirty pages or WAL frames */
+    writePages(pages: Array<{
+        pageId: number;
+        data: Uint8Array;
+    }>): Promise<void>;
+    /** Flushes all in-flight writes durably to persistent storage */
+    flush(): Promise<void>;
+    /** Truncates the storage file/store to the specified page count */
+    truncate(pageCount: number): Promise<void>;
+    /** Reads the 32-byte WAL file header. Returns null if WAL is empty or does not exist. */
+    readWalHeader(): Promise<Uint8Array | null>;
+    /** Writes or overwrites the 32-byte WAL file header */
+    writeWalHeader(header: Uint8Array): Promise<void>;
+    /** Reads a single 4,128-byte WAL frame (32B header + 4096B page data) by 0-based frame index */
+    readWalFrame(frameIndex: number): Promise<Uint8Array | null>;
+    /** Reads a batch of consecutive 4,128-byte WAL frames starting from frameIndex */
+    readWalFrames(startFrameIndex: number, maxFrames?: number): Promise<Uint8Array[]>;
+    /** Appends one or more 4,128-byte WAL frames to the end of the log */
+    appendWalFrames(frames: Uint8Array[]): Promise<void>;
+    /** Flushes WAL writes durably to persistent storage */
+    flushWal(): Promise<void>;
+    /** Truncates the WAL to the specified frame count (0 resets WAL) */
+    truncateWal(frameIndex: number): Promise<void>;
+    /** Returns the current number of frames in the WAL */
+    getWalFrameCount(): Promise<number>;
+    /** Closes and cleans up storage handles */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=vfs.d.ts.map

package/dist/host/storage/vfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../../../src/host/storage/vfs.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAErD,0DAA0D;IAC1D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D,8DAA8D;IAC9D,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI3C,yFAAyF;IACzF,aAAa,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE5C,uDAAuD;IACvD,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD,gGAAgG;IAChG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE7D,kFAAkF;IAClF,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAElF,sEAAsE;IACtE,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,uDAAuD;IACvD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,oEAAoE;IACpE,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,sDAAsD;IACtD,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC,2CAA2C;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/host/storage/wal_codec.d.ts

@@ -0,0 +1,56 @@
+export declare const WAL_MAGIC_BYTES: Uint8Array<ArrayBuffer>;
+export interface WalFileHeader {
+    walVersion: number;
+    pageSize: number;
+    checkpointSeq: number;
+    salt1: number;
+    salt2: number;
+    checksum: number;
+}
+export interface WalFrameHeader {
+    magic: number;
+    frameType: number;
+    flags: number;
+    txId: number;
+    pageId: number;
+    dbSizePages: number;
+    frameSeq: number;
+    checksum: number;
+}
+export interface WalFrame {
+    header: WalFrameHeader;
+    pageData: Uint8Array;
+}
+/**
+ * Encodes a 32-byte WAL file header.
+ */
+export declare function encodeWalFileHeader(header?: Partial<WalFileHeader>): Uint8Array;
+/**
+ * Decodes and validates a 32-byte WAL file header.
+ */
+export declare function decodeWalFileHeader(bytes: Uint8Array, verifyChecksum?: boolean): WalFileHeader;
+/**
+ * Encodes a single 4,128-byte WAL frame (32-byte header + 4096-byte page payload).
+ */
+export declare function encodeWalFrame(header: Omit<WalFrameHeader, 'magic' | 'checksum'> & {
+    magic?: number;
+    checksum?: number;
+}, pageData?: Uint8Array): Uint8Array;
+/**
+ * Decodes only the 32-byte header of a WAL frame without copying the 4096 page bytes.
+ */
+export declare function decodeWalFrameHeader(frameBytes: Uint8Array): WalFrameHeader;
+/**
+ * Validates a candidate WAL frame without throwing, detecting truncated tails,
+ * magic mismatches, and torn writes / CRC32 bit corruption.
+ */
+export declare function validateWalFrame(frameBytes: Uint8Array): {
+    valid: boolean;
+    reason?: 'truncated' | 'magic_mismatch' | 'checksum_mismatch';
+    header?: WalFrameHeader;
+};
+/**
+ * Decodes and verifies a complete 4,128-byte WAL frame.
+ */
+export declare function decodeWalFrame(frameBytes: Uint8Array, verifyChecksum?: boolean): WalFrame;
+//# sourceMappingURL=wal_codec.d.ts.map

package/dist/host/storage/wal_codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal_codec.d.ts","sourceRoot":"","sources":["../../../src/host/storage/wal_codec.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,eAAe,yBAAuD,CAAC;AAEpF,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,UAAU,CAgCnF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,GAAE,OAAc,GAAG,aAAa,CAyCpG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1F,QAAQ,CAAC,EAAE,UAAU,GACpB,UAAU,CAsCZ;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,cAAc,CAkB3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;IAC9D,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,CAgBA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,GAAE,OAAc,GAAG,QAAQ,CAyB/F"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types/index.js';
+export * from './constants.js';
+export * from './host/storage/index.js';
+export * from './host/driver/index.js';
+export * from './host/compiler/index.js';
+export * from './host/api/index.js';
+export * from './core/index.js';
+export * from './shared/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/layouts/index.d.ts

@@ -0,0 +1,5 @@
+export * from './page_format.ts';
+export * from './syspage_format.ts';
+export * from './pool_format.ts';
+export * from './wal_format.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/layouts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layouts/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/layouts/page_format.d.ts

@@ -0,0 +1,163 @@
+/**
+ * AUTO-GENERATED AT BUILD TIME FROM src/layouts/schemas/page_format.json
+ * DO NOT EDIT MANUALLY. Run 'npm run generate:layouts' to rebuild.
+ */
+/**
+ * ============================================================================
+ * CRITICAL WARNING: FROZEN ON-DISK PAGE FORMAT SPECIFICATION
+ * DO NOT alter the order, types, or byte lengths of existing fields in this
+ * layout! Changing any field offset will invalidate existing binary databases,
+ * break cross-version read compatibility, and result in unrecoverable data
+ * corruption.
+ *
+ * Any future extensions MUST use designated reserved bytes or bump
+ * CURRENT_ENGINE_VERSION and CURRENT_MIN_READ_VERSION.
+ * ============================================================================
+ */
+/**
+ * Standard uniform page size in bytes across the entire database engine (4 KB).
+ * Every page in the database file and buffer pool is rigidly aligned to this size.
+ */
+export declare const PAGE_SIZE = 4096;
+/**
+ * Strict maximum size in bytes allowed for a single serialized row record (2 KB).
+ * Enforces the B-tree invariant that at least two rows fit on a leaf data page
+ * without requiring overflow chaining in the v1 engine.
+ */
+export declare const MAX_ROW_SIZE = 2048;
+/**
+ * 32-bit Word Byte Layout Grid for SLOTTED_PAGE_HEADER:
+ *   Byte 0           Byte 1           Byte 2           Byte 3
+ * +-----------------+-----------------+-----------------+-----------------+
+ * | TYPE (1B)       | FLAGS (1B)      | CELL_COUNT (2B)                   |
+ * +-----------------+-----------------+-----------------------------------+
+ * | CONTENT_OFFSET (2B)               | NEXT_PAGE_ID [0..1]               |
+ * +-----------------------------------+-----------------------------------+
+ * | NEXT_PAGE_ID [2..3]               | FREE_BYTES (2B)                   |
+ * +-----------------------------------+-----------------------------------+
+ * | CHECKSUM (4B)                                                         |
+ * +-----------------------------------------------------------------------+
+ *
+ * Field Details:
+ * +--------+------+----------------+----------+----------------------------------------------+
+ * | Offset | Size | Field Name     | Type     | Description                                  |
+ * +--------+------+----------------+----------+----------------------------------------------+
+ * | 0      | 1B   | TYPE           | uint8_t  | Identifies the page structure and role.      |
+ * | 1      | 1B   | FLAGS          | uint8_t  | Flags and reserved attributes for this page. |
+ * | 2      | 2B   | CELL_COUNT     | uint16_t | Number of active records/cells               |
+ * | 4      | 2B   | CONTENT_OFFSET | uint16_t | Byte offset pointing to the start            |
+ * | 6      | 4B   | NEXT_PAGE_ID   | uint32_t | Multifunctional 32-bit pointer:              |
+ * | 10     | 2B   | FREE_BYTES     | uint16_t | Cumulative count of fragmented               |
+ * | 12     | 4B   | CHECKSUM       | uint32_t | IEEE 802.3 CRC32 checksum computed           |
+ * +--------+------+----------------+----------+----------------------------------------------+
+ * | Total: 16 Bytes                                                                          |
+ * +------------------------------------------------------------------------------------------+
+ */
+/**
+ * Ordered sequence of fields composing the 16-byte header of all standard
+ * data and interior pages (pages 2+).
+ * Defined as an immutable array of `[fieldName, byteSize]` tuples to guarantee
+ * strict byte ordering across all JavaScript/TypeScript runtime engines.
+ */
+export declare const SLOTTED_PAGE_HEADER_FIELDS: readonly [readonly ["TYPE", 1], readonly ["FLAGS", 1], readonly ["CELL_COUNT", 2], readonly ["CONTENT_OFFSET", 2], readonly ["NEXT_PAGE_ID", 4], readonly ["FREE_BYTES", 2], readonly ["CHECKSUM", 4]];
+/**
+ * Total size in bytes of the standard slotted page header (16 bytes).
+ */
+export declare const PAGE_HEADER_SIZE = 16;
+/**
+ * Byte offset 0 (uint8_t): Identifies the page structure and role.
+ * Valid types:
+ * - `0x00` (PAGE_TYPE_FREE): Free/recycled page on the free list.
+ * - `0x02` (PAGE_TYPE_INDEX_INTERIOR): B-tree index interior node.
+ * - `0x05` (PAGE_TYPE_TABLE_INTERIOR): B-tree table interior routing node.
+ * - `0x0A` (PAGE_TYPE_INDEX_LEAF): B-tree index leaf node.
+ * - `0x0C` (PAGE_TYPE_CATALOG_PAGE): Dedicated column catalog page.
+ * - `0x0D` (PAGE_TYPE_LEAF_DATA): Table leaf data page storing rows.
+ */
+export declare const PAGE_HEADER_OFFSET_TYPE = 0;
+/**
+ * Byte offset 1 (uint8_t): Flags and reserved attributes for this page.
+ * Initialized to `0x00` in v1.
+ */
+export declare const PAGE_HEADER_OFFSET_FLAGS = 1;
+/**
+ * Byte offset 2 (uint16_t, little-endian): Number of active records/cells
+ * stored on this page. Also specifies the count of 2-byte slot directory entries.
+ */
+export declare const PAGE_HEADER_OFFSET_CELL_COUNT = 2;
+/**
+ * Byte offset 4 (uint16_t, little-endian): Byte offset pointing to the start
+ * of the lower cell payload boundary. Payloads are allocated from byte 4096
+ * growing upwards toward the slot directory. An empty page has this set to 4096.
+ */
+export declare const PAGE_HEADER_OFFSET_CONTENT_OFFSET = 4;
+/**
+ * Byte offset 6 (uint32_t, little-endian): Multifunctional 32-bit pointer:
+ * - Table Leaf Data (0x0D): Forward sibling pointer (`next_page_id`) linking data pages.
+ * - Table Interior (0x05): Rightmost child pointer (`right_child_page_id`).
+ * - Free Page (0x00): Next pageId on the free list chain (`next_free_page_id`).
+ */
+export declare const PAGE_HEADER_OFFSET_NEXT_PAGE_ID = 6;
+/**
+ * Byte offset 10 (uint16_t, little-endian): Cumulative count of fragmented
+ * unallocated bytes left behind by deleted or shrunk records. This space is
+ * reclaimed when page defragmentation (`page_compact`) is invoked.
+ */
+export declare const PAGE_HEADER_OFFSET_FREE_BYTES = 10;
+/**
+ * Byte offset 12 (uint32_t, little-endian): IEEE 802.3 CRC32 checksum computed
+ * over the entire 4KB page (with bytes 12..15 zeroed during calculation) to detect
+ * torn writes or on-disk storage corruption.
+ */
+export declare const PAGE_HEADER_OFFSET_CHECKSUM = 12;
+/**
+ * 32-bit Word Byte Layout Grid for TABLE_INTERIOR_CELL:
+ *   Byte 0           Byte 1           Byte 2           Byte 3
+ * +-----------------+-----------------+-----------------+-----------------+
+ * | CHILD_PAGE_ID (4B)                                                    |
+ * +-----------------------------------------------------------------------+
+ * | Bytes 4..11 (8B): ROWID (int64_t)                                     |
+ * +-----------------------------------------------------------------------+
+ *
+ * Field Details:
+ * +--------+------+---------------+----------+-------------+
+ * | Offset | Size | Field Name    | Type     | Description |
+ * +--------+------+---------------+----------+-------------+
+ * | 0      | 4B   | CHILD_PAGE_ID | uint32_t |             |
+ * | 4      | 8B   | ROWID         | int64_t  |             |
+ * +--------+------+---------------+----------+-------------+
+ * | Total: 12 Bytes                                        |
+ * +--------------------------------------------------------+
+ */
+/**
+ * Ordered sequence of fields composing a single 12-byte routing cell in a
+ * Table Interior B-tree node (`page_type = 0x05`).
+ */
+export declare const TABLE_INTERIOR_CELL_FIELDS: readonly [readonly ["CHILD_PAGE_ID", 4], readonly ["ROWID", 8]];
+/**
+ * Total size in bytes of a single table interior cell (12 bytes).
+ * Composed of a 4-byte child `page_id` and an 8-byte signed `rowid` separator key.
+ */
+export declare const TABLE_INTERIOR_CELL_SIZE = 12;
+/**
+ * Byte offset 0 within an interior cell (uint32_t, little-endian):
+ * The `page_id` of the child subtree containing keys less than or equal to `rowid`.
+ */
+export declare const TABLE_INTERIOR_CELL_OFFSET_CHILD_PAGE_ID = 0;
+/**
+ * Byte offset 4 within an interior cell (int64_t, little-endian):
+ * The separator `rowid` key. Keys $\le \text{rowid}$ route to `child_page_id`;
+ * keys $> \text{rowid}$ continue searching to the right.
+ */
+export declare const TABLE_INTERIOR_CELL_OFFSET_ROWID = 4;
+/**
+ * Maximum number of 12-byte interior cells that can fit inside one 4KB interior page:
+ * \lfloor(4096 - 16) / (12 + 2)\rfloor = 291 cells (where 2 is the slot directory entry size).
+ */
+export declare const MAX_TABLE_INTERIOR_CELLS = 291;
+/**
+ * Median split index for interior page splits. When splitting a full 291-cell
+ * interior node, entry 145 is promoted to the parent routing node.
+ */
+export declare const TABLE_INTERIOR_SPLIT_INDEX = 145;
+//# sourceMappingURL=page_format.d.ts.map

package/dist/layouts/page_format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page_format.d.ts","sourceRoot":"","sources":["../../src/layouts/page_format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS,OAAO,CAAC;AAE9B;;;;GAIG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAMjC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,wMAQ7B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAGnC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAM9C;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,iEAG7B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAG3C;;;GAGG;AACH,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC"}

package/dist/layouts/pool_format.d.ts

@@ -0,0 +1,126 @@
+/**
+ * AUTO-GENERATED AT BUILD TIME FROM src/layouts/schemas/pool_format.json
+ * DO NOT EDIT MANUALLY. Run 'npm run generate:layouts' to rebuild.
+ */
+/**
+ * Default cache buffer pool size in bytes (4 MB = 1024 * 4096).
+ */
+export declare const DEFAULT_CACHE_SIZE_BYTES = 4194304;
+/**
+ * Default number of page cache slots in the buffer pool (1024).
+ */
+export declare const DEFAULT_SLOT_COUNT = 1024;
+/**
+ * Alias for DEFAULT_SLOT_COUNT (1024).
+ */
+export declare const DEFAULT_PAGE_SLOTS = 1024;
+/**
+ * Default number of hash table buckets for page-to-slot mapping (2048, load factor <= 50%).
+ */
+export declare const DEFAULT_PAGE_TO_SLOT_BUCKETS = 2048;
+/**
+ * Size in bytes of each hash table bucket (uint32 page_id + uint32 slot_idx = 8 bytes).
+ */
+export declare const PAGE_TO_SLOT_BUCKET_SIZE = 8;
+/**
+ * Total size in bytes of the page-to-slot hash table (2048 * 8 = 16 KB).
+ */
+export declare const PAGE_TO_SLOT_SIZE = 16384;
+/**
+ * Size in bytes allocated for VM execution context state (12 KB).
+ */
+export declare const VM_CONTEXT_SIZE = 12288;
+/**
+ * Size in bytes allocated for SQL result row serialization buffer (64 KB).
+ */
+export declare const RESULT_BUFFER_SIZE = 65536;
+/**
+ * Size in bytes allocated for compiled query bytecode instructions (32 KB).
+ */
+export declare const BYTECODE_SIZE = 32768;
+/**
+ * Size in bytes allocated for temporary single-page staging / decompression (4 KB).
+ */
+export declare const PAGE_SCRATCHPAD_SIZE = 4096;
+/**
+ * Padding bytes to align transient execution arena at boundary 0x430000 (61,312 bytes).
+ */
+export declare const ALIGNMENT_PADDING_SIZE = 61312;
+/**
+ * Maximum memory limit in bytes for transient query execution arena (16 MB).
+ */
+export declare const DEFAULT_MAX_QUERY_MEMORY = 16777216;
+/**
+ * Shared Memory Architecture Map (1024 Slots / 4MB Cache Default):
+ * +----------------------+--------+-------------------+------------------------------------------------+
+ * | Memory Address Range | Size   | Region Name       | Description                                    |
+ * +----------------------+--------+-------------------+------------------------------------------------+
+ * | 0x400000..0x400FFF   | 4096B  | SLOT_TO_PAGE      | Array of 1024 uint32 pageIds mapping slot -... |
+ * | 0x401000..0x404FFF   | 16384B | PAGE_TO_SLOT      | Open-addressing hash table (2048 buckets x ... |
+ * | 0x405000..0x40507F   | 128B   | DIRTY_MASK        | Bitmask (128 bytes = 1024 bits) tracking di... |
+ * | 0x405080..0x40807F   | 12288B | VM_CONTEXT        | Execution context frames for the SQL VM.       |
+ * | 0x408080..0x41807F   | 65536B | RESULT_BUFFER     | Output buffer for query result rows.           |
+ * | 0x418080..0x42007F   | 32768B | BYTECODE          | Instruction buffer for compiled bytecode ro... |
+ * | 0x420080..0x42107F   | 4096B  | PAGE_SCRATCHPAD   | Staging buffer for page compression or I/O ... |
+ * | 0x421080..0x42FFFF   | 61312B | ALIGNMENT_PADDING | Padding aligning transient arena to 0x430000.  |
+ * +----------------------+--------+-------------------+------------------------------------------------+
+ * | Arena Start: 0x430000 | Total Regions: 196608 Bytes                                                |
+ * +----------------------------------------------------------------------------------------------------+
+ */
+export declare const DEFAULT_BUFFER_POOL_REGIONS: readonly [readonly ["SLOT_TO_PAGE", 4096], readonly ["PAGE_TO_SLOT", 16384], readonly ["DIRTY_MASK", 128], readonly ["VM_CONTEXT", 12288], readonly ["RESULT_BUFFER", 65536], readonly ["BYTECODE", 32768], readonly ["PAGE_SCRATCHPAD", 4096], readonly ["ALIGNMENT_PADDING", 61312]];
+/**
+ * Byte offset 0x400000: Array of 1024 uint32 pageIds mapping slot -> pageId.
+ */
+export declare const SLOT_TO_PAGE_OFFSET = 4194304;
+/**
+ * Byte offset 0x401000: Open-addressing hash table (2048 buckets x 8B) mapping pageId -> slot.
+ */
+export declare const PAGE_TO_SLOT_OFFSET = 4198400;
+/**
+ * Byte offset 0x405000: Bitmask (128 bytes = 1024 bits) tracking dirty slots.
+ */
+export declare const DIRTY_MASK_OFFSET = 4214784;
+/**
+ * Byte offset 0x405080: Execution context frames for the SQL VM.
+ */
+export declare const VM_CONTEXT_OFFSET = 4214912;
+/**
+ * Byte offset 0x408080: Output buffer for query result rows.
+ */
+export declare const RESULT_BUFFER_OFFSET = 4227200;
+/**
+ * Byte offset 0x418080: Instruction buffer for compiled bytecode routines.
+ */
+export declare const BYTECODE_OFFSET = 4292736;
+/**
+ * Byte offset 0x420080: Staging buffer for page compression or I/O reassembly.
+ */
+export declare const PAGE_SCRATCHPAD_OFFSET = 4325504;
+/**
+ * Byte offset 0x421080: Padding aligning transient arena to 0x430000.
+ */
+export declare const ALIGNMENT_PADDING_OFFSET = 4329600;
+/**
+ * Byte offset 0x430000: Start of dynamic transient query execution arena.
+ */
+export declare const TRANSIENT_ARENA_OFFSET = 4390912;
+/**
+ * Total buffer pool and shared Wasm memory allocation in bytes (20.1875 MB).
+ */
+export declare const TOTAL_MEMORY_BYTES = 21168128;
+/**
+ * Computes memory layout offsets for arbitrary slot counts.
+ */
+export declare function computeBufferPoolOffsets(slotCount: number, _maxQueryMemory?: number): {
+    slotsEndOffset: number;
+    slotToPageOffset: number;
+    pageToSlotOffset: number;
+    pageToSlotBuckets: number;
+    dirtyMaskOffset: number;
+    vmContextOffset: number;
+    resultBufferOffset: number;
+    bytecodeOffset: number;
+    pageScratchpadOffset: number;
+    transientArenaOffset: number;
+};
+//# sourceMappingURL=pool_format.d.ts.map

package/dist/layouts/pool_format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool_format.d.ts","sourceRoot":"","sources":["../../src/layouts/pool_format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;GAEG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,wRAS9B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,MAAiC;;;;;;;;;;;EAgDnD"}