bun-shared-memory 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.7] - 2026-11-02
+
+### Added
+
+- Keep the Index Table in a single growable `SharedArrayBuffer` (capped at
+  4 GiB) instead of the chunked logic, so it stays contiguous and cheap to
+  address. `SharedMemoryOptions.indexTableMaxByteLength` configures its cap
+  (default 4 GiB).
+- `maxTotalBytes` now caps the combined physical size of DataTable,
+  StringTable, and ArrayTable only (the Index Table is excluded). The budget
+  is enforced by an atomic `SharedBudget` counter shared across workers that
+  reserves memory before each chunk growth, so the three tables cannot exceed
+  the limit even when multiple workers write concurrently.
+- Enforce size limits regardless of the configured values: `chunkSize` is at
+  least 4 MiB, `maxTotalBytes`/`maxByteLength` are at least 32 MiB, and
+  `chunkSize` is raised as needed so no table needs more than 1024 chunks.
+  `SharedMemory.maxByteLength` and `SharedMemory.maxTotalBytes` are now public
+  read-only fields.
+
+### Performance
+
+- Reclaim memory from inactive chunks after defragmentation. A
+  `SharedArrayBuffer` cannot be shrunk, so `GrowableBuffer` replaces each
+  inactive chunk with a fresh 4-byte `SharedArrayBuffer`, releasing the old
+  full-size buffer so its memory is freed. `defragment()` returns the new
+  chunk lists and the main thread broadcasts them to workers via a
+  `__chunkUpdate` message; workers apply them with `applyChunkUpdate()`. This
+  only runs during defragmentation (rare), so the hot path is unaffected.
+- Optimize the budget write hot path: `GrowableBuffer` tracks
+  `nextChunkToActivate` (the first not-yet-active chunk) so `ensureCapacity`
+  only activates new chunks instead of re-scanning every already-active chunk
+  on each write (was O(n) per write as the dataset grew). Writes ~9% faster.
+
+### Changed
+
+- Stabilize the real-world benchmark against CPU contention. The shared-memory
+  methodology finishes in tens of milliseconds, so it is sensitive to load
+  from other processes (IDE, language servers). Each worker now runs several
+  measured samples (default 5) and reports its fastest; each methodology is
+  run several times (default 3) and the fastest run is kept. Because
+  contention can only slow a run down, the minimum is the best estimate of
+  true throughput.
+
+### Fixed
+
+- Resolve chunk offsets with an unsigned right shift (`offset >>> chunkShift`)
+  instead of a signed one. A signed 32-bit shift turns offsets at or above
+  2 GiB negative, so reads/writes past 2 GiB (e.g. in a >4 GiB chunked buffer)
+  hit the wrong chunk or threw. The Index Table and the Data/String/Array
+  tables can now be addressed at any offset below the 4 GiB single-SAB cap.
+  Reported by [mizulu](https://github.com/mizulu).
+
 ## [0.1.6] - 2026-11-02
 
 ### Added
@@ -120,6 +172,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - O(1) in-place `push`/`pop` with capacity-based array growth.
 - Benchmarks for all data types vs native.
 
+[0.1.7]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.3...v0.1.4

package/README.md

@@ -37,20 +37,21 @@ is benchmarked sequentially with 4 workers. See
 [`bench/real-world/README.md`](bench/real-world/README.md) for setup.
 
 Measured on Linux (Bun 1.4.4, 100,000 requests per methodology, sorted by
-speed; MySQL/Redis benchmarked over both TCP and Unix socket):
+speed; MySQL/Redis benchmarked over both TCP and Unix socket; each methodology
+is the minimum over 3 runs × 5 samples to filter CPU-contention noise):
 
 | Methodology | Transport | Requests | Elapsed (ms) | req/s      | vs. shared |
 |-------------|-----------|----------|--------------|------------|------------|
-| `shared`    | —         | 100,000  | 52           | 1,925,042  | —          |
-| `sqlite`    | —         | 100,000  | 187          | 535,469    | 3.6× slower |
-| `redis`     | socket    | 100,000  | 1,688        | 59,233     | 32.5× slower |
-| `mysql`     | socket    | 100,000  | 1,823        | 54,861     | 35.1× slower |
-| `redis`     | tcp       | 100,000  | 2,863        | 34,923     | 55.1× slower |
-| `mysql`     | tcp       | 100,000  | 3,281        | 30,476     | 63.2× slower |
-
-Shared memory is the fastest by a wide margin: ~3.6× faster than a live SQLite
-read and ~33–63× faster than live MySQL/Redis reads. Unix sockets are
-significantly faster than TCP for MySQL/Redis (~1.7×), but both remain far
+| `shared`    | —         | 100,000  | 21           | 4,876,492  | —          |
+| `sqlite`    | —         | 100,000  | 188          | 531,116    | 9.2× slower |
+| `redis`     | socket    | 100,000  | 1,262        | 79,229     | 61.5× slower |
+| `mysql`     | socket    | 100,000  | 1,605        | 62,322     | 78.2× slower |
+| `redis`     | tcp       | 100,000  | 2,817        | 35,497     | 137.4× slower |
+| `mysql`     | tcp       | 100,000  | 2,976        | 33,602     | 145.1× slower |
+
+Shared memory is the fastest by a wide margin: ~9.2× faster than a live SQLite
+read and ~61–145× faster than live MySQL/Redis reads. Unix sockets are
+significantly faster than TCP for MySQL/Redis (~1.8×), but both remain far
 slower than shared memory.
 
 ## ✨ Features
@@ -305,22 +306,24 @@ A complete runnable example is in [`examples/worker/`](examples/worker/).
 
 ## Memory budget
 
-Shared memory is split across several growable `SharedArrayBuffer`s (the
-index, data, string, and array tables; each key's version counter lives in its
-index entry). A single `SharedArrayBuffer` can be at most **4 GiB**. By default
-each buffer grows independently up to its own `maxByteLength`, so the _total_
-memory can be several times that.
+The Index Table (including each key's version counter) uses one growable
+`SharedArrayBuffer`, capped at **4 GiB** by default (configurable via
+`indexTableMaxByteLength`). The DataTable, StringTable, and ArrayTable use
+chunks and can individually exceed 4 GiB. By default each table grows up to
+its own `maxByteLength`, so the _total_ memory can be several times that.
 
 Configure the buffers when calling `init()` — pass `initialSize` (each
-buffer's starting size, avoiding a grow on first use) and `maxByteLength`
-(each buffer's cap). To cap the **total** memory across all buffers, pass
-`maxTotalBytes`:
+table's starting size, avoiding a grow on first use) and `maxByteLength`
+(each table's cap). To cap the combined physical memory of DataTable,
+StringTable, and ArrayTable, pass `maxTotalBytes`. The Index Table is excluded
+from this budget. Its growth and chunk growth in workers reserve memory from
+the same atomic budget before allocating, so the three tables cannot exceed it.
 
 ```ts
 import { init } from "bun-shared-memory";
 
-// Each buffer starts at 64 KiB and grows up to 4 GiB; the sum of all buffers'
-// physical sizes is additionally capped at 4 GiB (maxTotalBytes).
+// The Index Table grows up to 4 GiB independently. DataTable, StringTable, and
+// ArrayTable together are capped at 4 GiB.
 await init({
   initialSize: 64 * 1024,
   maxByteLength: 4 * 1024 * 1024 * 1024,
@@ -328,14 +331,24 @@ await init({
 });
 ```
 
-`maxTotalBytes` caps the **sum** of all buffers' physical sizes, so the total
-stays within the budget. If a write would exceed the budget, a `RangeError` is
-thrown. Without `maxTotalBytes`, each buffer simply grows up to its own
-`maxByteLength`.
+`maxTotalBytes` caps the **sum** of the physical sizes of DataTable,
+StringTable, and ArrayTable, including across workers. If a write would exceed
+the budget, a `RangeError` is thrown before the chunk grows. Without
+`maxTotalBytes`, each table simply grows up to its own `maxByteLength`.
 
-The budget is shared dynamically — buffers grow as needed, but only while the
-sum of all buffers stays within `maxTotalBytes`. If a write would exceed the
-budget, a `RangeError` is thrown.
+### Size limits
+
+The following limits are enforced regardless of the configured values:
+
+- **`chunkSize` is at least 4 MiB.** A smaller value is raised to 4 MiB.
+- **`maxTotalBytes` / `maxByteLength` are at least 32 MiB.** A smaller value
+  is raised to 32 MiB.
+- **No table uses more than 1024 chunks.** `chunkSize` is raised as needed so
+  that `ceil(maxByteLength / chunkSize) ≤ 1024` (e.g. an 8 GiB table with a
+  4 MiB chunk would need 2048 chunks, so the chunk size is raised to 8 MiB).
+
+These keep the chunk count bounded (so the pre-allocated chunk list stays
+small) and avoid pathological tiny chunks.
 
 ## Array capacity
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "sideEffects": false,

package/src/growable-buffer.ts

@@ -1,52 +1,77 @@
 /**
  * Shared memory budget shared across multiple GrowableBuffers.
  *
- * Tracks the sum of the physical sizes of all participating buffers so a
- * caller can cap the *total* memory used by a set of buffers, rather than
- * capping each buffer independently. Growth is only allowed if the new total
- * stays within the budget.
+ * Tracks the combined physical size of DataTable, StringTable, and ArrayTable.
+ * The counter is shared across workers so each growth reserves against the
+ * same limit.
  */
 export class SharedBudget {
-  private total = 0;
+  private readonly used: BigInt64Array;
 
-  constructor(private readonly max: number) {}
+  constructor(
+    private readonly max: number,
+    buffer = new SharedArrayBuffer(BigInt64Array.BYTES_PER_ELEMENT),
+  ) {
+    this.used = new BigInt64Array(buffer);
+  }
+
+  get buffer(): SharedArrayBuffer {
+    return this.used.buffer as SharedArrayBuffer;
+  }
 
   /** Record a buffer's initial physical size. */
   add(size: number): void {
-    this.total += size;
-    if (this.total > this.max) {
+    if (!this.tryReserve(size)) {
+      const total = Atomics.load(this.used, 0) + BigInt(size);
       throw new RangeError(
-        `Shared memory budget exceeded: initial buffers total ${this.total} bytes but the budget is ${this.max}`,
+        `Shared memory budget exceeded: initial buffers total ${total} bytes but the budget is ${this.max}`,
       );
     }
   }
 
   /**
-   * Attempt to grow a buffer from `oldSize` to `newSize`. Returns true and
-   * updates the total if the new total stays within the budget, false
-   * otherwise (the caller must not grow).
+   * Atomically reserve physical memory shared by all tables and workers.
    */
-  tryGrow(oldSize: number, newSize: number): boolean {
-    const newTotal = this.total - oldSize + newSize;
-    if (newTotal > this.max) return false;
-    this.total = newTotal;
-    return true;
+  tryReserve(size: number): boolean {
+    if (size <= 0) return true;
+    const increment = BigInt(size);
+    for (;;) {
+      const current = Atomics.load(this.used, 0);
+      if (current + increment > BigInt(this.max)) return false;
+      if (
+        Atomics.compareExchange(this.used, 0, current, current + increment) ===
+        current
+      ) {
+        return true;
+      }
+    }
+  }
+
+  /**
+   * Release memory reserved for a growth that failed or a reclaimed chunk.
+   */
+  release(size: number): void {
+    if (size <= 0) return;
+    const decrement = BigInt(size);
+    for (;;) {
+      const current = Atomics.load(this.used, 0);
+      const next = current > decrement ? current - decrement : 0n;
+      if (Atomics.compareExchange(this.used, 0, current, next) === current) {
+        return;
+      }
+    }
   }
 }
 
 /**
- * Growable shared memory backed by one or more SharedArrayBuffers (chunks).
+ * Growable shared memory backed by one or more SharedArrayBuffers. Chunked
+ * tables split storage across SABs; the Index Table uses one growable SAB.
+ * Offsets are logical and continuous across chunks.
  *
- * A single SharedArrayBuffer can be at most 4 GiB, so a buffer that needs to
- * grow beyond that is split into multiple chunks. Each chunk is its own
- * SharedArrayBuffer (<= `chunkMax` bytes). Offsets are logical and continuous
- * across chunks; access methods resolve an offset into (chunk, chunkOffset).
- *
- * All chunks are pre-allocated at construction with `maxByteLength = chunkSize`
- * but only 4 bytes of actual storage. A chunk is "activated" (grown to its
- * full `chunkSize`) on first access. Because `SharedArrayBuffer.grow()` is
- * visible across all workers sharing the buffer, activation needs no
- * postMessage broadcast.
+ * In chunked mode, all chunks are pre-allocated with `maxByteLength =
+ * chunkSize` but only 4 bytes of actual storage. A chunk is activated (grown
+ * to its full size) on first access. Because `SharedArrayBuffer.grow()` is
+ * visible across workers, activation needs no postMessage broadcast.
  */
 interface Chunk {
   buffer: SharedArrayBuffer;
@@ -56,33 +81,97 @@ interface Chunk {
 }
 
 /** Round `n` up to the next power of two (chunk sizes must be powers of two). */
-function nextPowerOfTwo(n: number): number {
+export function nextPowerOfTwo(n: number): number {
   if (n <= 0) return 1;
   let p = 1;
   while (p < n) p <<= 1;
   return p;
 }
 
+export function largestPowerOfTwo(n: number): number {
+  if (n <= 1) return 1;
+  return 2 ** Math.floor(Math.log2(n));
+}
+
 export class GrowableBuffer {
   private chunks: Chunk[] = [];
   private readonly maxByteLength: number;
+  private readonly singleBuffer: boolean;
   /** Fixed size of every chunk (the minimum growth step). */
   readonly chunkSize: number;
   /** log2(chunkSize), used for O(1) offset resolution via bit shifts. */
   private readonly chunkShift: number;
   private readonly budget?: SharedBudget;
-  private used = 0;
+  /**
+   * Shared append cursor (used length). Stored in a SharedArrayBuffer so all
+   * workers that reconstruct this buffer from `fromBuffers()` see the same
+   * used length and append at the correct offset instead of overwriting
+   * existing data at offset 0.
+   */
+  private readonly cursor: BigInt64Array;
+  /** Smallest chunk index that is not yet active (see `activate`). */
+  private nextChunkToActivate = 0;
 
   constructor(
     initialSizeOrBuffer: number | SharedArrayBuffer | SharedArrayBuffer[],
     maxByteLength: number,
     budget?: SharedBudget,
     chunkSize = 32 * 1024 * 1024, // 32 MiB per chunk
+    singleBuffer = false,
+    chargeInitial = true,
+    cursorBuffer?: SharedArrayBuffer,
   ) {
-    this.maxByteLength = maxByteLength;
+    this.singleBuffer = singleBuffer;
     this.budget = budget;
+    this.cursor = new BigInt64Array(
+      cursorBuffer ?? new SharedArrayBuffer(BigInt64Array.BYTES_PER_ELEMENT),
+    );
+    if (singleBuffer && typeof initialSizeOrBuffer !== "number") {
+      const buffer = Array.isArray(initialSizeOrBuffer)
+        ? initialSizeOrBuffer[0]
+        : initialSizeOrBuffer;
+      if (
+        buffer === undefined ||
+        (Array.isArray(initialSizeOrBuffer) && initialSizeOrBuffer.length !== 1)
+      ) {
+        throw new RangeError(
+          "A single-buffer GrowableBuffer requires exactly one SharedArrayBuffer",
+        );
+      }
+      this.maxByteLength = Math.min(
+        buffer.maxByteLength ?? buffer.byteLength,
+        maxByteLength,
+      );
+      this.chunkSize = this.maxByteLength;
+      this.chunkShift = 0;
+      this.chunks.push({
+        buffer,
+        view: new DataView(buffer),
+        active: buffer.byteLength > 4,
+      });
+      if (chargeInitial) this.budget?.add(buffer.byteLength);
+      return;
+    }
+
+    this.maxByteLength = maxByteLength;
     if (typeof initialSizeOrBuffer === "number") {
-      this.chunkSize = Math.min(nextPowerOfTwo(chunkSize), maxByteLength);
+      if (singleBuffer) {
+        const buffer = new SharedArrayBuffer(4, {
+          maxByteLength,
+        });
+        this.chunkSize = maxByteLength;
+        this.chunkShift = 0;
+        this.chunks.push({
+          buffer,
+          view: new DataView(buffer),
+          active: false,
+        });
+        return;
+      }
+      this.chunkSize = Math.min(
+        nextPowerOfTwo(chunkSize),
+        largestPowerOfTwo(maxByteLength),
+      );
       this.chunkShift = Math.log2(this.chunkSize);
       // Pre-allocate all chunks (4 bytes each, growable to chunkSize).
       const chunkCount = Math.max(1, Math.ceil(maxByteLength / this.chunkSize));
@@ -95,6 +184,7 @@ export class GrowableBuffer {
           view: new DataView(buffer),
           active: false,
         });
+        if (chargeInitial) this.budget?.add(buffer.byteLength);
       }
     } else if (Array.isArray(initialSizeOrBuffer)) {
       // Reconstruct from a list of chunks. Use the buffers directly (they are
@@ -110,7 +200,7 @@ export class GrowableBuffer {
           view: new DataView(sab),
           active: sab.byteLength === this.chunkSize,
         });
-        this.budget?.add(sab.byteLength);
+        if (chargeInitial) this.budget?.add(sab.byteLength);
       }
     } else {
       // Reconstruct from a single existing buffer. Use it directly so writes
@@ -124,7 +214,7 @@ export class GrowableBuffer {
         view: new DataView(initialSizeOrBuffer),
         active: initialSizeOrBuffer.byteLength === this.chunkSize,
       });
-      this.budget?.add(initialSizeOrBuffer.byteLength);
+      if (chargeInitial) this.budget?.add(initialSizeOrBuffer.byteLength);
     }
   }
 
@@ -136,20 +226,70 @@ export class GrowableBuffer {
   private activate(index: number): void {
     const chunk = this.chunks[index];
     if (chunk === undefined || chunk.active) return;
-    chunk.buffer.grow(this.chunkSize);
+    if (this.singleBuffer) {
+      return;
+    }
+    const oldSize = chunk.buffer.byteLength;
+    if (oldSize >= this.chunkSize) {
+      chunk.view = new DataView(chunk.buffer);
+      chunk.active = true;
+      this.advanceNextChunkToActivate(index);
+      return;
+    }
+    const growth = this.chunkSize - oldSize;
+    if (this.budget && !this.budget.tryReserve(growth)) {
+      throw new RangeError(
+        `Shared memory budget exceeded: need ${growth} additional bytes`,
+      );
+    }
+    try {
+      chunk.buffer.grow(this.chunkSize);
+    } catch (error) {
+      if (chunk.buffer.byteLength >= this.chunkSize) {
+        this.budget?.release(growth);
+        chunk.view = new DataView(chunk.buffer);
+        chunk.active = true;
+        this.advanceNextChunkToActivate(index);
+        return;
+      }
+      this.budget?.release(growth);
+      throw error;
+    }
     chunk.view = new DataView(chunk.buffer);
     chunk.active = true;
-    this.budget?.add(this.chunkSize);
+    this.advanceNextChunkToActivate(index);
+  }
+
+  /**
+   * Advance `nextChunkToActivate` past `index` while the following chunks are
+   * already active, so `ensureCapacity` never re-scans active chunks.
+   */
+  private advanceNextChunkToActivate(index: number): void {
+    if (index < this.nextChunkToActivate) return;
+    this.nextChunkToActivate = index + 1;
+    while (
+      this.nextChunkToActivate < this.chunks.length &&
+      this.chunks[this.nextChunkToActivate]!.active
+    ) {
+      this.nextChunkToActivate++;
+    }
   }
 
   /** Number of bytes written so far (used length, not buffer capacity). */
   get byteLength(): number {
-    return this.used;
+    return Number(Atomics.load(this.cursor, 0));
+  }
+
+  /** The shared cursor buffer (for export to workers). */
+  get cursorBuffer(): SharedArrayBuffer {
+    return this.cursor.buffer as SharedArrayBuffer;
   }
 
   /** Total logical capacity across all chunks (active or not). */
   get capacity(): number {
-    return this.chunks.length * this.chunkSize;
+    return this.singleBuffer
+      ? this.maxByteLength
+      : this.chunks.length * this.chunkSize;
   }
 
   /** The list of SharedArrayBuffers backing this buffer (for export). */
@@ -157,18 +297,43 @@ export class GrowableBuffer {
     return this.chunks.map((c) => c.buffer);
   }
 
-  /** Number of chunks that have been activated (grown to full size). */
+  /** Number of chunks that have been grown from their initial 4-byte size. */
   get activeChunkCount(): number {
     return this.chunks.reduce((n, c) => n + (c.active ? 1 : 0), 0);
   }
 
+  /**
+   * Replace the chunk list with `newBuffers` (received from the main thread
+   * after a defragmentation broadcast). Each buffer is either a full-size
+   * active chunk or a fresh 4-byte inactive chunk. Used by workers to stay in
+   * sync with the main thread's chunk replacement.
+   */
+  applyChunks(newBuffers: SharedArrayBuffer[]): void {
+    if (this.singleBuffer && newBuffers.length !== 1) {
+      throw new RangeError(
+        "A single-buffer GrowableBuffer requires exactly one SharedArrayBuffer",
+      );
+    }
+    this.chunks = newBuffers.map((sab) => ({
+      buffer: sab,
+      view: new DataView(sab),
+      active: this.singleBuffer
+        ? sab.byteLength > 4
+        : sab.byteLength === this.chunkSize,
+    }));
+    this.nextChunkToActivate = this.firstInactiveChunk();
+  }
+
   /**
    * Resolve a logical offset into (chunk, offset within that chunk). All
    * chunks are the same size, so this is O(1). Activates the chunk if it is
    * not yet active.
    */
   private resolve(offset: number): { chunk: Chunk; off: number } {
-    const index = offset >> this.chunkShift;
+    if (this.singleBuffer) {
+      return { chunk: this.chunks[0]!, off: offset };
+    }
+    const index = offset >>> this.chunkShift;
     const chunk = this.chunks[index];
     if (chunk === undefined) {
       throw new RangeError(`Offset ${offset} is beyond the buffer capacity`);
@@ -184,31 +349,99 @@ export class GrowableBuffer {
         `Shared buffer capacity exceeded: need ${needed} bytes but max is ${this.maxByteLength}`,
       );
     }
+    if (this.singleBuffer) {
+      const chunk = this.chunks[0]!;
+      const oldSize = chunk.buffer.byteLength;
+      if (needed <= oldSize) return;
+      const target = Math.min(
+        this.maxByteLength,
+        Math.max(needed, oldSize * 2),
+      );
+      let growth = target - oldSize;
+      if (this.budget && !this.budget.tryReserve(growth)) {
+        if (target === needed || !this.budget.tryReserve(needed - oldSize)) {
+          throw new RangeError(
+            `Shared memory budget exceeded: need ${needed - oldSize} additional bytes`,
+          );
+        }
+        growth = needed - oldSize;
+      }
+      try {
+        chunk.buffer.grow(oldSize + growth);
+      } catch (error) {
+        this.budget?.release(growth);
+        throw error;
+      }
+      chunk.view = new DataView(chunk.buffer);
+      chunk.active = true;
+      return;
+    }
     // All chunks are pre-allocated; just activate the ones needed to cover
     // `needed`. grow() is visible across workers, so no broadcast is required.
+    // Start from `nextChunkToActivate` so already-active chunks are not
+    // re-scanned on every write (keeps the write hot path O(1) amortized).
     const neededChunks = Math.ceil(needed / this.chunkSize);
-    for (let i = 0; i < neededChunks; i++) {
+    for (let i = this.nextChunkToActivate; i < neededChunks; i++) {
       this.activate(i);
     }
   }
 
   /** Mark `n` bytes as used, after writing them at the current offset. */
   advance(n: number): void {
-    this.used += n;
+    Atomics.add(this.cursor, 0, BigInt(n));
   }
 
   /**
    * Reset the used length to `n` bytes. Used by defragmentation after
    * compacting live data to the front of the buffer. Chunks beyond the
-   * compacted region are marked inactive (their storage is released by the
-   * GC, which replaces them with fresh chunks).
+   * compacted region are marked inactive; their storage is reclaimed by
+   * `releaseInactiveChunks()`.
    */
   reset(n: number): void {
-    this.used = n;
+    Atomics.store(this.cursor, 0, BigInt(n));
+    if (this.singleBuffer) return;
     const neededChunks = Math.ceil(n / this.chunkSize);
-    for (let i = neededChunks; i < this.chunks.length; i++) {
-      this.chunks[i]!.active = false;
+    for (let i = 0; i < this.chunks.length; i++) {
+      const chunk = this.chunks[i]!;
+      chunk.active =
+        i < neededChunks && chunk.buffer.byteLength >= this.chunkSize;
+    }
+    this.nextChunkToActivate = this.firstInactiveChunk();
+  }
+
+  /**
+   * Replace every inactive chunk with a fresh 4-byte SharedArrayBuffer
+   * (growable to `chunkSize`), releasing the old full-size buffer so its
+   * memory can be reclaimed. Returns the new chunk list; the caller must
+   * broadcast it to workers so they see the replacement.
+   *
+   * Because a SharedArrayBuffer cannot be shrunk, reclaiming memory requires
+   * allocating a new buffer. This is only called after defragmentation (rare),
+   * so the resulting broadcast is acceptable.
+   */
+  releaseInactiveChunks(): SharedArrayBuffer[] {
+    if (this.singleBuffer) return this.chunks.map((c) => c.buffer);
+    for (let i = 0; i < this.chunks.length; i++) {
+      const chunk = this.chunks[i]!;
+      if (chunk.active) continue;
+      // Release the old full-size buffer from the budget and replace it with
+      // a fresh 4-byte chunk.
+      this.budget?.release(Math.max(0, chunk.buffer.byteLength - 4));
+      const buffer = new SharedArrayBuffer(4, {
+        maxByteLength: this.chunkSize,
+      });
+      this.chunks[i] = { buffer, view: new DataView(buffer), active: false };
     }
+    this.nextChunkToActivate = this.firstInactiveChunk();
+    return this.chunks.map((c) => c.buffer);
+  }
+
+  /** Index of the first chunk that is not active, or `chunks.length`. */
+  private firstInactiveChunk(): number {
+    for (let i = 0; i < this.chunks.length; i++) {
+      if (!this.chunks[i]!.active) return i;
+    }
+    return this.chunks.length;
   }
 
   // -------------------------------------------------------------------------
@@ -216,7 +449,8 @@ export class GrowableBuffer {
   // -------------------------------------------------------------------------
 
   getInt32(offset: number): number {
-    const index = offset >> this.chunkShift;
+    if (this.singleBuffer) return this.chunks[0]!.view.getInt32(offset, true);
+    const index = offset >>> this.chunkShift;
     this.activate(index);
     return this.chunks[index]!.view.getInt32(
       offset & (this.chunkSize - 1),
@@ -225,7 +459,11 @@ export class GrowableBuffer {
   }
 
   setInt32(offset: number, value: number): void {
-    const index = offset >> this.chunkShift;
+    if (this.singleBuffer) {
+      this.chunks[0]!.view.setInt32(offset, value, true);
+      return;
+    }
+    const index = offset >>> this.chunkShift;
     this.activate(index);
     this.chunks[index]!.view.setInt32(
       offset & (this.chunkSize - 1),
@@ -235,13 +473,18 @@ export class GrowableBuffer {
   }
 
   getUint8(offset: number): number {
-    const index = offset >> this.chunkShift;
+    if (this.singleBuffer) return this.chunks[0]!.view.getUint8(offset);
+    const index = offset >>> this.chunkShift;
     this.activate(index);
     return this.chunks[index]!.view.getUint8(offset & (this.chunkSize - 1));
   }
 
   setUint8(offset: number, value: number): void {
-    const index = offset >> this.chunkShift;
+    if (this.singleBuffer) {
+      this.chunks[0]!.view.setUint8(offset, value);
+      return;
+    }
+    const index = offset >>> this.chunkShift;
     this.activate(index);
     this.chunks[index]!.view.setUint8(offset & (this.chunkSize - 1), value);
   }

package/src/memory.ts

@@ -1,4 +1,8 @@
-import { GrowableBuffer, SharedBudget } from "./growable-buffer.ts";
+import {
+  GrowableBuffer,
+  SharedBudget,
+  nextPowerOfTwo,
+} from "./growable-buffer.ts";
 import { Mutex } from "./mutex.ts";
 
 /**
@@ -30,10 +34,11 @@ import { Mutex } from "./mutex.ts";
  *   [12..15] reserved
  *   then propertyCount * (nameRef(8 bytes) + valueSlot(16 bytes))
  *
- * Index Table entry (12 bytes):
+ * Index Table entry (16 bytes):
  *   [0..3]   key string offset
  *   [4..7]   key string length
  *   [8..11]  data offset (into DataTable)
+ *   [12..15] key version
  */
 
 export const TYPE_NUMBER = 0;
@@ -51,11 +56,19 @@ const INDEX_ENTRY_SIZE = 16;
 const INDEX_HEADER = 4;
 /** Byte offset of the version field within an index entry. */
 const INDEX_VERSION_OFFSET = 12;
+const MAX_INDEX_TABLE_BYTES = 4 * 1024 * 1024 * 1024;
 /** Size of the objectId header at the start of each array block. */
 const ARRAY_HEADER = 4;
 
 const DEFAULT_INITIAL = 1024;
 const DEFAULT_MAX = 64 * 1024 * 1024; // 64 MiB
+const DEFAULT_CHUNK_SIZE = 32 * 1024 * 1024; // 32 MiB per chunk
+/** Minimum size of a single chunk (a chunk is the minimum growth step). */
+const MIN_CHUNK_SIZE = 4 * 1024 * 1024; // 4 MiB
+/** Minimum combined memory budget (maxTotalBytes / maxByteLength). */
+const MIN_MAX_MEMORY = 32 * 1024 * 1024; // 32 MiB
+/** Maximum number of chunks per table (chunkSize must be large enough). */
+const MAX_CHUNKS_PER_TABLE = 1024;
 const DEFAULT_INTERN_CAPACITY = 256;
 const DEFAULT_INTERN_MAX = 1 << 16; // 65536 entries
 
@@ -172,10 +185,20 @@ export function decodeSlot(slot: ValueSlot): unknown {
 
 export interface SharedMemoryOptions {
   initialSize?: number;
+  /** Per-buffer maximum byte length (clamped to at least 32 MiB). */
   maxByteLength?: number;
-  /** Total memory budget shared across all buffers (see below). */
+  /**
+   * Total physical memory budget shared by DataTable, StringTable, and
+   * ArrayTable (clamped to at least 32 MiB).
+   */
   maxTotalBytes?: number;
-  /** Size of each growable chunk (the minimum growth step). Default 32 MiB. */
+  /** Internal worker reconstruction option; normally inferred from buffers. */
+  indexTableMaxByteLength?: number;
+  /**
+   * Size of each growable chunk (the minimum growth step). Default 32 MiB,
+   * clamped to at least 4 MiB and raised as needed so no table needs more
+   * than 1024 chunks.
+   */
   chunkSize?: number;
   lock?: Mutex;
   internCapacity?: number;
@@ -187,6 +210,13 @@ export interface SharedMemoryOptions {
     arrayTable?: SharedArrayBuffer | SharedArrayBuffer[];
     layoutVersion?: SharedArrayBuffer;
     refCount?: SharedArrayBuffer;
+    budget?: SharedArrayBuffer;
+    cursors?: {
+      indexTable?: SharedArrayBuffer;
+      dataTable?: SharedArrayBuffer;
+      stringTable?: SharedArrayBuffer;
+      arrayTable?: SharedArrayBuffer;
+    };
   };
 }
 
@@ -197,11 +227,30 @@ function makeBuffer(
   maxByteLength: number,
   budget?: SharedBudget,
   chunkSize?: number,
+  singleBuffer = false,
+  chargeInitial = true,
+  cursorBuffer?: SharedArrayBuffer,
 ): GrowableBuffer {
   if (buf === undefined) {
-    return new GrowableBuffer(initial, maxByteLength, budget, chunkSize);
+    return new GrowableBuffer(
+      initial,
+      maxByteLength,
+      budget,
+      chunkSize,
+      singleBuffer,
+      chargeInitial,
+      cursorBuffer,
+    );
   }
-  return new GrowableBuffer(buf, maxByteLength, budget, chunkSize);
+  return new GrowableBuffer(
+    buf,
+    maxByteLength,
+    budget,
+    chunkSize,
+    singleBuffer,
+    chargeInitial,
+    cursorBuffer,
+  );
 }
 
 /**
@@ -213,6 +262,12 @@ export class SharedMemory {
   readonly dataTable: GrowableBuffer;
   readonly stringTable: GrowableBuffer;
   readonly arrayTable: GrowableBuffer;
+  /** Per-buffer maximum byte length (clamped to at least 32 MiB). */
+  readonly maxByteLength: number;
+  private readonly indexTableMaxByteLength: number;
+  /** Combined memory budget for Data/String/Array tables, or null if unset. */
+  readonly maxTotalBytes: number | null;
+  private readonly budgetBuffer: SharedArrayBuffer | null;
   /**
    * Cached Int32Array view over the Index Table, used to read/increment each
    * key's version cell (stored as the 4th field of each index entry). Rebuilt
@@ -262,25 +317,59 @@ export class SharedMemory {
 
   constructor(options?: SharedMemoryOptions) {
     const initial = options?.initialSize ?? DEFAULT_INITIAL;
-    // `maxTotalBytes` is a *total* budget shared across all buffers: each
-    // buffer's own maxByteLength is capped at maxTotalBytes, and the sum of
-    // all buffers' physical sizes is additionally capped at maxTotalBytes.
+    // `maxTotalBytes` caps the combined physical size of DataTable,
+    // StringTable, and ArrayTable. IndexTable has its independent 4 GiB cap.
     // Without maxTotalBytes, each buffer grows up to its own maxByteLength.
-    // A single SharedArrayBuffer is limited to 4 GiB, but the chunked
-    // GrowableBuffer splits a buffer across multiple chunks, so a buffer can
-    // exceed 4 GiB.
+    // The Index Table remains a single growable SharedArrayBuffer and is
+    // capped at 4 GiB. The other tables use chunks and can exceed that limit.
     const maxTotal = options?.maxTotalBytes;
-    const perBufferMax = maxTotal ?? options?.maxByteLength ?? DEFAULT_MAX;
-    const budget =
-      maxTotal !== undefined ? new SharedBudget(maxTotal) : undefined;
-    const chunkSize = options?.chunkSize;
+    if (
+      maxTotal !== undefined &&
+      (!Number.isSafeInteger(maxTotal) || maxTotal < 0)
+    ) {
+      throw new RangeError("maxTotalBytes must be a non-negative safe integer");
+    }
+    // Enforce the minimum memory budget: maxTotalBytes / maxByteLength are
+    // never below 32 MiB.
+    const perBufferMax = Math.max(
+      maxTotal ?? options?.maxByteLength ?? DEFAULT_MAX,
+      MIN_MAX_MEMORY,
+    );
+    const indexTableMax = Math.min(
+      options?.indexTableMaxByteLength ?? options?.maxByteLength ?? DEFAULT_MAX,
+      MAX_INDEX_TABLE_BYTES,
+    );
+    // Enforce the chunk-size limits: at least 4 MiB, and large enough that no
+    // table needs more than MAX_CHUNKS_PER_TABLE chunks.
+    const userChunkSize = options?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const chunkSize = Math.max(
+      userChunkSize,
+      MIN_CHUNK_SIZE,
+      nextPowerOfTwo(perBufferMax / MAX_CHUNKS_PER_TABLE),
+    );
     const buffers = options?.buffers;
+    // The budget is the clamped maxTotalBytes (never below MIN_MAX_MEMORY), so
+    // it stays consistent with perBufferMax.
+    const budgetMax = maxTotal !== undefined ? perBufferMax : undefined;
+    const budgetBuffer = buffers?.budget;
+    const budget =
+      budgetMax !== undefined
+        ? new SharedBudget(budgetMax, budgetBuffer)
+        : undefined;
+    const chargeInitial = budgetBuffer === undefined;
+    this.maxByteLength = perBufferMax;
+    this.indexTableMaxByteLength = indexTableMax;
+    this.maxTotalBytes = budgetMax ?? null;
+    this.budgetBuffer = budget?.buffer ?? null;
     this.indexTable = makeBuffer(
       buffers?.indexTable,
       initial,
-      perBufferMax,
-      budget,
+      indexTableMax,
+      undefined,
       chunkSize,
+      true,
+      true,
+      buffers?.cursors?.indexTable,
     );
     this.dataTable = makeBuffer(
       buffers?.dataTable,
@@ -288,6 +377,9 @@ export class SharedMemory {
       perBufferMax,
       budget,
       chunkSize,
+      false,
+      chargeInitial,
+      buffers?.cursors?.dataTable,
     );
     this.stringTable = makeBuffer(
       buffers?.stringTable,
@@ -295,6 +387,9 @@ export class SharedMemory {
       perBufferMax,
       budget,
       chunkSize,
+      false,
+      chargeInitial,
+      buffers?.cursors?.stringTable,
     );
     this.arrayTable = makeBuffer(
       buffers?.arrayTable,
@@ -302,6 +397,9 @@ export class SharedMemory {
       perBufferMax,
       budget,
       chunkSize,
+      false,
+      chargeInitial,
+      buffers?.cursors?.arrayTable,
     );
     this.versionView = new Int32Array(this.indexTable.buffers[0]!);
     this.layoutVersion = new Int32Array(
@@ -319,6 +417,24 @@ export class SharedMemory {
     return this.lock.withLock(fn);
   }
 
+  /**
+   * Apply a buffer update received from the main thread after a
+   * defragmentation pass. Replaces each table's buffers and rebuilds the
+   * version view. Called by workers on the `__chunkUpdate` message.
+   */
+  applyChunkUpdate(buffers: {
+    indexTable: SharedArrayBuffer[];
+    dataTable: SharedArrayBuffer[];
+    stringTable: SharedArrayBuffer[];
+    arrayTable: SharedArrayBuffer[];
+  }): void {
+    this.indexTable.applyChunks(buffers.indexTable);
+    this.dataTable.applyChunks(buffers.dataTable);
+    this.stringTable.applyChunks(buffers.stringTable);
+    this.arrayTable.applyChunks(buffers.arrayTable);
+    this.versionView = new Int32Array(this.indexTable.buffers[0]!);
+  }
+
   /**
    * Attach the reference-counting buffer (5th SAB) to this memory so it is
    * included in `exportBuffers()`. No-op if a buffer is already attached.
@@ -334,8 +450,10 @@ export class SharedMemory {
    * Export all shared buffers (including the lock) so they can be sent to a
    * worker via `postMessage` and reconstructed there with `fromBuffers()`.
    *
-   * Each table is exported as a list of SharedArrayBuffers (chunks), since a
-   * single SharedArrayBuffer is limited to 4 GiB.
+   * Tables are exported as lists for the chunked buffers. The Index Table is
+   * a single growable SharedArrayBuffer, exported as a one-element list. The
+   * optional shared budget counter is included so workers reserve atomically
+   * against the same three-table limit.
    */
   exportBuffers(): {
     indexTable: SharedArrayBuffer[];
@@ -345,6 +463,16 @@ export class SharedMemory {
     layoutVersion: SharedArrayBuffer;
     lock: SharedArrayBuffer;
     refCount: SharedArrayBuffer | null;
+    maxByteLength: number;
+    indexTableMaxByteLength: number;
+    maxTotalBytes: number | null;
+    budget: SharedArrayBuffer | null;
+    cursors: {
+      indexTable: SharedArrayBuffer;
+      dataTable: SharedArrayBuffer;
+      stringTable: SharedArrayBuffer;
+      arrayTable: SharedArrayBuffer;
+    };
   } {
     return {
       indexTable: this.indexTable.buffers,
@@ -354,6 +482,16 @@ export class SharedMemory {
       layoutVersion: this.layoutVersion.buffer as SharedArrayBuffer,
       lock: this.lock.buffer as SharedArrayBuffer,
       refCount: this.refCountBuffer,
+      maxByteLength: this.maxByteLength,
+      indexTableMaxByteLength: this.indexTableMaxByteLength,
+      maxTotalBytes: this.maxTotalBytes,
+      budget: this.budgetBuffer,
+      cursors: {
+        indexTable: this.indexTable.cursorBuffer,
+        dataTable: this.dataTable.cursorBuffer,
+        stringTable: this.stringTable.cursorBuffer,
+        arrayTable: this.arrayTable.cursorBuffer,
+      },
     };
   }
 
@@ -369,8 +507,28 @@ export class SharedMemory {
     layoutVersion: SharedArrayBuffer;
     lock: SharedArrayBuffer;
     refCount?: SharedArrayBuffer | null;
+    maxByteLength?: number;
+    indexTableMaxByteLength?: number;
+    maxTotalBytes?: number | null;
+    budget?: SharedArrayBuffer | null;
+    cursors?: {
+      indexTable?: SharedArrayBuffer;
+      dataTable?: SharedArrayBuffer;
+      stringTable?: SharedArrayBuffer;
+      arrayTable?: SharedArrayBuffer;
+    };
   }): SharedMemory {
+    const indexBuffer = Array.isArray(buffers.indexTable)
+      ? buffers.indexTable[0]
+      : buffers.indexTable;
     return new SharedMemory({
+      maxByteLength: buffers.maxByteLength ?? DEFAULT_MAX,
+      indexTableMaxByteLength:
+        buffers.indexTableMaxByteLength ??
+        indexBuffer?.maxByteLength ??
+        indexBuffer?.byteLength ??
+        DEFAULT_MAX,
+      maxTotalBytes: buffers.maxTotalBytes ?? undefined,
       buffers: {
         indexTable: buffers.indexTable,
         dataTable: buffers.dataTable,
@@ -378,6 +536,8 @@ export class SharedMemory {
         arrayTable: buffers.arrayTable,
         layoutVersion: buffers.layoutVersion,
         refCount: buffers.refCount ?? undefined,
+        budget: buffers.budget ?? undefined,
+        cursors: buffers.cursors,
       },
       lock: new Mutex(buffers.lock),
     });
@@ -798,7 +958,12 @@ export class SharedMemory {
    *
    * Must be called under the shared lock (or on a single thread).
    */
-  defragment(): void {
+  defragment(): {
+    indexTable: SharedArrayBuffer[];
+    dataTable: SharedArrayBuffer[];
+    stringTable: SharedArrayBuffer[];
+    arrayTable: SharedArrayBuffer[];
+  } {
     const stringRemap = new Map<number, number>();
     const arrayRemap = new Map<number, number>();
     const objectRemap = new Map<number, number>();
@@ -964,6 +1129,15 @@ export class SharedMemory {
 
     // Phase 7: Invalidate all per-worker caches.
     this.bumpLayoutVersion();
+
+    // Phase 8: Reclaim memory from inactive chunks (beyond the compacted
+    // region). The Index Table is a single growable SAB and is never replaced.
+    return {
+      indexTable: this.indexTable.releaseInactiveChunks(),
+      dataTable: this.dataTable.releaseInactiveChunks(),
+      stringTable: this.stringTable.releaseInactiveChunks(),
+      arrayTable: this.arrayTable.releaseInactiveChunks(),
+    };
   }
 }
 

package/src/refcount.ts

@@ -161,6 +161,13 @@ export class RefCountCoordinator {
   /** Free-space threshold (fraction of maxByteLength) that triggers defrag. */
   private readonly defragThreshold: number;
   private maintenanceTimer: ReturnType<typeof setInterval> | null = null;
+  /** Called after a defragmentation pass with the new chunk lists. */
+  private readonly onDefragment?: (buffers: {
+    indexTable: SharedArrayBuffer[];
+    dataTable: SharedArrayBuffer[];
+    stringTable: SharedArrayBuffer[];
+    arrayTable: SharedArrayBuffer[];
+  }) => void;
 
   constructor(
     mem: SharedMemory,
@@ -169,9 +176,16 @@ export class RefCountCoordinator {
       defragThreshold?: number;
       autoMaintenance?: boolean;
       maintenanceInterval?: number;
+      onDefragment?: (buffers: {
+        indexTable: SharedArrayBuffer[];
+        dataTable: SharedArrayBuffer[];
+        stringTable: SharedArrayBuffer[];
+        arrayTable: SharedArrayBuffer[];
+      }) => void;
     } = {},
   ) {
     this.mem = mem;
+    this.onDefragment = opts.onDefragment;
     // Reuse the memory's shared refCount buffer if present, so the same SAB is
     // exported to workers; otherwise create a fresh one and attach it to the
     // memory so it can be shared.
@@ -313,7 +327,8 @@ export class RefCountCoordinator {
     this.maintenanceTimer = setInterval(() => {
       this.drainEvents();
       if (this.needsDefrag()) {
-        this.mem.withLock(() => this.mem.defragment());
+        const buffers = this.mem.withLock(() => this.mem.defragment());
+        this.onDefragment?.(buffers);
       }
     }, intervalMs);
     // Unref the timer so it does not keep the process alive. The coordinator

package/src/worker.ts

@@ -130,7 +130,9 @@ export function getDefaultTracker(): RefCountTracker | null {
 function startCoordinator(): void {
   if (coordinator !== null) return;
   const mem = getDefaultMemory();
-  coordinator = new RefCountCoordinator(mem);
+  coordinator = new RefCountCoordinator(mem, undefined, {
+    onDefragment: (buffers) => broadcastChunkUpdate(buffers),
+  });
   unregisterWorkers = coordinator.autoRegister();
 }
 
@@ -156,6 +158,12 @@ let mainListener:
     }) => void)
   | null = null;
 
+/** Live workers on the main thread, for broadcasting chunk updates. */
+const liveWorkers = new Set<{
+  postMessage: (msg: unknown) => void;
+  addEventListener: (type: string, fn: (e: { data: unknown }) => void) => void;
+}>();
+
 /** Main thread: answer each worker's buffer request. */
 function initMain(): void {
   const listener = (worker: {
@@ -165,6 +173,7 @@ function initMain(): void {
       fn: (e: { data: unknown }) => void,
     ) => void;
   }) => {
+    liveWorkers.add(worker);
     worker.addEventListener("message", (e) => {
       const msg = e.data as { __sharedMemoryRequest?: boolean } | undefined;
       if (
@@ -191,6 +200,22 @@ function stopMain(): void {
     process.off("worker", mainListener);
     mainListener = null;
   }
+  liveWorkers.clear();
+}
+
+/**
+ * Broadcast a chunk update (new chunk lists after a defragmentation pass) to
+ * all live workers. Workers apply it via `applyChunkUpdate()`.
+ */
+function broadcastChunkUpdate(buffers: {
+  indexTable: SharedArrayBuffer[];
+  dataTable: SharedArrayBuffer[];
+  stringTable: SharedArrayBuffer[];
+  arrayTable: SharedArrayBuffer[];
+}): void {
+  for (const worker of liveWorkers) {
+    worker.postMessage({ __chunkUpdate: true, buffers });
+  }
 }
 
 /** Worker: request the buffers from the main thread and await the reply. */
@@ -239,6 +264,15 @@ function installMessageWrapper(): void {
           __sharedMemoryInit?: boolean;
           buffers?: Parameters<typeof SharedMemory.fromBuffers>[0];
         }
+      | {
+          __chunkUpdate?: boolean;
+          buffers?: {
+            indexTable: SharedArrayBuffer[];
+            dataTable: SharedArrayBuffer[];
+            stringTable: SharedArrayBuffer[];
+            arrayTable: SharedArrayBuffer[];
+          };
+        }
       | undefined;
     if (
       msg !== null &&
@@ -264,6 +298,18 @@ function installMessageWrapper(): void {
       flush();
       return;
     }
+    if (
+      msg !== null &&
+      typeof msg === "object" &&
+      "__chunkUpdate" in msg &&
+      msg.buffers &&
+      hasDefaultMemory()
+    ) {
+      // The main thread replaced inactive chunks after a defragmentation
+      // pass; apply the new chunk lists so this worker sees the replacement.
+      getDefaultMemory().applyChunkUpdate(msg.buffers);
+      return;
+    }
     if (hasDefaultMemory() && hasHandler) {
       messageHandler(e);
     } else {