fix(ecs): take the renderer-streamed bound from the container, not the default

Review follow-up (P2). Engine.removeEntity called isRendererStreamedNumber with
the module default of RESERVED_STATIC_ENTITIES, so the purge decision and the
id-release decision could disagree whenever a custom container is injected via
the public IEngineOptions.entityContainer seam. They are two halves of one
question and have to use the same bound.

Confirmed reachable, and it breaks in BOTH directions — the more damaging one
being the opposite of what you might expect:

  createEntityContainer({ reservedStaticEntities: 64 }), entity #100 v0
    container released the id? true
    components purged?        false
    getEntitiesWith(C) after removal: 1 entry, still yields 100 = {"v":111}

The id goes back into the recycling pool while the entity stays visible to
component queries with its data intact — engine.removeEntity returns true and
the entity is not removed. A caller cannot detect that.

The other direction is the narrower one: with reservedStaticEntities: 1024,
entity #700 is renderer-owned per the container (release refused) yet the purge
ran anyway, reopening for 512..1024 exactly the corruption this branch fixes.

Fix: IEntityContainer exposes the bound it enforces, and Engine.removeEntity
uses it. The member is OPTIONAL, so a third-party IEntityContainer stays
source-compatible; when absent the engine falls back to the module default,
which is correct for any container that also uses it. Public API grows by one
line:

  +    readonly reservedStaticEntities?: number;

Tests cover both directions and fail 3/21 without the change. Note the named
static entities stay at numbers 0-2 regardless of the bound — root, player and
camera are fixed by the protocol, not by the reserved range — and a bound below
3 degenerates safely to "always purge", matching a container that reserves
nothing.

Snapshots regenerated. Full suite: 160 suites, 1223 tests.

Author: LautaroPetaccio

packages/@dcl/ecs/src/engine/entity.ts

@@ -99,6 +99,18 @@ export type IEntityContainer = {
   releaseRemovedEntities(): Entity[]
   updateRemovedEntity(entity: Entity): boolean
   updateUsedEntity(entity: Entity): boolean
+
+  /**
+   * The exclusive upper bound of the renderer-reserved entity NUMBER range this container
+   * enforces — i.e. the `reservedStaticEntities` it was built with.
+   *
+   * `Engine.removeEntity` needs it to decide whether to purge an entity's components, and
+   * that decision has to agree with whether this container will release the id. Optional so
+   * a custom `IEntityContainer` passed via `IEngineOptions.entityContainer` stays
+   * source-compatible; when absent the engine falls back to `RESERVED_STATIC_ENTITIES`, which
+   * only matches if the container also uses the default.
+   */
+  readonly reservedStaticEntities?: number
 }
 
 /**
@@ -293,6 +305,7 @@ export function createEntityContainer(opts?: { reservedStaticEntities: number })
   }
 
   return {
+    reservedStaticEntities,
     generateEntity,
     removeEntity,
     getExistingEntities(): Set<Entity> {

packages/@dcl/ecs/src/engine/index.ts

@@ -63,7 +63,13 @@ function preEngine(options?: IEngineOptions): PreEngine {
     // range, so deletes on RootEntity/PlayerEntity/CameraEntity DO reach it and are applied.
     // Skipping those would silently break a working removal — the frame is byte-identical to
     // InputModifier.deleteFrom(engine.PlayerEntity).
-    if (!isRendererStreamedNumber(entity)) {
+    // Bound taken from the CONTAINER, not the module default, so the purge decision and the
+    // id-release decision cannot disagree. They are two halves of one question, and a custom
+    // container injected via IEngineOptions.entityContainer may enforce a different range: with
+    // a larger one the purge would run on entities the container treats as renderer-owned, and
+    // with a smaller one it would be skipped for scene-owned entities whose ids ARE released —
+    // leaving a "removed" entity still visible to getEntitiesWith with its data intact.
+    if (!isRendererStreamedNumber(entity, entityContainer.reservedStaticEntities)) {
       for (const [, component] of componentsDefinition) {
         // TODO: hack for the moment.
         // We still need the NetworkEntity to forward this message to the SyncTransport.

packages/@dcl/playground-assets/etc/playground-assets.api.md

@@ -1487,6 +1487,7 @@ export type IEntityContainer = {
     releaseRemovedEntities(): Entity[];
     updateRemovedEntity(entity: Entity): boolean;
     updateUsedEntity(entity: Entity): boolean;
+    readonly reservedStaticEntities?: number;
 };
 
 // @public (undocumented)

test/ecs/reserved-entity-range.spec.ts

@@ -104,8 +104,7 @@ describe('Reserved entity range ownership', () => {
       // createEntityContainer reads the define at call time, so assigning the global first
       // reproduces the build faithfully: counter starts at 746 while only 230 composite
       // entities are ever marked used, leaving a permanent deficit of 4.
-      ;(globalThis as unknown as { DCL_MAX_COMPOSITE_ENTITY: number }).DCL_MAX_COMPOSITE_ENTITY =
-        MAX_COMPOSITE_ENTITY
+      ;(globalThis as unknown as { DCL_MAX_COMPOSITE_ENTITY: number }).DCL_MAX_COMPOSITE_ENTITY = MAX_COMPOSITE_ENTITY
       entityContainer = createEntityContainer()
       for (let i = 0; i < COMPOSITE_ENTITY_COUNT; i++) {
         entityContainer.updateUsedEntity(EntityUtils.toEntityId(RESERVED_STATIC_ENTITIES + i, 0))
@@ -191,6 +190,64 @@ describe('Reserved entity range ownership', () => {
     })
   })
 
+  // IEngineOptions.entityContainer is a public injection seam, so Engine.removeEntity must take
+  // the reserved bound from the CONTAINER rather than the module default. Using the default
+  // breaks in both directions, and neither is detectable by a caller.
+  describe('when a custom entity container enforces a different reserved bound', () => {
+    let engine: ReturnType<typeof Engine>
+    let Owned: ReturnType<ReturnType<typeof Engine>['defineComponent']>
+
+    describe('and the bound is LOWER than the default, so the id IS released', () => {
+      let sceneEntity: Entity
+
+      beforeEach(() => {
+        engine = Engine({ entityContainer: createEntityContainer({ reservedStaticEntities: 64 }) })
+        Owned = engine.defineComponent('test::owned', { value: Schemas.Int })
+        // Number 100 is scene-owned under a bound of 64, but sits inside the default range.
+        sceneEntity = EntityUtils.toEntityId(100, 0)
+        Owned.create(sceneEntity, { value: 111 })
+      })
+
+      it('should release the id, confirming the container considers it scene-owned', () => {
+        expect(engine.removeEntity(sceneEntity)).toBe(true)
+      })
+
+      it('should purge its components, so a released id cannot keep them', () => {
+        engine.removeEntity(sceneEntity)
+
+        expect(Owned.getOrNull(sceneEntity)).toBeNull()
+      })
+
+      it('should stop yielding it from getEntitiesWith', () => {
+        engine.removeEntity(sceneEntity)
+
+        expect(Array.from(engine.getEntitiesWith(Owned))).toHaveLength(0)
+      })
+    })
+
+    describe('and the bound is HIGHER than the default, so the id is NOT released', () => {
+      let rendererOwned: Entity
+
+      beforeEach(() => {
+        engine = Engine({ entityContainer: createEntityContainer({ reservedStaticEntities: 1024 }) })
+        Owned = engine.defineComponent('test::owned', { value: Schemas.Int })
+        // Number 700 is renderer-owned under a bound of 1024, but outside the default range.
+        rendererOwned = EntityUtils.toEntityId(700, 0)
+        Owned.create(rendererOwned, { value: 222 })
+      })
+
+      it('should refuse to release the id', () => {
+        expect(engine.removeEntity(rendererOwned)).toBe(false)
+      })
+
+      it('should NOT purge its components, since the container treats it as renderer-owned', () => {
+        engine.removeEntity(rendererOwned)
+
+        expect(Owned.getOrNull(rendererOwned)).not.toBeNull()
+      })
+    })
+  })
+
   describe('when a scene removes an entity it genuinely owns', () => {
     let engine: ReturnType<typeof Engine>
     let SceneOwned: ReturnType<ReturnType<typeof Engine>['defineComponent']>

test/snapshots/development-bundles/static-scene.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=620.5k bytes
+SCENE_COMPILED_JS_SIZE_PROD=620.6k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -55,4 +55,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 5k
   MALLOC_COUNT = -5
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 1548.16k bytes
+  MEMORY_USAGE_COUNT ~= 1548.28k bytes

test/snapshots/development-bundles/testing-fw.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=621k bytes
+SCENE_COMPILED_JS_SIZE_PROD=621.1k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -61,4 +61,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 6k
   MALLOC_COUNT = -53
   ALIVE_OBJS_DELTA ~= -0.01k
-  MEMORY_USAGE_COUNT ~= 1553.86k bytes
+  MEMORY_USAGE_COUNT ~= 1553.98k bytes

test/snapshots/development-bundles/two-way-crdt.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=621k bytes
+SCENE_COMPILED_JS_SIZE_PROD=621.1k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -61,4 +61,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 6k
   MALLOC_COUNT = -53
   ALIVE_OBJS_DELTA ~= -0.01k
-  MEMORY_USAGE_COUNT ~= 1553.86k bytes
+  MEMORY_USAGE_COUNT ~= 1553.98k bytes

test/snapshots/production-bundles/append-value-crdt.ts.crdt

@@ -54,4 +54,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 15k
   MALLOC_COUNT = 31
   ALIVE_OBJS_DELTA ~= 0.01k
-  MEMORY_USAGE_COUNT ~= 1138.88k bytes
+  MEMORY_USAGE_COUNT ~= 1138.97k bytes

test/snapshots/production-bundles/billboard.ts.crdt

@@ -76,4 +76,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 12k
   MALLOC_COUNT = 0
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 1324.78k bytes
+  MEMORY_USAGE_COUNT ~= 1324.87k bytes

test/snapshots/production-bundles/cube-deleted.ts.crdt

@@ -41,4 +41,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 7k
   MALLOC_COUNT = 1
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 1101.02k bytes
+  MEMORY_USAGE_COUNT ~= 1101.11k bytes