Skip to content

W-042: ecs-prefab lifecycle, errors and isolation (PREFAB-F05)

Type: feature · Size: S · Epic: E-prefab-v0 · Target: packages/ecs-prefab · Breaking: no Depends: W-039, W-041 Refs: spec PREFAB-060..PREFAB-067

Goal

Pin down the error and lifecycle rules: instantiate rejects dead, non-prefab, and foreign-world prefabs; destroying a prefab, an instance, or a base has defined effects; worlds are isolated and reset invalidates prefab handles. Document the copy and clone rules in the README.

Steps

  • S1 (PREFAB-060, PREFAB-064, PREFAB-066): instantiate throws naming instantiate for a dead or non-prefab entity and for a prefab from another world; createPrefab rejects a base from another world; after world.reset() old handles are rejected and new prefabs work; files: packages/ecs-prefab/tests/lifecycle-errors.test.ts
  • S2 (PREFAB-061, PREFAB-062, PREFAB-063): destroying a prefab keeps its instances alive and removes their IsA pair; destroying an instance does not affect the prefab or siblings; destroying a base removes IsA from its variants, which then instantiate with their own traits only; files: packages/ecs-prefab/tests/lifecycle-destroy.test.ts
  • S3 (PREFAB-065, PREFAB-067; changeset): no module-level mutable state, and two worlds are independent; README states copy-once, AoS cloning or replacement, non-IsA pairs not copied, and variants holding only their own traits; files: packages/ecs-prefab/tests/isolation.test.ts, packages/ecs-prefab/README.md, .changeset/w-042-ecs-prefab-lifecycle.md (patch, @workspace/ecs-prefab)

Log

  • 2026-11-01 created from the approved spec split of W-005 (Triage)
  • 2026-11-01 held: waits on the OQ6 decision after the W-039 S1 spike (decision logged in W-039 first) (Triage)