@forgeax/engine-ecs 0.1.24 → 0.1.26

package/README.md

@@ -342,3 +342,12 @@ Physics, or the explicitly named ECS subpath.
 
 For the full migration rationale and acceptance matrix, see the canonical
 [ECS 80% architecture design](../../.forgeax-harness/docs/specs/2026-08-22-ecs-core-80-percent-architecture-reduction-design.md).
+
+### Large managed arrays
+
+The eight BufferPool size classes bound pooling, not field capacity. Larger
+arrays use dedicated allocations; release drops their storage instead of
+retaining a large free bucket. Growth preserves bytes and slot identity, and
+allocation failure returns the existing structured managed-buffer error. Small
+fields keep their existing allocation and reuse behavior. Game data, including
+instance transforms, remains World-owned regardless of its size.

package/dist/buffer-pool.d.ts

@@ -6,8 +6,7 @@ import { ManagedBufferOutOfBoundsError, ManagedBufferShrinkNotSupportedError } f
  *
  * `alloc(byteLength)` rounds up to `SIZE_CLASSES[i]` for the smallest `i`
  * with `byteLength <= SIZE_CLASSES[i]`. byteLength === 0 is the special path
- * (no bucket); byteLength > SIZE_CLASSES[7] (262_144) returns
- * `managed-buffer-out-of-bounds`.
+ * (no bucket); larger requests use dedicated, unpooled allocations.
  */
 export declare const SIZE_CLASSES: readonly number[];
 /** Result envelope for a fresh alloc - id + initial view. */
@@ -42,10 +41,10 @@ export declare class BufferPool {
      * Allocate a managed buffer slot of at least `byteLength` bytes.
      *
      * Routes:
-     *   - byteLength < 0  -> not in current contract (caller responsibility).
+     *   - invalid byteLength -> structured out-of-bounds error.
      *   - byteLength == 0 -> ok({ id, view: zero-length Uint8Array }) (no bucket).
      *   - byteLength <= 262144 -> ok({ id, view }), bucket = smallest >= byteLength.
-     *   - byteLength  > 262144 -> err(managed-buffer-out-of-bounds).
+     *   - byteLength > 262144 -> a dedicated allocation; allocation failure is structured.
      *
      * D-5: size classes are radix-4 (16 / 64 / 256 / 1K / 4K / 16K / 64K / 256K).
      * Free-list pop reuses the most recently released slot id at the same bucket;
@@ -65,7 +64,7 @@ export declare class BufferPool {
      *     the caller become detached / orphaned - callers must use `pool.view(id)`
      *     after grow to read the refreshed view (the `release` loop refreshes
      *     automatically).
-     *   - newBytes > 262144 -> err(managed-buffer-out-of-bounds).
+     *   - newBytes beyond the last pooled class -> dedicated allocation.
      */
     grow(id: number, newBytes: number): Result<Uint8Array, ManagedBufferShrinkNotSupportedError | ManagedBufferOutOfBoundsError>;
     /**

package/dist/buffer-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buffer-pool.d.ts","sourceRoot":"","sources":["../src/buffer-pool.ts"],"names":[],"mappings":"AA2CA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,6BAA6B,EAAE,oCAAoC,EAAE,MAAM,UAAU,CAAC;AAE/F;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAExC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAyCD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsD;IAClF,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,iBAAiB,EAAE,6BAA6B,CAAC;IAoDnF;;;;;;;;;;;;;;OAcG;IACH,IAAI,CACF,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,UAAU,EAAE,oCAAoC,GAAG,6BAA6B,CAAC;IAgD3F;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC;IAgBxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU;IAM5B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAOhC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,UAAU,EAAE,oCAAoC,GAAG,6BAA6B,CAAC;IA4B3F,+EAA+E;IAC/E,UAAU,IAAI,MAAM;CAKrB"}
+{"version":3,"file":"buffer-pool.d.ts","sourceRoot":"","sources":["../src/buffer-pool.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,6BAA6B,EAAE,oCAAoC,EAAE,MAAM,UAAU,CAAC;AAE/F;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAExC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAwCD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsD;IAClF,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,iBAAiB,EAAE,6BAA6B,CAAC;IA+DnF;;;;;;;;;;;;;;OAcG;IACH,IAAI,CACF,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,UAAU,EAAE,oCAAoC,GAAG,6BAA6B,CAAC;IAkD3F;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC;IAgBxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU;IAM5B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAOhC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,UAAU,EAAE,oCAAoC,GAAG,6BAA6B,CAAC;IA4B3F,+EAA+E;IAC/E,UAAU,IAAI,MAAM;CAKrB"}

package/dist/index.mjs

@@ -4788,9 +4788,8 @@ var WorldComponentAccess = class {
       slotId = column.view[row];
     }
     const requiredBytes = (currentLength + 1) * meta.byteSize;
-    const maximum = Math.floor(262144 / meta.byteSize);
-    if (!Number.isSafeInteger(currentLength + 1) || currentLength + 1 > maximum) {
-      return err(new ManagedBufferOutOfBoundsError(requiredBytes, 262144));
+    if (!Number.isSafeInteger(requiredBytes)) {
+      return err(new ManagedBufferOutOfBoundsError(requiredBytes, Number.MAX_SAFE_INTEGER));
     }
     const preparation = {
       target,
@@ -5850,10 +5849,10 @@ var BufferPool = class {
    * Allocate a managed buffer slot of at least `byteLength` bytes.
    *
    * Routes:
-   *   - byteLength < 0  -> not in current contract (caller responsibility).
+   *   - invalid byteLength -> structured out-of-bounds error.
    *   - byteLength == 0 -> ok({ id, view: zero-length Uint8Array }) (no bucket).
    *   - byteLength <= 262144 -> ok({ id, view }), bucket = smallest >= byteLength.
-   *   - byteLength  > 262144 -> err(managed-buffer-out-of-bounds).
+   *   - byteLength > 262144 -> a dedicated allocation; allocation failure is structured.
    *
    * D-5: size classes are radix-4 (16 / 64 / 256 / 1K / 4K / 16K / 64K / 256K).
    * Free-list pop reuses the most recently released slot id at the same bucket;
@@ -5867,11 +5866,20 @@ var BufferPool = class {
       this.slots.set(id2, { sizeClassIdx: -1, buffer: buffer2, view: view2, byteLength: 0, live: true });
       return ok({ id: id2, view: view2 });
     }
+    if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+      return err(new ManagedBufferOutOfBoundsError(byteLength, 0));
+    }
     const idx = bucketIndex(byteLength);
     if (idx === SIZE_CLASSES.length) {
-      return err(
-        new ManagedBufferOutOfBoundsError(byteLength, SIZE_CLASSES[SIZE_CLASSES.length - 1] ?? 0)
-      );
+      try {
+        const buffer2 = new ArrayBuffer(byteLength);
+        const view2 = new Uint8Array(buffer2);
+        const id2 = this.nextId++;
+        this.slots.set(id2, { sizeClassIdx: idx, buffer: buffer2, view: view2, byteLength, live: true });
+        return ok({ id: id2, view: view2 });
+      } catch {
+        return err(new ManagedBufferOutOfBoundsError(byteLength, 0));
+      }
     }
     const bucketBytes = SIZE_CLASSES[idx];
     if (bucketBytes === void 0) {
@@ -5915,7 +5923,7 @@ var BufferPool = class {
    *     the caller become detached / orphaned - callers must use `pool.view(id)`
    *     after grow to read the refreshed view (the `release` loop refreshes
    *     automatically).
-   *   - newBytes > 262144 -> err(managed-buffer-out-of-bounds).
+   *   - newBytes beyond the last pooled class -> dedicated allocation.
    */
   grow(id, newBytes) {
     const slot = this.slots.get(id);
@@ -5928,25 +5936,27 @@ var BufferPool = class {
     if (newBytes === slot.byteLength) {
       return ok(slot.view);
     }
-    const newIdx = bucketIndex(newBytes);
-    if (newIdx === SIZE_CLASSES.length) {
-      return err(
-        new ManagedBufferOutOfBoundsError(newBytes, SIZE_CLASSES[SIZE_CLASSES.length - 1] ?? 0)
-      );
+    if (!Number.isSafeInteger(newBytes) || newBytes < 0) {
+      return err(new ManagedBufferOutOfBoundsError(newBytes, slot.buffer.byteLength));
     }
-    if (newIdx === slot.sizeClassIdx) {
+    const newIdx = bucketIndex(newBytes);
+    if (newBytes <= slot.buffer.byteLength) {
       slot.byteLength = newBytes;
       slot.view = new Uint8Array(slot.buffer, 0, newBytes);
       return ok(slot.view);
     }
-    const newBucketBytes = SIZE_CLASSES[newIdx];
+    const newBucketBytes = SIZE_CLASSES[newIdx] ?? Math.max(newBytes, slot.buffer.byteLength * 2);
     const oldByteLength = slot.byteLength;
     let nextBuffer;
-    if (HAS_TRANSFER2) {
-      nextBuffer = slot.buffer.transfer(newBucketBytes);
-    } else {
-      nextBuffer = new ArrayBuffer(newBucketBytes);
-      new Uint8Array(nextBuffer).set(new Uint8Array(slot.buffer, 0, oldByteLength));
+    try {
+      if (HAS_TRANSFER2) {
+        nextBuffer = slot.buffer.transfer(newBucketBytes);
+      } else {
+        nextBuffer = new ArrayBuffer(newBucketBytes);
+        new Uint8Array(nextBuffer).set(new Uint8Array(slot.buffer, 0, oldByteLength));
+      }
+    } catch {
+      return err(new ManagedBufferOutOfBoundsError(newBytes, slot.buffer.byteLength));
     }
     slot.sizeClassIdx = newIdx;
     slot.buffer = nextBuffer;
@@ -5965,7 +5975,7 @@ var BufferPool = class {
     if (slot === void 0) return ok(void 0);
     if (!slot.live) return ok(void 0);
     slot.live = false;
-    if (slot.sizeClassIdx >= 0) {
+    if (slot.sizeClassIdx >= 0 && slot.sizeClassIdx < SIZE_CLASSES.length) {
       const bucket = this.freeBuckets[slot.sizeClassIdx];
       if (bucket !== void 0) bucket.push(id);
     } else {
@@ -5994,7 +6004,7 @@ var BufferPool = class {
     const slot = this.slots.get(id);
     if (slot === void 0 || !slot.live) return 0;
     if (slot.sizeClassIdx < 0) return 0;
-    return SIZE_CLASSES[slot.sizeClassIdx] ?? 0;
+    return slot.buffer.byteLength;
   }
   /**
    * Reset the logical byteLength of slot `id` to `newByteLength` while
@@ -6022,7 +6032,7 @@ var BufferPool = class {
       }
       return err(new ManagedBufferOutOfBoundsError(newByteLength, 0));
     }
-    const bucketBytes = SIZE_CLASSES[slot.sizeClassIdx] ?? 0;
+    const bucketBytes = slot.buffer.byteLength;
     if (newByteLength > bucketBytes) {
       return err(new ManagedBufferOutOfBoundsError(newByteLength, bucketBytes));
     }