@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/ecs/HIERARCHY_REVIEW.md

@@ -1,717 +1,717 @@
-# Hierarchy in meep's ECS — a review against Unreal 6 / Scene Graph
-
-**Date:** 2026-08-23
-**Subject:** `ParentEntity`, `TransformAttachment`, `EntityNode`, and the systems behind them
-**Comparator:** Epic's Scene Graph — the entity/component framework that UE6 is being built on
-
-**Status, 2026-08-24.** §6.1 landed: both systems now keep a parent → children index
-(`ecs/hierarchy/EntityChildIndex.js`), which closed **D5**, **D7**, **D8** and **D11**, and made **D3** small enough
-to fix in the same pass. **D4** was addressed the day before. Still open: **D1**, **D2**, **D6**, **D9**, **D10**, and
-the question in §8. Sections below are written in the tense of what is true now; the reasoning that led there is
-unchanged.
-
----
-
-## 0. Verdict up front
-
-The **core split is right, and it is a better decomposition than Unreal's.** meep separates *lifetime* parenting
-(`ParentEntity`) from *spatial* parenting (`TransformAttachment`) into two independent components. Scene Graph has one
-hierarchy that means lifetime, and bolts a spatial override onto it (`transform_component.Origin`). meep's version is
-the more honest model: two relations that are genuinely independent are stored as two relations, rather than one
-relation plus an escape hatch.
-
-The **propagation is also better than I expected.** I assumed the signal cascade would re-do work exponentially in
-depth. It does not — measured, each descendant is recomputed **exactly once** per root change, at any depth. That is
-optimal, and it is achieved without a sort, a level index, or a dirty-flag pass.
-
-What is weak is everything *around* that core:
-
-- `EntityNode`, described as "syntactic sugar", is not sugar. It holds live state (the local transform, the
-  subscriptions) that the ECS does not have, and animation binds to it. It is a **shadow object graph** — the exact
-  thing an ECS hierarchy exists to remove.
-- **Live reparenting does not work.** One path silently strips the spatial link (verified, repro below); the other
-  asserts. Scene Graph treats reparenting as an ordinary operation.
-- ~~**Children are not stored anywhere.** Every "give me the subtree" operation is a full scan of the dataset, so
-  subtree work is O(nodes × entities-in-world).~~ **Fixed** — each system now owns the back-links (§6.1).
-- Three parallel attachment mechanisms exist (`TransformAttachment`, `Attachment`, plus ad-hoc `transform.subscribe`
-  closures in `MeshSystem3`). A fourth component, `ChildEntities`, was dead code and has been deleted.
-
-Severity-ordered defect list is in §5. Six of the eleven are correctness, and two of those I reproduced.
-
----
-
-## 1. Scope and method
-
-**Read in full:** `ecs/parent/*` (`ParentEntity`, `ParentEntitySystem`, `ChildEntities` (since deleted), `EntityNode`,
-`EntityNodeFlags`, `entity_node_compute_bounding_box`), `ecs/transform-attachment/*` (`TransformAttachment`,
-`TransformAttachmentSystem`, `transform_attachment_parent_of`, `transform_attachment_find_descendant_by_name`),
-`ecs/attachment/*` (`Attachment`, `AttachmentSystem`, `AttachmentBinding`, `TransformAttachmentBinding`,
-`BoneAttachmentBinding`), plus `Entity`, `Transform`, and the relevant parts of `EntityComponentDataset`,
-`EntityManager` and `BinaryBufferSerializer`.
-
-**Consumers surveyed:** `shade_node_to_entity_composition`, `three_object_to_entity_composition`, `MeshSystem3`,
-`SGMeshSystem`, `ColliderObserverSystem`, `HierarchicalEntityListView`, `bind_property_writer`,
-`sg_hierarchy_compute_bounding_box_via_parent_entity`.
-
-**Measured, not assumed.** Four throwaway specs were run against the real systems (no mocks) and then deleted. Every
-number in §2.3, §5 D1, D2 and D10 is output from those runs, quoted verbatim. Where I state something I only read and
-did not execute, it says so.
-
-**On the Unreal side — read this before trusting §3.** Epic announced at State of Unreal (June 2026) that UE6 unifies
-UE and UEFN, and that Actors and Blueprints will eventually be deprecated in favour of Verse plus Scene Graph, with
-conversion tools and a multi-year transition. Scene Graph itself shipped first in UEFN and is documented there as
-experimental/beta. **The public documentation is the UEFN surface**, so the API names below are the Verse ones. Epic
-has not published Scene Graph's internal storage, so anything about *how* it stores hierarchy is unknown, and I make
-no claims about it.
-
-One terminology correction worth making, because it changes what "compare against Unreal's ECS" means: **Scene Graph
-is not Unreal's ECS.** Unreal's data-oriented ECS is **Mass** (archetype-based; components are "fragments", systems
-are "processors"), built for crowds and traffic. Scene Graph is an *entity/component gameplay framework* — the Actor
-replacement. It is Scene Graph, not Mass, that is the right comparator for meep's hierarchy, and that is what this
-document uses. Mass has no user-facing hierarchy to compare against.
-
----
-
-## 2. What meep has today
-
-### 2.1 Four mechanisms, not one
-
-| Mechanism | Means | Propagated by | Status |
-|---|---|---|---|
-| `ParentEntity { entity }` | **Lifetime.** Parent dies → child dies. | `ParentEntitySystem` listens for `EntityRemoved` on the parent, removes the child. | Live |
-| `TransformAttachment { transform, parent, flags }` | **Space.** Child world = parent world × local. | `TransformAttachmentSystem`, via `Transform` change signals. | Live |
-| `Attachment { parent, socket, transform }` | **Space, via a named socket / bone.** | `AttachmentSystem`, via `AttachmentBinding`s, polled every frame. | Live |
-| ad-hoc `transform.subscribe(follow)` | **Space, hand-rolled.** | A closure in `MeshSystem3` (line ~558) copying one transform to another. | Live |
-| ~~`ChildEntities { entities[] }`~~ | — | — | **Deleted** (D5). Was dead, and the wrong shape — see §4.2. |
-
-`EntityNode` sits on top of the first two as an authoring façade.
-
-The overlap between rows 2–4 is the first thing to notice. `TransformAttachmentBinding` (row 3's transform case) does
-what `UpdateContext` (row 2) does, with a socket offset spliced in, using matrices instead of `Transform` composition —
-and it carries a `TODO` saying so. Row 4 is row 2 with the local transform hard-coded to identity.
-
-### 2.2 The two relations are genuinely independent — and that is the good part
-
-```
-ParentEntity.entity        →  "when that entity dies, I die"
-TransformAttachment.parent →  "my transform is relative to that entity"
-```
-
-Nothing requires them to name the same entity. That is a real capability: a UI marker can be spatially attached to a
-unit's head while being owned by the HUD; a compound rigid body's colliders are `ParentEntity`-owned by the body
-(which is exactly how `ColliderObserverSystem` finds them) without necessarily composing transforms through it.
-
-Scene Graph cannot express this as two facts. It has one hierarchy — which means lifetime — and then
-`transform_component.Origin` to say "actually, compose me against *that* entity instead". Same expressive power,
-reached by exception rather than by construction.
-
-### 2.3 How the transform composition actually behaves (measured)
-
-`TransformAttachmentSystem` builds an `UpdateContext` per attached entity holding `{attachment, transform, entity,
-parent_transform}` and subscribes it to *both* the parent's world `Transform` and the attachment's local `Transform`.
-Any change to either fires `ctx.update()`, which is one `m4_multiply` plus a decompose back into the child's world
-`Transform` — whose own position/rotation/scale setters fire, waking the grandchild's context. Propagation is a
-synchronous, re-entrant, depth-first cascade with no flush point.
-
-Measured on a straight chain, counting writes to each descendant's TRS channels for **one** root change:
-
-```
-depth=4  translate: pos-writes=3  rot-writes=0  scale-writes=0   across 3 descendants
-depth=4  rotate:    pos-writes=3  rot-writes=3  scale-writes=3   across 3 descendants
-depth=8  translate: pos-writes=7  rot-writes=0  scale-writes=0   across 7 descendants
-depth=8  rotate:    pos-writes=7  rot-writes=7  scale-writes=7   across 7 descendants
-depth=16 translate: pos-writes=15 rot-writes=0  scale-writes=0   across 15 descendants
-depth=16 rotate:    pos-writes=15 rot-writes=15 scale-writes=15  across 15 descendants
-```
-
-**One recompute per descendant, every time.** No redundancy at any depth. The `Vector3.set`/`Quaternion.set` equality
-guards are doing real work here: a pure translation never wakes a rotation listener. This is a good design and it
-should be said plainly, because the rest of this document is mostly criticism.
-
-Two costs come with it, both real:
-
-**It is observable mid-cascade.** An observer of a descendant's `Transform` is called *during* propagation, when the
-transform is only partly updated. Measured on a depth-3 chain under one 90° root yaw, an observer of the leaf sees:
-
-```
-[0] pos(0.000,-2.000)  rotY(0.000)     ← position already final, rotation still stale
-[1] pos(0.000,-2.000)  rotY(0.707)     ← settled
-```
-
-State `[0]` is a pose that never existed. Anything that *accumulates* from a transform callback — a motion trail, a
-velocity estimate, a moved-event, a physics impulse — integrates a torn pose. Renderers get away with it because the
-last write before the frame ends is correct.
-
-**Every level does a decompose/recompose round-trip**, and it is lossy. Measured on a chain with **no scaling
-anywhere**, all-rotation locals:
-
-```
-depth=8:  leaf world scale = (1.00000009045938,  1, 1.00000009045938)
-depth=32: leaf world scale = (1.0000006507070245, 1, 1.0000006507070245)
-depth=64: leaf world scale = (1.0000014229381489, 1, 1.0000014229381489)
-```
-
-The exact answer is `(1,1,1)` at every depth. The drift grows with depth, and — because it is a genuine change — it
-also fires a spurious `scale.onChanged` at every level on every rotation, which is where the `scale-writes=N` column
-above comes from. Anything subscribed to scale is woken by pure rotation.
-
-The same round-trip discards shear outright. Root scaled `(4,1,1)`, child yawed 45°:
-
-```
-mid  world scale stored as (2.9155, 1.0000, 2.9155)
-leaf world matrix row0    = 2.8284, 0.0000, -0.7071
-```
-
-The true composed basis is non-orthogonal; TRS cannot hold it, so it is silently best-fitted. A mesh under a
-non-uniformly-scaled rotated parent draws wrong. **Scene Graph shares this limitation** — its transform is TRS too —
-but Unreal documents the non-uniform-scale caveat and meep does not.
-
-### 2.4 `EntityNode` is not syntactic sugar
-
-Its own docstring says "syntactic sugar on top of `TransformAttachment` and `ParentEntity`". It is not, on three
-counts:
-
-1. **It owns a third copy of the local transform.** `EntityNode.__transform` is the local transform; the component's
-   `attachment.transform` is *also* the local transform. They are synced one-way, node → component, by
-   `__transform_sync_down` on change. Write the component directly and the node is stale, with no way to notice.
-2. **It is required at runtime, not just at authoring time.** `bind_property_writer` binds animation curves to
-   `node.transform.position` / `.rotation` / `.scale` — the *node's* transform, not the component's. Every animated
-   model therefore has to retain its `EntityNode` tree for as long as it animates. The object graph an ECS hierarchy
-   is supposed to replace is still there, alive, next to the dataset.
-3. **It carries behaviour the components do not have** — `build`/`destroy` ordering, `on.built`/`on.destroyed`,
-   listener attach/detach, `root`, `traverse`. None of that is reachable from an entity id. Anything holding only an
-   entity id cannot participate.
-
-So there are two ways to express a hierarchy in meep, and they are not interchangeable: components are the storage,
-`EntityNode` is the API, and the API is only available to whoever constructed the tree.
-
----
-
-## 3. What Scene Graph does
-
-From Epic's UEFN documentation (see §8 for links):
-
-**Entities are containers; components supply data and behaviour.** One component instance per type per entity — need
-two, make two entities. Components are constructed with a pointer to their owning entity and **cannot be moved between
-parents**.
-
-**One hierarchy, and it means lifetime.** "Parenting represents object lifetime: if the parent is removed from the
-scene, so are the sub-objects." One simulation entity is the root; every map entity is a descendant of it.
-
-**Children are stored and enumerable.** `GetEntities()` returns the direct children; `GetParent()` walks up;
-`AddEntities(...)` adds children **and reparents them if they already have a parent**; `RemoveFromParent()` detaches,
-and the entity can be re-added later.
-
-**Space is layered on top, by exception.** `transform_component` holds `LocalTransform` plus an optional `Origin`. If
-`Origin` is unset, the entity composes against its parent. If set, it composes against whatever entity `Origin` names
-— "a child can orbit around a sibling rather than its parent". API is `Get/SetLocalTransform`, `Get/SetGlobalTransform`
-(both of which implicitly create the component), and `SetOrigin` / `GetOrigin[]` / `ResetOrigin`.
-
-**Lifecycle is a phase machine, not a boolean.** Components get `OnAddedToScene` → `OnBeginSimulation` →
-`OnSimulate` (suspending/async) → `OnEndSimulation` → `OnRemovingFromScene`. Adding a child to an in-scene parent
-"advances the child through lifetime phases to match parent state". Component queries only become valid after
-`OnAddedToScene`.
-
-**The hierarchy is an event bus.** `SendUp(event)` / `SendDown(event)`, with consumption halting propagation.
-
-**Entities carry tags** — `AddTag`, `ContainsAnyTag`, `RemoveAllTagsExcept`, etc.
-
-**Access is scoped.** `GetEntities()` and `GetComponents()` return what is "accessible from the calling context" —
-visibility is part of the model, not just a convention.
-
-**Their own performance guidance** is: don't re-scan the tree during gameplay; find what you need once in
-`OnBeginSimulation`, cache the references or subscribe to events, and react to events rather than searching again.
-Don't broadcast events across large portions of the graph.
-
----
-
-## 4. Head-to-head
-
-| | meep | Scene Graph |
-|---|---|---|
-| Lifetime relation | `ParentEntity.entity` | the hierarchy itself |
-| Spatial relation | `TransformAttachment.parent` — **independent** | `transform_component.Origin`, defaulting to the parent |
-| Local transform | `TransformAttachment.transform` (+ a shadow copy on `EntityNode`) | `transform_component.LocalTransform` |
-| World transform | stored, as a decomposed `Transform` component | queried via `GetGlobalTransform()` |
-| Children stored? | Yes — a system-owned index, not a component (§4.2) | Yes — `GetEntities()` |
-| Reparenting | **Broken / unsupported** (§5 D1, D2) | `AddEntities` reparents as a normal operation |
-| Lifecycle | `isBuilt` boolean; `link`/`unlink` on systems | five explicit phases, propagated to children |
-| Events on the tree | none | `SendUp` / `SendDown` with consumption |
-| Tags | none (`Name` only) | first-class |
-| Cycle safety | detected on read, throws | not documented |
-| Serialization | asymmetric — spatial survives, lifetime does not (§5 D6) | prefab-based |
-| Shear under non-uniform scale | lost silently | lost (documented) |
-
-### 4.1 The relation split — meep wins, and should not follow Unreal here
-
-Worth stating explicitly because it is tempting to read Unreal's design as the newer one and therefore the better one.
-It is not, on this axis. `Origin`-defaults-to-parent is a **"unset means auto" sentinel**: one field with two meanings,
-where the common case is invisible and the uncommon case is an override. meep's two independent fields say the same
-thing with uniform control flow — the common case (`TransformAttachment.parent === ParentEntity.entity`) is written
-out rather than implied.
-
-This also happens to be the shape the codebase already prefers. Adopting `Origin` would be adopting a sentinel.
-
-The cost meep pays is that **the coupling is real but undocumented**: `TransformAttachment` alone is not safe when the
-parent can die (§5 D3). `ParentEntity` is what makes it safe. Nothing says so, and `transform_attachment_parent_of`'s
-docstring — which is otherwise the best documentation in this area — describes the spatial hierarchy as if it stood
-alone.
-
-### 4.2 Children were not stored — the biggest structural gap, now closed
-
-**Was:** `ParentEntitySystem.findChildrenOf` scanned **every** `ParentEntity` component in the dataset to find one
-entity's children, and `traverse` called it once per node. So computing a subtree bounding box (which
-`sg_hierarchy_compute_bounding_box_via_parent_entity` does exactly this way) was **O(subtree × all-parented-entities)**.
-
-Scene Graph stores children and Epic's own guidance is *still* "don't scan the tree during gameplay, cache in
-`OnBeginSimulation`". meep was scanning a structure that was a full dataset sweep rather than a stored list.
-
-**Now:** both systems own a parent → children index (`ecs/hierarchy/EntityChildIndex.js`), so `findChildrenOf` is a
-lookup and `traverse` is linear in the subtree. The shape and the reasoning are below; what actually landed is in §6.1.
-
-Two things this did **not** change, deliberately:
-
-- `transform_attachment_find_descendant_by_name` still scans every `Name` and walks up from each candidate — that is
-  the bone-lookup path, and it searches by *name* first, which no parent → children index answers. Rewriting it as a
-  downward walk over the spatial index is now possible and is the obvious follow-up, but it is a different search.
-- The editor's `HierarchicalEntityListView` still builds its own `Map<parent, children[]>`. It looked like the missing
-  index implemented privately, and it is not quite: the view excludes editor-owned entities from the tree entirely, so
-  its map is a *filtered* one, and it needs a full entity sweep regardless to find the roots — entities with no
-  `ParentEntity` at all, which no children index knows about. Swapping in the real index would mean filtering on every
-  read and taking a dependency on a running system, for no sweep saved. Left alone.
-
-#### Where the index belongs — *not* in a component
-
-The obvious move, and the one most engines make, is a `ChildEntities` component. meep had one already
-(`parent/ChildEntities.js`, dead). **That was the wrong shape, and it was deleted rather than revived.**
-
-A child list stored as a component is *derived data promoted to authored data*. The consequences are all bad and all
-structural:
-
-- **It is a two-place invariant.** `ParentEntity` lives on the child and `ChildEntities` lives on the parent — two
-  entities, two components, one fact. Nothing in the type system or the dataset keeps them agreeing. They can drift,
-  and the drift is silent.
-- **It is user-writable.** Being a component makes it authorable, mutable, and reachable from any system. Every one of
-  those is an opportunity to corrupt an index that has one correct value.
-- **It is a burden at the layer least able to carry it.** Whoever builds a hierarchy now has to maintain both ends of
-  every edge, for information the engine can derive.
-- **It doubles the state footprint** of every parent, and it has to be excluded from serialization by hand — one more
-  thing to get wrong alongside D6.
-
-The alternative, and what was built, is to hold the back-links **at the system level**: `ParentEntitySystem` already
-observes every entity that gains or loses a `ParentEntity`, so it maintains a private parent → children index with no
-component, no authored state, and nothing for a user to desynchronise. One writer, one source of truth, rebuilt from
-scratch on load.
-
-The usual objection is ergonomics — a consumer now has to reach for the system instead of just calling `getComponent`.
-That objection does not survive contact with the actual call pattern: **`ChildEntities` would not have avoided it.** A
-component gives you one level of children as entity ids; to go a level deeper you need `getComponent(child,
-ChildEntities)`, so you are already reaching for the dataset. Component and system are equally indirect, and the system
-version is the one that cannot be wrong. `EntityManager.getSystem(SystemClass)` is typed on the class, so this stays
-inside the codebase's preference for typed lookup over string-keyed registries.
-
-The migration cost was also much smaller than it looked — see §6.1.
-
-### 4.3 Reparenting
-
-Scene Graph: `AddEntities` reparents, and advances the child through lifecycle phases to match the new parent.
-
-meep: **neither path works.** Direct `.parent =` assignment strips the spatial link (D1, reproduced). `addChild` of an
-already-built node throws (D2, reproduced). There is no supported way to move a live subtree.
-
-This is the single largest functional gap, and it is not exotic — "pick this up", "get in the vehicle", "re-dock this
-panel" are all reparenting a live subtree.
-
-### 4.4 Lifecycle phases
-
-meep has one bit (`isBuilt`) plus system `link`/`unlink`. The consequence is `TransformAttachmentSystem`'s retry
-queue: a child whose parent has not appeared yet cannot be linked, so it is parked and retried at 32 entries per
-frame, forever, with no diagnostic if the parent never arrives. `AttachmentSystem` has its own separate `waiting`
-array doing the same thing.
-
-That queue is *compensating for the absence of ordering guarantees*. Scene Graph's answer is that a child added to an
-in-scene parent is advanced to match the parent's phase — the "parent isn't ready yet" state is structurally
-impossible rather than polled for.
-
-Not a defect. But two hand-rolled retry queues is what the missing phase model costs.
-
-### 4.5 Events, tags, scoping
-
-meep has none of `SendUp`/`SendDown`, tags, or context-scoped access. Of the three:
-
-- **`SendUp`/`SendDown` is worth having** and is cheap once children are stored. The idiom it enables — a hit on a
-  limb bubbling to the creature, a "prefab" root broadcasting down — is currently done by walking to
-  `ParentEntitySystem.findRoot` and dispatching manually.
-- **Tags** duplicate what a component already does in meep. Skip; a zero-field component is the same thing and stays
-  typed, which is what this codebase prefers over string keys.
-- **Scoped access** is a Verse-language concern. Not applicable.
-
----
-
-## 5. Defects
-
-Ordered by severity. **[repro]** = I reproduced it against the real systems. **[read]** = from reading only.
-Entries marked **FIXED** were closed on 2026-08-24 by the work in §6.1 and §6.3; the original finding is kept so the
-reasoning stays readable, with what changed appended.
-
----
-
-**D1 — `EntityNode.parent` setter destroys the spatial link. [repro]** — *correctness, high*
-
-`EntityNode.js:240-270`. The setter removes both components up front:
-
-```js
-let parent_entity = this_entity.removeComponent(ParentEntity);
-let attachment    = this_entity.removeComponent(TransformAttachment);   // returns the instance
-
-if (node !== null) {
-    ...
-    this_entity.add(parent_entity);                    // ParentEntity IS re-added
-
-    if (attachment === null) {                         // ...but it is NOT null,
-        attachment = this.__safe_get_attachment();     //    so this never runs
-    }
-    attachment.parent = parent_entity_id;              // mutates a DETACHED component
-}
-```
-
-`Entity.removeComponent` returns the removed instance (`Entity.js:286`), so the `=== null` branch is dead whenever the
-node was already parented. The re-add only happens through `__safe_get_attachment()`, which is skipped.
-
-Reproduced — build `a → b`, then assign `b.parent = c` directly:
-
-```
-after build,     b has TransformAttachment: true
-after reparent,  b TransformAttachment: null
-after reparent,  b ParentEntity: 2   (c.id: 2)   ← lifetime link correct
-dataset has TransformAttachment on b: undefined  ← spatial link gone
-```
-
-The child keeps its new owner and silently stops following it in space; its world `Transform` freezes at its last
-value. `addChild()` happens to escape this because `removeChild()` runs first and clears the component via the
-`node === null` path — so the bug is confined to the public setter, which is the documented way to reparent.
-
-Fix is one line: drop the `if (attachment === null)` guard and always call `__safe_get_attachment()`.
-
----
-
-**D2 — live reparenting asserts in dev, silently no-ops in prod. [repro]** — *correctness, high*
-
-`EntityNode.addChild` calls `node.build(dataset)` when the receiving parent is built; `build` opens with
-`assert.notOk(this.__entity.isBuilt, 'Already built')`. Reproduced: `addChild` of a built node into a built parent
-throws `"Already built"`.
-
-Asserts are compiled out of production builds. In production the assert vanishes and `Entity.build` early-returns
-(`Entity.js:442-449`), so it degrades to a partial no-op rather than corruption — but combined with D1 the node can
-end up owned-but-not-attached with no error anywhere. **Dev throws, prod silently misbehaves**, which is the worse of
-the two orderings.
-
----
-
-**D3 — a child was not detached when its spatial parent died. [read]** — *correctness, high* — **FIXED 2026-08-24.**
-
-`UpdateContext` captured `parent_transform` at link time and subscribed to it. Nothing observed the *parent's*
-removal. When the parent entity was destroyed:
-
-- the child still had `TransformAttachment` + `Transform`, so the system's `unlink` was never called;
-- `this.__contexts[entity]` kept holding the context, which kept holding the dead parent's `Transform` alive;
-- the child composed against a transform nothing would ever update again — it froze, silently.
-
-`ParentEntity` masked this whenever both components named the same entity, because the child got destroyed too. It was
-exposed exactly when the two are used independently — i.e. the capability §4.1 credits as meep's advantage.
-
-**The fix**, mirroring what `ParentEntitySystem`'s `Context` already did: `UpdateContext` subscribes to its parent's
-`EntityRemoved` in `link()` and unsubscribes in `unlink()`, and on removal it takes `TransformAttachment` off the
-child. The child survives with the world transform it had, as a root, and its own subtree keeps composing against it.
-Dropping the component rather than quietly tearing the context down is what makes the detach observable, and it routes
-the teardown through the system's ordinary `unlink` path.
-
-Two details worth keeping:
-
-- **It is registered per child, not per parent, so the §6.1 index is not what makes it work.** The index would have
-  needed a separate count of *bound* children to know when to add and drop a single per-parent listener — queued
-  children are in the index but must not register — which is more state than one listener per context. The index is
-  still what makes "which children point at me" answerable; this particular fix just did not need to ask.
-- **A stale dispatch is real and is guarded.** Entity event dispatch copies its listener list before invoking it, so
-  when an entity carries *both* relations and the lifetime one destroys it first, the spatial detach still arrives —
-  for an entity that no longer exists. `UpdateContext` tracks whether it is linked and ignores the late call. This is
-  ordering-dependent (whichever system linked first is called first) and is covered both ways round in the spec.
-
-**Still not covered:** a child that is still *queued* when its parent dies. It never bound, so it never subscribed, and
-it goes on retrying against an id that may be recycled. That is the pre-existing gap §4.4 describes — the retry queue
-has no diagnostic for a parent that never arrives, and now also none for one that leaves.
-
----
-
-**D4 — mutating `TransformAttachment.parent` is silently ignored. [read]** — *correctness, medium* — **ADDRESSED
-2026-08-24**, documented on the field to match `ParentEntity`'s existing constraint.
-
-`UpdateContext.update()` reads `this.parent_transform`, resolved once at link. Writing `attachment.parent = other`
-afterwards changes nothing; the entity keeps composing against the old parent. `ParentEntity` documents this
-constraint ("Must not be mutated while the component is attached to a dataset"); `TransformAttachment` did not, and
-its field is plain and public.
-
-Worth noting that this contract is **load-bearing for §6.1, not just hygiene.** A system-owned child index is correct
-precisely because `link`/`unlink` are the only transitions a parent reference can undergo. If either component's
-`parent` field could be rewritten in place, the index would need change detection to stay honest, and the argument for
-keeping it out of a component would weaken. Documenting the immutability is what makes the cheap index sound.
-
----
-
-**D5 — `ChildEntities` was dead code, and the wrong shape. [repro — zero references]** — *hygiene, medium* —
-**FIXED 2026-08-24.**
-
-Defined in `parent/ChildEntities.js`, referenced nowhere outside its own file.
-
-**Deleted.** Per §4.2 it was not a stub to finish — a component is the wrong home for a derived back-link, and leaving
-the file present implied both that a child index existed and that a component was where one should go. Neither was
-true. The index belongs to `ParentEntitySystem` (§6.1), and now lives there.
-
----
-
-**D6 — serialization is asymmetric between the two hierarchies. [read]** — *correctness, medium*
-
-`ParentEntity.serializable = false`, commented "Entity IDs are transient, serialization is not applicable".
-`TransformAttachment` sets no such flag, and `isComponentClassSerializable` defaults to serializable
-(`BinaryBufferSerializer.js:15`) — so its `parent` field, **also a raw entity id**, is written and read back.
-
-Entity ids do survive a round-trip (`BinaryBufferDeSerializer` calls `createEntitySpecific`), so this is not
-straightforwardly broken. But the two components make opposite decisions about the same kind of data, and the result
-is that a saved scene reloads with its **spatial** hierarchy intact and its **lifetime** hierarchy gone. Given D3,
-that reload also lands in exactly the configuration where an attachment is unsafe.
-
-Whichever way it is resolved, the two should agree.
-
-§6.1 sharpened this rather than changing it: the child index is rebuilt from the child-side components on load, so a
-scene that reloads without its `ParentEntity` components reloads with an empty lifetime index too. The index does not
-cause the omission, it just stops it being invisible.
-
----
-
-**D7 — subtree operations were O(subtree × world). [read]** — *performance, medium* — **FIXED 2026-08-24.**
-
-`ParentEntitySystem.findChildrenOf` swept every `ParentEntity` in the dataset per node; `traverse` called it per node.
-`sg_hierarchy_compute_bounding_box_via_parent_entity` and `transform_attachment_find_descendant_by_name` (the bone
-lookup) both paid it.
-
-The index in §6.1 fixed the first: `findChildrenOf` is a lookup and `traverse` is linear in the subtree. The bone
-lookup is untouched — it searches by name, which this index does not answer (§4.2).
-
-Also in `traverse`: `path.concat(entity)` allocated a new array per node per level, making cycle detection O(depth²) in
-allocations for a deep tree. The rewritten walk pushes and pops one shared path array instead, and cycle detection is
-now O(depth) comparisons per node against no allocation at all.
-
----
-
-**D8 — the cycle checker was a shared fixed buffer. [read]** — *correctness, low* — **FIXED 2026-08-24.**
-
-`ParentEntitySystem` used a module-level `Uint32Array(1024)` for `findRoot` and `isAncestorOf`, with no bounds check
-on `loop_checker_array[count++]`. Two consequences: writes past 1024 were silently dropped by JS typed arrays, so a
-hierarchy deeper than 1024 stopped detecting cycles and could spin forever; and because the buffer was shared and
-un-reentrant, a `findRoot` called from inside a `traverse` callback clobbered the outer walk's state.
-
-Depth > 1024 is not realistic. Re-entrancy was — `traverse` takes a user callback.
-
-Both walks now keep their own path array, which is per call and grows, so neither failure mode exists. It fell out of
-moving these two off the static-plus-`ecd` shape onto the system; the module global, `check_loop` and `genLoopString`
-went with it. A 2048-deep chain is in the spec.
-
----
-
-**D9 — transform sockets update twice per frame. [read]** — *performance, low*
-
-`TransformAttachmentBinding.link()` subscribes to the parent's and the attachment's transform changes, *and*
-`AttachmentSystem.__updateAll()` calls `binding.update()` for every binding every frame unconditionally. Either the
-subscription or the sweep is redundant. (`BoneAttachmentBinding` genuinely needs the per-frame sweep — its pose is a
-query with no change signal — so the sweep is the one to keep, and the `TransformAttachmentBinding` subscriptions are
-the removable half.)
-
----
-
-**D10 — decompose round-trip drifts and drops shear. [repro]** — *correctness, low-to-medium*
-
-Numbers in §2.3. Scale drifts to ~1.4e-6 over 64 rotation-only levels and fires spurious `scale.onChanged` at every
-level; shear from a non-uniformly-scaled rotated parent is silently best-fitted away.
-
-Not cheaply fixable — it is inherent to storing the world transform as a decomposed `Transform` — and Unreal has the
-same limitation.
-
-The documentation half is **done**: `TransformAttachment` now carries the non-uniform-scale caveat and the drift
-figure. The behaviour is unchanged and the defect stays open on that basis. Still worth considering: whether
-`UpdateContext.update()` should compose into the child's `matrix` and skip the decompose for consumers that only read
-the matrix.
-
----
-
-**D11 — neither system had a spec. [repro — no such files]** — *test coverage, medium* — **FIXED 2026-08-24.**
-
-There was no `TransformAttachmentSystem.spec.js` and no `ParentEntitySystem.spec.js`. `TransformAttachment.spec.js` and
-`EntityNode.spec.js` between them test `setFlag`/`clearFlag`/`getFlag`/`writeFlag` — twice, once each, in identical
-form — plus JSON round-trip and `addChild`/`removeChild` bookkeeping on *unbuilt* nodes.
-
-**The composition contract itself was untested.** Nothing asserted that a child's world transform equals parent ×
-local, that a change propagates, that a chain composes, or that a queued attachment links when its parent arrives.
-Nine other specs register both systems, but as fixture scaffolding — `MeshSystem3.spec.js` registers them so a model
-can expand, not to check them.
-
-Both specs now exist, on real `EntityManager`/`EntityComponentDataset` objects, and cover the composition contract,
-the index (empty/one/many, ordering, child removal, parent removal, id recycling, snapshot semantics), the queue path,
-subtree traversal against the full-scan implementation it replaced, cycles, and the D3 detach in both dispatch orders.
-`EntityChildIndex` has its own spec for what the systems cannot reach through their own API. The flag tests remain the
-vacuous-smoke-test shape and were left alone; they are not what this defect was about.
-
-Note that D1 and D2 are both immediately visible from a five-line test, which is why they are still here.
-
----
-
-## 6. What is worth taking from Scene Graph
-
-In order of value per unit of change. Note that the first item takes Scene Graph's *capability* while explicitly
-rejecting its *storage* — the useful comparison here is not "copy what Unreal did".
-
-### 6.1 Store children — as a system-owned index, not a component — **LANDED 2026-08-24**
-
-Take Scene Graph's *capability* (children are enumerable in O(children)) and reject its *storage*, because meep's
-system layer can derive the same thing without asking the user to maintain anything. Reasoning in §4.2; this is what
-was built.
-
-`ecs/hierarchy/EntityChildIndex.js` holds the structure — a sparse array of parent id → ascending child ids — and both
-systems own one, as `__children`. It has its own spec for the ordering and copy-out contracts.
-
-**The choke points already existed and were already overridden.** `ParentEntitySystem` extends `AbstractContextSystem`,
-whose `link()`/`unlink()` fire exactly once per entity gaining or losing a `ParentEntity`. `ParentEntitySystem`'s own
-`Context` already overrode both, and already read `this.components[0].entity` to subscribe to the parent's removal.
-Maintaining the index is one insert in `Context.link()` and one remove in `Context.unlink()`, beside code that was
-already there for exactly the same edge.
-
-Design notes that mattered, and how each was settled:
-
-- **Store entity ids, never contexts.** `AbstractContextSystem` pools its contexts through `ObjectPoolFactory` and
-  reuses them after `unlink`. An index holding context references would alias recycled objects. The index stores ids.
-- **Define child order explicitly.** Insertion order is link order, which is deterministic only as far as entity
-  creation order is. **Sorted ascending by entity id on insert**, via a binary-search insert — chosen over documenting
-  link order because it makes iteration order independent of the thing that is hard to reason about, and child fan-out
-  is small enough that the splice is not worth defending against.
-- **Hand out a snapshot, not the live array.** `handleParentEntityRemoval` destroys children from inside the cascade,
-  so a consumer iterating a live array mutates under itself. `findChildrenOf` kept its `(result, result_offset, ...)
-  -> count` shape — the `ecd` argument dropped, since the system knows its own dataset — which preserves the house
-  convention from the bvh3 query API. `countChildrenOf` was added beside it, to size a buffer without filling one.
-- **The index does not serialize, and that is the point.** It is rebuilt from `ParentEntity` on load, so there is no
-  format, no version, and no stale-id migration. **This does sharpen D6:** `ParentEntity.serializable === false` means
-  a loaded scene has no `ParentEntity` components to rebuild *from*, so the lifetime hierarchy comes back empty. The
-  index makes that omission visible rather than causing it.
-- **Entity ids are recycled**, so a parent whose last child leaves has its entry deleted outright rather than left
-  empty. An id that comes back has to come back childless; both specs pin it.
-
-**Static-with-`ecd` versus instance.** `traverse` and `findChildrenOf` need the index, so they had to move onto the
-system. `findRoot`, `isAncestorOf` and `findParentEntity` walk child → parent and did not, but leaving them static
-would have meant two ways to ask the same system the same kind of question. All five are instance methods now and the
-`ecd` parameter is gone from all of them. Per library semantics the unreferenced ones were carried across rather than
-deleted.
-
-**Migration cost, measured before and confirmed after:** `ParentEntitySystem.traverse` had **exactly one caller** in
-the whole tree (`sg_hierarchy_compute_bounding_box_via_parent_entity.js:30`), which now takes the system in place of
-the `ecd`. `findChildrenOf`, `findRoot` and `isAncestorOf` had **zero** external callers. So the "you have to reach
-for the system" awkwardness cost one production signature change, plus standing up an `EntityManager` in
-`sg_hierarchy_compute_bounding_box_via_parent_entity.spec.js`, which had been running on a bare ECD.
-
-Payoff: killed D7 and D8, made D3 small enough to fix in the same pass (§6.3), and unblocks `SendUp`/`SendDown`. It did
-**not** let `HierarchicalEntityListView` drop its private `Map<parent, children[]>` — see §4.2 for why that map is not
-this index.
-
-**The same index shape applies to the spatial hierarchy**, and landed there too. `TransformAttachmentSystem` already
-keyed `__contexts` by child; the parent → children direction goes in at `link()` and out at `unlink()`. Inserting at
-`link()` rather than `__finalize_link()` means **a queued child is in the index before it binds** — the question the
-index answers is "which children point at me", and that is true of a child still waiting for its parent to gain a
-`Transform`. The consequence, documented on the system: a non-zero child count does not imply those children are
-composing yet.
-
-### 6.2 Make reparenting a real, single operation
-
-**Not done — still the largest open item.** One function — `hierarchy_reparent(ecd, entity, new_parent)` — that
-updates both components together and is the only supported path. Fix D1 inside it and let `EntityNode.parent` delegate
-to it. This is Scene Graph's `AddEntities` semantics, minus the phase machine. D4's documented immutability means
-reparenting is a remove/re-add of the components, not a field write — which is the contract this function should
-encode rather than leave to callers, and which §6.1 turned from a convention into something the child indices depend
-on.
-
-### 6.3 Detach on parent death — **LANDED 2026-08-24**
-
-`TransformAttachmentSystem` now listens for `EntityRemoved` on the parent (as `ParentEntitySystem`'s `Context` already
-did) and drops the child's `TransformAttachment`. This fixes D3, and makes the independent use of the two relations
-actually safe.
-
-One prediction here did not hold up. The expectation was that the 6.1 index would turn "which children do I unlink"
-into a lookup; in practice the listener is registered **per child context**, exactly as `ParentEntitySystem` does it,
-because a single per-parent listener would have needed its own count of *bound* children to know when to register and
-unregister — the index deliberately includes queued children, which must not register one. Per-child is less state
-and mirrors the sibling system. The index is still what makes the direction answerable at all; this fix just did not
-need to ask. Details, including the stale-dispatch guard, are in D3.
-
-### 6.4 `SendUp` / `SendDown`
-
-Now cheap — 6.1 exists, so `SendDown` is a traversal that already terminates and `SendUp` is
-`ParentEntitySystem.findRoot`'s walk with a visitor. Replaces the manual `findRoot`-and-dispatch idiom. Not built;
-nothing in the tree asks for it yet.
-
-### 6.5 Document the couplings — **DONE 2026-08-24**
-
-`TransformAttachment` needed what `ParentEntity` already had. All three halves are now on the component: the
-`parent`-immutability note (D4), the non-uniform-scale and drift caveat (D10), and the statement that without a
-lifetime relation an attachment does not survive its parent — which, since D3, means the component is removed and the
-entity becomes a world-space root rather than freezing.
-
-Both `parent` fields also now say *why* they must not be mutated in place: each system resolves the parent once at
-link and indexes the edge at the same moment, so an in-place write desynchronises both.
-
-## 7. What is not worth taking
-
-- **`Origin`-defaults-to-parent.** §4.1 — meep's two-field split is better and matches the codebase's stated
-  preference for uniform control flow over sentinels.
-- **A child list as stored, authored state.** §4.2 — take the enumerability, not the component. Scene Graph can afford
-  a stored child list because its hierarchy *is* the entity and there is only one writer; in an ECS the same list
-  becomes a second, user-writable copy of an edge that already exists on the child, with no mechanism keeping the two
-  ends honest. Derive it in the system instead. This is the one place where the conventional engine answer and
-  `ChildEntities` agree with each other and are both wrong.
-- **Tags.** A zero-field component already is a tag, and stays typed.
-- **The five-phase lifecycle, wholesale.** The valuable half is the ordering guarantee that removes the retry queues;
-  adopting five named phases across every system is a much larger change than the problem warrants. If anything here
-  is worth doing it is the *guarantee*, not the vocabulary.
-- **Scoped access.** A Verse language feature with no analogue here.
-
-## 8. The one thing this review would change first
-
-Not any single defect — **`EntityNode`'s status.**
-
-It is documented as sugar and treated as sugar, but it holds the local transform that animation writes to, so it is
-load-bearing runtime state. Every gap in this document traces back to that: reparenting is broken because the fix
-belongs on the components but the API lives on the node; the transform has two homes because the node keeps its own;
-subtree queries scanned because the node had `children` and nothing at the dataset level did.
-
-That last clause is no longer true, which sharpens the question rather than answering it: since §6.1 there **is** a
-child enumeration below the node, owned by the systems. `EntityNode.children` is now a second answer to a question the
-dataset can already answer — a list of nodes, only available to whoever built the tree, next to a list of entity ids
-available to anything holding an entity id.
-
-Decide which one is the hierarchy. If it is the components, `EntityNode` must become genuinely stateless — its
-`transform` accessor forwarding to `attachment.transform`, its `children` reading through `ParentEntitySystem` — and
-animation binds to components. If it is `EntityNode`, then say so, and stop describing it as sugar.
-
-Scene Graph made this choice: the entity is the hierarchy, `transform_component.LocalTransform` is the one local
-transform, and there is no second object graph. That is the part of the design worth copying — not the API surface.
-
----
-
-## Sources
-
-Unreal / Scene Graph — Epic documentation and reporting:
-
-- [Getting Started in Scene Graph in Fortnite](https://dev.epicgames.com/documentation/fortnite/getting-started-in-scene-graph-in-fortnite)
-- [entity class — Verse API reference](https://dev.epicgames.com/documentation/en-us/fortnite/verse-api/versedotorg/scenegraph/entity)
-- [component class — Verse API reference](https://dev.epicgames.com/documentation/en-us/fortnite/verse-api/versedotorg/scenegraph/component)
-- [Transforms in Scene Graph](https://dev.epicgames.com/documentation/en-us/fortnite/transforms-in-scene-graph-in-unreal-editor-for-fortnite)
-- [Scene Graph Best Practices](https://dev.epicgames.com/documentation/fortnite/scene-graph-best-practices-in-fortnite?lang=en-US)
-- [Scene Graph is Now Available as an Experimental Feature in UEFN](https://www.fortnite.com/news/scene-graph-is-now-available-as-an-experimental-feature-in-uefn)
-- [Unreal Engine 6 Will Combine UEFN and UE Into a "Unified Engine"](https://80.lv/articles/upd-unreal-engine-6-will-combine-uefn-and-ue-into-a-unified-engine)
-- [10 things CG artists need to know about Unreal Engine 6](https://www.cgchannel.com/2026/06/10-things-cg-artists-need-to-know-about-unreal-engine-6/)
-- [Mass Framework overview](https://vrealmatic.com/unreal-engine/mass) — for the Scene Graph ≠ Mass distinction
+# Hierarchy in meep's ECS — a review against Unreal 6 / Scene Graph
+
+**Date:** 2026-08-23
+**Subject:** `ParentEntity`, `TransformAttachment`, `EntityNode`, and the systems behind them
+**Comparator:** Epic's Scene Graph — the entity/component framework that UE6 is being built on
+
+**Status, 2026-08-24.** §6.1 landed: both systems now keep a parent → children index
+(`ecs/hierarchy/EntityChildIndex.js`), which closed **D5**, **D7**, **D8** and **D11**, and made **D3** small enough
+to fix in the same pass. **D4** was addressed the day before. Still open: **D1**, **D2**, **D6**, **D9**, **D10**, and
+the question in §8. Sections below are written in the tense of what is true now; the reasoning that led there is
+unchanged.
+
+---
+
+## 0. Verdict up front
+
+The **core split is right, and it is a better decomposition than Unreal's.** meep separates *lifetime* parenting
+(`ParentEntity`) from *spatial* parenting (`TransformAttachment`) into two independent components. Scene Graph has one
+hierarchy that means lifetime, and bolts a spatial override onto it (`transform_component.Origin`). meep's version is
+the more honest model: two relations that are genuinely independent are stored as two relations, rather than one
+relation plus an escape hatch.
+
+The **propagation is also better than I expected.** I assumed the signal cascade would re-do work exponentially in
+depth. It does not — measured, each descendant is recomputed **exactly once** per root change, at any depth. That is
+optimal, and it is achieved without a sort, a level index, or a dirty-flag pass.
+
+What is weak is everything *around* that core:
+
+- `EntityNode`, described as "syntactic sugar", is not sugar. It holds live state (the local transform, the
+  subscriptions) that the ECS does not have, and animation binds to it. It is a **shadow object graph** — the exact
+  thing an ECS hierarchy exists to remove.
+- **Live reparenting does not work.** One path silently strips the spatial link (verified, repro below); the other
+  asserts. Scene Graph treats reparenting as an ordinary operation.
+- ~~**Children are not stored anywhere.** Every "give me the subtree" operation is a full scan of the dataset, so
+  subtree work is O(nodes × entities-in-world).~~ **Fixed** — each system now owns the back-links (§6.1).
+- Three parallel attachment mechanisms exist (`TransformAttachment`, `Attachment`, plus ad-hoc `transform.subscribe`
+  closures in `MeshSystem3`). A fourth component, `ChildEntities`, was dead code and has been deleted.
+
+Severity-ordered defect list is in §5. Six of the eleven are correctness, and two of those I reproduced.
+
+---
+
+## 1. Scope and method
+
+**Read in full:** `ecs/parent/*` (`ParentEntity`, `ParentEntitySystem`, `ChildEntities` (since deleted), `EntityNode`,
+`EntityNodeFlags`, `entity_node_compute_bounding_box`), `ecs/transform-attachment/*` (`TransformAttachment`,
+`TransformAttachmentSystem`, `transform_attachment_parent_of`, `transform_attachment_find_descendant_by_name`),
+`ecs/attachment/*` (`Attachment`, `AttachmentSystem`, `AttachmentBinding`, `TransformAttachmentBinding`,
+`BoneAttachmentBinding`), plus `Entity`, `Transform`, and the relevant parts of `EntityComponentDataset`,
+`EntityManager` and `BinaryBufferSerializer`.
+
+**Consumers surveyed:** `shade_node_to_entity_composition`, `three_object_to_entity_composition`, `MeshSystem3`,
+`SGMeshSystem`, `ColliderObserverSystem`, `HierarchicalEntityListView`, `bind_property_writer`,
+`sg_hierarchy_compute_bounding_box_via_parent_entity`.
+
+**Measured, not assumed.** Four throwaway specs were run against the real systems (no mocks) and then deleted. Every
+number in §2.3, §5 D1, D2 and D10 is output from those runs, quoted verbatim. Where I state something I only read and
+did not execute, it says so.
+
+**On the Unreal side — read this before trusting §3.** Epic announced at State of Unreal (June 2026) that UE6 unifies
+UE and UEFN, and that Actors and Blueprints will eventually be deprecated in favour of Verse plus Scene Graph, with
+conversion tools and a multi-year transition. Scene Graph itself shipped first in UEFN and is documented there as
+experimental/beta. **The public documentation is the UEFN surface**, so the API names below are the Verse ones. Epic
+has not published Scene Graph's internal storage, so anything about *how* it stores hierarchy is unknown, and I make
+no claims about it.
+
+One terminology correction worth making, because it changes what "compare against Unreal's ECS" means: **Scene Graph
+is not Unreal's ECS.** Unreal's data-oriented ECS is **Mass** (archetype-based; components are "fragments", systems
+are "processors"), built for crowds and traffic. Scene Graph is an *entity/component gameplay framework* — the Actor
+replacement. It is Scene Graph, not Mass, that is the right comparator for meep's hierarchy, and that is what this
+document uses. Mass has no user-facing hierarchy to compare against.
+
+---
+
+## 2. What meep has today
+
+### 2.1 Four mechanisms, not one
+
+| Mechanism | Means | Propagated by | Status |
+|---|---|---|---|
+| `ParentEntity { entity }` | **Lifetime.** Parent dies → child dies. | `ParentEntitySystem` listens for `EntityRemoved` on the parent, removes the child. | Live |
+| `TransformAttachment { transform, parent, flags }` | **Space.** Child world = parent world × local. | `TransformAttachmentSystem`, via `Transform` change signals. | Live |
+| `Attachment { parent, socket, transform }` | **Space, via a named socket / bone.** | `AttachmentSystem`, via `AttachmentBinding`s, polled every frame. | Live |
+| ad-hoc `transform.subscribe(follow)` | **Space, hand-rolled.** | A closure in `MeshSystem3` (line ~558) copying one transform to another. | Live |
+| ~~`ChildEntities { entities[] }`~~ | — | — | **Deleted** (D5). Was dead, and the wrong shape — see §4.2. |
+
+`EntityNode` sits on top of the first two as an authoring façade.
+
+The overlap between rows 2–4 is the first thing to notice. `TransformAttachmentBinding` (row 3's transform case) does
+what `UpdateContext` (row 2) does, with a socket offset spliced in, using matrices instead of `Transform` composition —
+and it carries a `TODO` saying so. Row 4 is row 2 with the local transform hard-coded to identity.
+
+### 2.2 The two relations are genuinely independent — and that is the good part
+
+```
+ParentEntity.entity        →  "when that entity dies, I die"
+TransformAttachment.parent →  "my transform is relative to that entity"
+```
+
+Nothing requires them to name the same entity. That is a real capability: a UI marker can be spatially attached to a
+unit's head while being owned by the HUD; a compound rigid body's colliders are `ParentEntity`-owned by the body
+(which is exactly how `ColliderObserverSystem` finds them) without necessarily composing transforms through it.
+
+Scene Graph cannot express this as two facts. It has one hierarchy — which means lifetime — and then
+`transform_component.Origin` to say "actually, compose me against *that* entity instead". Same expressive power,
+reached by exception rather than by construction.
+
+### 2.3 How the transform composition actually behaves (measured)
+
+`TransformAttachmentSystem` builds an `UpdateContext` per attached entity holding `{attachment, transform, entity,
+parent_transform}` and subscribes it to *both* the parent's world `Transform` and the attachment's local `Transform`.
+Any change to either fires `ctx.update()`, which is one `m4_multiply` plus a decompose back into the child's world
+`Transform` — whose own position/rotation/scale setters fire, waking the grandchild's context. Propagation is a
+synchronous, re-entrant, depth-first cascade with no flush point.
+
+Measured on a straight chain, counting writes to each descendant's TRS channels for **one** root change:
+
+```
+depth=4  translate: pos-writes=3  rot-writes=0  scale-writes=0   across 3 descendants
+depth=4  rotate:    pos-writes=3  rot-writes=3  scale-writes=3   across 3 descendants
+depth=8  translate: pos-writes=7  rot-writes=0  scale-writes=0   across 7 descendants
+depth=8  rotate:    pos-writes=7  rot-writes=7  scale-writes=7   across 7 descendants
+depth=16 translate: pos-writes=15 rot-writes=0  scale-writes=0   across 15 descendants
+depth=16 rotate:    pos-writes=15 rot-writes=15 scale-writes=15  across 15 descendants
+```
+
+**One recompute per descendant, every time.** No redundancy at any depth. The `Vector3.set`/`Quaternion.set` equality
+guards are doing real work here: a pure translation never wakes a rotation listener. This is a good design and it
+should be said plainly, because the rest of this document is mostly criticism.
+
+Two costs come with it, both real:
+
+**It is observable mid-cascade.** An observer of a descendant's `Transform` is called *during* propagation, when the
+transform is only partly updated. Measured on a depth-3 chain under one 90° root yaw, an observer of the leaf sees:
+
+```
+[0] pos(0.000,-2.000)  rotY(0.000)     ← position already final, rotation still stale
+[1] pos(0.000,-2.000)  rotY(0.707)     ← settled
+```
+
+State `[0]` is a pose that never existed. Anything that *accumulates* from a transform callback — a motion trail, a
+velocity estimate, a moved-event, a physics impulse — integrates a torn pose. Renderers get away with it because the
+last write before the frame ends is correct.
+
+**Every level does a decompose/recompose round-trip**, and it is lossy. Measured on a chain with **no scaling
+anywhere**, all-rotation locals:
+
+```
+depth=8:  leaf world scale = (1.00000009045938,  1, 1.00000009045938)
+depth=32: leaf world scale = (1.0000006507070245, 1, 1.0000006507070245)
+depth=64: leaf world scale = (1.0000014229381489, 1, 1.0000014229381489)
+```
+
+The exact answer is `(1,1,1)` at every depth. The drift grows with depth, and — because it is a genuine change — it
+also fires a spurious `scale.onChanged` at every level on every rotation, which is where the `scale-writes=N` column
+above comes from. Anything subscribed to scale is woken by pure rotation.
+
+The same round-trip discards shear outright. Root scaled `(4,1,1)`, child yawed 45°:
+
+```
+mid  world scale stored as (2.9155, 1.0000, 2.9155)
+leaf world matrix row0    = 2.8284, 0.0000, -0.7071
+```
+
+The true composed basis is non-orthogonal; TRS cannot hold it, so it is silently best-fitted. A mesh under a
+non-uniformly-scaled rotated parent draws wrong. **Scene Graph shares this limitation** — its transform is TRS too —
+but Unreal documents the non-uniform-scale caveat and meep does not.
+
+### 2.4 `EntityNode` is not syntactic sugar
+
+Its own docstring says "syntactic sugar on top of `TransformAttachment` and `ParentEntity`". It is not, on three
+counts:
+
+1. **It owns a third copy of the local transform.** `EntityNode.__transform` is the local transform; the component's
+   `attachment.transform` is *also* the local transform. They are synced one-way, node → component, by
+   `__transform_sync_down` on change. Write the component directly and the node is stale, with no way to notice.
+2. **It is required at runtime, not just at authoring time.** `bind_property_writer` binds animation curves to
+   `node.transform.position` / `.rotation` / `.scale` — the *node's* transform, not the component's. Every animated
+   model therefore has to retain its `EntityNode` tree for as long as it animates. The object graph an ECS hierarchy
+   is supposed to replace is still there, alive, next to the dataset.
+3. **It carries behaviour the components do not have** — `build`/`destroy` ordering, `on.built`/`on.destroyed`,
+   listener attach/detach, `root`, `traverse`. None of that is reachable from an entity id. Anything holding only an
+   entity id cannot participate.
+
+So there are two ways to express a hierarchy in meep, and they are not interchangeable: components are the storage,
+`EntityNode` is the API, and the API is only available to whoever constructed the tree.
+
+---
+
+## 3. What Scene Graph does
+
+From Epic's UEFN documentation (see §8 for links):
+
+**Entities are containers; components supply data and behaviour.** One component instance per type per entity — need
+two, make two entities. Components are constructed with a pointer to their owning entity and **cannot be moved between
+parents**.
+
+**One hierarchy, and it means lifetime.** "Parenting represents object lifetime: if the parent is removed from the
+scene, so are the sub-objects." One simulation entity is the root; every map entity is a descendant of it.
+
+**Children are stored and enumerable.** `GetEntities()` returns the direct children; `GetParent()` walks up;
+`AddEntities(...)` adds children **and reparents them if they already have a parent**; `RemoveFromParent()` detaches,
+and the entity can be re-added later.
+
+**Space is layered on top, by exception.** `transform_component` holds `LocalTransform` plus an optional `Origin`. If
+`Origin` is unset, the entity composes against its parent. If set, it composes against whatever entity `Origin` names
+— "a child can orbit around a sibling rather than its parent". API is `Get/SetLocalTransform`, `Get/SetGlobalTransform`
+(both of which implicitly create the component), and `SetOrigin` / `GetOrigin[]` / `ResetOrigin`.
+
+**Lifecycle is a phase machine, not a boolean.** Components get `OnAddedToScene` → `OnBeginSimulation` →
+`OnSimulate` (suspending/async) → `OnEndSimulation` → `OnRemovingFromScene`. Adding a child to an in-scene parent
+"advances the child through lifetime phases to match parent state". Component queries only become valid after
+`OnAddedToScene`.
+
+**The hierarchy is an event bus.** `SendUp(event)` / `SendDown(event)`, with consumption halting propagation.
+
+**Entities carry tags** — `AddTag`, `ContainsAnyTag`, `RemoveAllTagsExcept`, etc.
+
+**Access is scoped.** `GetEntities()` and `GetComponents()` return what is "accessible from the calling context" —
+visibility is part of the model, not just a convention.
+
+**Their own performance guidance** is: don't re-scan the tree during gameplay; find what you need once in
+`OnBeginSimulation`, cache the references or subscribe to events, and react to events rather than searching again.
+Don't broadcast events across large portions of the graph.
+
+---
+
+## 4. Head-to-head
+
+| | meep | Scene Graph |
+|---|---|---|
+| Lifetime relation | `ParentEntity.entity` | the hierarchy itself |
+| Spatial relation | `TransformAttachment.parent` — **independent** | `transform_component.Origin`, defaulting to the parent |
+| Local transform | `TransformAttachment.transform` (+ a shadow copy on `EntityNode`) | `transform_component.LocalTransform` |
+| World transform | stored, as a decomposed `Transform` component | queried via `GetGlobalTransform()` |
+| Children stored? | Yes — a system-owned index, not a component (§4.2) | Yes — `GetEntities()` |
+| Reparenting | **Broken / unsupported** (§5 D1, D2) | `AddEntities` reparents as a normal operation |
+| Lifecycle | `isBuilt` boolean; `link`/`unlink` on systems | five explicit phases, propagated to children |
+| Events on the tree | none | `SendUp` / `SendDown` with consumption |
+| Tags | none (`Name` only) | first-class |
+| Cycle safety | detected on read, throws | not documented |
+| Serialization | asymmetric — spatial survives, lifetime does not (§5 D6) | prefab-based |
+| Shear under non-uniform scale | lost silently | lost (documented) |
+
+### 4.1 The relation split — meep wins, and should not follow Unreal here
+
+Worth stating explicitly because it is tempting to read Unreal's design as the newer one and therefore the better one.
+It is not, on this axis. `Origin`-defaults-to-parent is a **"unset means auto" sentinel**: one field with two meanings,
+where the common case is invisible and the uncommon case is an override. meep's two independent fields say the same
+thing with uniform control flow — the common case (`TransformAttachment.parent === ParentEntity.entity`) is written
+out rather than implied.
+
+This also happens to be the shape the codebase already prefers. Adopting `Origin` would be adopting a sentinel.
+
+The cost meep pays is that **the coupling is real but undocumented**: `TransformAttachment` alone is not safe when the
+parent can die (§5 D3). `ParentEntity` is what makes it safe. Nothing says so, and `transform_attachment_parent_of`'s
+docstring — which is otherwise the best documentation in this area — describes the spatial hierarchy as if it stood
+alone.
+
+### 4.2 Children were not stored — the biggest structural gap, now closed
+
+**Was:** `ParentEntitySystem.findChildrenOf` scanned **every** `ParentEntity` component in the dataset to find one
+entity's children, and `traverse` called it once per node. So computing a subtree bounding box (which
+`sg_hierarchy_compute_bounding_box_via_parent_entity` does exactly this way) was **O(subtree × all-parented-entities)**.
+
+Scene Graph stores children and Epic's own guidance is *still* "don't scan the tree during gameplay, cache in
+`OnBeginSimulation`". meep was scanning a structure that was a full dataset sweep rather than a stored list.
+
+**Now:** both systems own a parent → children index (`ecs/hierarchy/EntityChildIndex.js`), so `findChildrenOf` is a
+lookup and `traverse` is linear in the subtree. The shape and the reasoning are below; what actually landed is in §6.1.
+
+Two things this did **not** change, deliberately:
+
+- `transform_attachment_find_descendant_by_name` still scans every `Name` and walks up from each candidate — that is
+  the bone-lookup path, and it searches by *name* first, which no parent → children index answers. Rewriting it as a
+  downward walk over the spatial index is now possible and is the obvious follow-up, but it is a different search.
+- The editor's `HierarchicalEntityListView` still builds its own `Map<parent, children[]>`. It looked like the missing
+  index implemented privately, and it is not quite: the view excludes editor-owned entities from the tree entirely, so
+  its map is a *filtered* one, and it needs a full entity sweep regardless to find the roots — entities with no
+  `ParentEntity` at all, which no children index knows about. Swapping in the real index would mean filtering on every
+  read and taking a dependency on a running system, for no sweep saved. Left alone.
+
+#### Where the index belongs — *not* in a component
+
+The obvious move, and the one most engines make, is a `ChildEntities` component. meep had one already
+(`parent/ChildEntities.js`, dead). **That was the wrong shape, and it was deleted rather than revived.**
+
+A child list stored as a component is *derived data promoted to authored data*. The consequences are all bad and all
+structural:
+
+- **It is a two-place invariant.** `ParentEntity` lives on the child and `ChildEntities` lives on the parent — two
+  entities, two components, one fact. Nothing in the type system or the dataset keeps them agreeing. They can drift,
+  and the drift is silent.
+- **It is user-writable.** Being a component makes it authorable, mutable, and reachable from any system. Every one of
+  those is an opportunity to corrupt an index that has one correct value.
+- **It is a burden at the layer least able to carry it.** Whoever builds a hierarchy now has to maintain both ends of
+  every edge, for information the engine can derive.
+- **It doubles the state footprint** of every parent, and it has to be excluded from serialization by hand — one more
+  thing to get wrong alongside D6.
+
+The alternative, and what was built, is to hold the back-links **at the system level**: `ParentEntitySystem` already
+observes every entity that gains or loses a `ParentEntity`, so it maintains a private parent → children index with no
+component, no authored state, and nothing for a user to desynchronise. One writer, one source of truth, rebuilt from
+scratch on load.
+
+The usual objection is ergonomics — a consumer now has to reach for the system instead of just calling `getComponent`.
+That objection does not survive contact with the actual call pattern: **`ChildEntities` would not have avoided it.** A
+component gives you one level of children as entity ids; to go a level deeper you need `getComponent(child,
+ChildEntities)`, so you are already reaching for the dataset. Component and system are equally indirect, and the system
+version is the one that cannot be wrong. `EntityManager.getSystem(SystemClass)` is typed on the class, so this stays
+inside the codebase's preference for typed lookup over string-keyed registries.
+
+The migration cost was also much smaller than it looked — see §6.1.
+
+### 4.3 Reparenting
+
+Scene Graph: `AddEntities` reparents, and advances the child through lifecycle phases to match the new parent.
+
+meep: **neither path works.** Direct `.parent =` assignment strips the spatial link (D1, reproduced). `addChild` of an
+already-built node throws (D2, reproduced). There is no supported way to move a live subtree.
+
+This is the single largest functional gap, and it is not exotic — "pick this up", "get in the vehicle", "re-dock this
+panel" are all reparenting a live subtree.
+
+### 4.4 Lifecycle phases
+
+meep has one bit (`isBuilt`) plus system `link`/`unlink`. The consequence is `TransformAttachmentSystem`'s retry
+queue: a child whose parent has not appeared yet cannot be linked, so it is parked and retried at 32 entries per
+frame, forever, with no diagnostic if the parent never arrives. `AttachmentSystem` has its own separate `waiting`
+array doing the same thing.
+
+That queue is *compensating for the absence of ordering guarantees*. Scene Graph's answer is that a child added to an
+in-scene parent is advanced to match the parent's phase — the "parent isn't ready yet" state is structurally
+impossible rather than polled for.
+
+Not a defect. But two hand-rolled retry queues is what the missing phase model costs.
+
+### 4.5 Events, tags, scoping
+
+meep has none of `SendUp`/`SendDown`, tags, or context-scoped access. Of the three:
+
+- **`SendUp`/`SendDown` is worth having** and is cheap once children are stored. The idiom it enables — a hit on a
+  limb bubbling to the creature, a "prefab" root broadcasting down — is currently done by walking to
+  `ParentEntitySystem.findRoot` and dispatching manually.
+- **Tags** duplicate what a component already does in meep. Skip; a zero-field component is the same thing and stays
+  typed, which is what this codebase prefers over string keys.
+- **Scoped access** is a Verse-language concern. Not applicable.
+
+---
+
+## 5. Defects
+
+Ordered by severity. **[repro]** = I reproduced it against the real systems. **[read]** = from reading only.
+Entries marked **FIXED** were closed on 2026-08-24 by the work in §6.1 and §6.3; the original finding is kept so the
+reasoning stays readable, with what changed appended.
+
+---
+
+**D1 — `EntityNode.parent` setter destroys the spatial link. [repro]** — *correctness, high*
+
+`EntityNode.js:240-270`. The setter removes both components up front:
+
+```js
+let parent_entity = this_entity.removeComponent(ParentEntity);
+let attachment    = this_entity.removeComponent(TransformAttachment);   // returns the instance
+
+if (node !== null) {
+    ...
+    this_entity.add(parent_entity);                    // ParentEntity IS re-added
+
+    if (attachment === null) {                         // ...but it is NOT null,
+        attachment = this.__safe_get_attachment();     //    so this never runs
+    }
+    attachment.parent = parent_entity_id;              // mutates a DETACHED component
+}
+```
+
+`Entity.removeComponent` returns the removed instance (`Entity.js:286`), so the `=== null` branch is dead whenever the
+node was already parented. The re-add only happens through `__safe_get_attachment()`, which is skipped.
+
+Reproduced — build `a → b`, then assign `b.parent = c` directly:
+
+```
+after build,     b has TransformAttachment: true
+after reparent,  b TransformAttachment: null
+after reparent,  b ParentEntity: 2   (c.id: 2)   ← lifetime link correct
+dataset has TransformAttachment on b: undefined  ← spatial link gone
+```
+
+The child keeps its new owner and silently stops following it in space; its world `Transform` freezes at its last
+value. `addChild()` happens to escape this because `removeChild()` runs first and clears the component via the
+`node === null` path — so the bug is confined to the public setter, which is the documented way to reparent.
+
+Fix is one line: drop the `if (attachment === null)` guard and always call `__safe_get_attachment()`.
+
+---
+
+**D2 — live reparenting asserts in dev, silently no-ops in prod. [repro]** — *correctness, high*
+
+`EntityNode.addChild` calls `node.build(dataset)` when the receiving parent is built; `build` opens with
+`assert.notOk(this.__entity.isBuilt, 'Already built')`. Reproduced: `addChild` of a built node into a built parent
+throws `"Already built"`.
+
+Asserts are compiled out of production builds. In production the assert vanishes and `Entity.build` early-returns
+(`Entity.js:442-449`), so it degrades to a partial no-op rather than corruption — but combined with D1 the node can
+end up owned-but-not-attached with no error anywhere. **Dev throws, prod silently misbehaves**, which is the worse of
+the two orderings.
+
+---
+
+**D3 — a child was not detached when its spatial parent died. [read]** — *correctness, high* — **FIXED 2026-08-24.**
+
+`UpdateContext` captured `parent_transform` at link time and subscribed to it. Nothing observed the *parent's*
+removal. When the parent entity was destroyed:
+
+- the child still had `TransformAttachment` + `Transform`, so the system's `unlink` was never called;
+- `this.__contexts[entity]` kept holding the context, which kept holding the dead parent's `Transform` alive;
+- the child composed against a transform nothing would ever update again — it froze, silently.
+
+`ParentEntity` masked this whenever both components named the same entity, because the child got destroyed too. It was
+exposed exactly when the two are used independently — i.e. the capability §4.1 credits as meep's advantage.
+
+**The fix**, mirroring what `ParentEntitySystem`'s `Context` already did: `UpdateContext` subscribes to its parent's
+`EntityRemoved` in `link()` and unsubscribes in `unlink()`, and on removal it takes `TransformAttachment` off the
+child. The child survives with the world transform it had, as a root, and its own subtree keeps composing against it.
+Dropping the component rather than quietly tearing the context down is what makes the detach observable, and it routes
+the teardown through the system's ordinary `unlink` path.
+
+Two details worth keeping:
+
+- **It is registered per child, not per parent, so the §6.1 index is not what makes it work.** The index would have
+  needed a separate count of *bound* children to know when to add and drop a single per-parent listener — queued
+  children are in the index but must not register — which is more state than one listener per context. The index is
+  still what makes "which children point at me" answerable; this particular fix just did not need to ask.
+- **A stale dispatch is real and is guarded.** Entity event dispatch copies its listener list before invoking it, so
+  when an entity carries *both* relations and the lifetime one destroys it first, the spatial detach still arrives —
+  for an entity that no longer exists. `UpdateContext` tracks whether it is linked and ignores the late call. This is
+  ordering-dependent (whichever system linked first is called first) and is covered both ways round in the spec.
+
+**Still not covered:** a child that is still *queued* when its parent dies. It never bound, so it never subscribed, and
+it goes on retrying against an id that may be recycled. That is the pre-existing gap §4.4 describes — the retry queue
+has no diagnostic for a parent that never arrives, and now also none for one that leaves.
+
+---
+
+**D4 — mutating `TransformAttachment.parent` is silently ignored. [read]** — *correctness, medium* — **ADDRESSED
+2026-08-24**, documented on the field to match `ParentEntity`'s existing constraint.
+
+`UpdateContext.update()` reads `this.parent_transform`, resolved once at link. Writing `attachment.parent = other`
+afterwards changes nothing; the entity keeps composing against the old parent. `ParentEntity` documents this
+constraint ("Must not be mutated while the component is attached to a dataset"); `TransformAttachment` did not, and
+its field is plain and public.
+
+Worth noting that this contract is **load-bearing for §6.1, not just hygiene.** A system-owned child index is correct
+precisely because `link`/`unlink` are the only transitions a parent reference can undergo. If either component's
+`parent` field could be rewritten in place, the index would need change detection to stay honest, and the argument for
+keeping it out of a component would weaken. Documenting the immutability is what makes the cheap index sound.
+
+---
+
+**D5 — `ChildEntities` was dead code, and the wrong shape. [repro — zero references]** — *hygiene, medium* —
+**FIXED 2026-08-24.**
+
+Defined in `parent/ChildEntities.js`, referenced nowhere outside its own file.
+
+**Deleted.** Per §4.2 it was not a stub to finish — a component is the wrong home for a derived back-link, and leaving
+the file present implied both that a child index existed and that a component was where one should go. Neither was
+true. The index belongs to `ParentEntitySystem` (§6.1), and now lives there.
+
+---
+
+**D6 — serialization is asymmetric between the two hierarchies. [read]** — *correctness, medium*
+
+`ParentEntity.serializable = false`, commented "Entity IDs are transient, serialization is not applicable".
+`TransformAttachment` sets no such flag, and `isComponentClassSerializable` defaults to serializable
+(`BinaryBufferSerializer.js:15`) — so its `parent` field, **also a raw entity id**, is written and read back.
+
+Entity ids do survive a round-trip (`BinaryBufferDeSerializer` calls `createEntitySpecific`), so this is not
+straightforwardly broken. But the two components make opposite decisions about the same kind of data, and the result
+is that a saved scene reloads with its **spatial** hierarchy intact and its **lifetime** hierarchy gone. Given D3,
+that reload also lands in exactly the configuration where an attachment is unsafe.
+
+Whichever way it is resolved, the two should agree.
+
+§6.1 sharpened this rather than changing it: the child index is rebuilt from the child-side components on load, so a
+scene that reloads without its `ParentEntity` components reloads with an empty lifetime index too. The index does not
+cause the omission, it just stops it being invisible.
+
+---
+
+**D7 — subtree operations were O(subtree × world). [read]** — *performance, medium* — **FIXED 2026-08-24.**
+
+`ParentEntitySystem.findChildrenOf` swept every `ParentEntity` in the dataset per node; `traverse` called it per node.
+`sg_hierarchy_compute_bounding_box_via_parent_entity` and `transform_attachment_find_descendant_by_name` (the bone
+lookup) both paid it.
+
+The index in §6.1 fixed the first: `findChildrenOf` is a lookup and `traverse` is linear in the subtree. The bone
+lookup is untouched — it searches by name, which this index does not answer (§4.2).
+
+Also in `traverse`: `path.concat(entity)` allocated a new array per node per level, making cycle detection O(depth²) in
+allocations for a deep tree. The rewritten walk pushes and pops one shared path array instead, and cycle detection is
+now O(depth) comparisons per node against no allocation at all.
+
+---
+
+**D8 — the cycle checker was a shared fixed buffer. [read]** — *correctness, low* — **FIXED 2026-08-24.**
+
+`ParentEntitySystem` used a module-level `Uint32Array(1024)` for `findRoot` and `isAncestorOf`, with no bounds check
+on `loop_checker_array[count++]`. Two consequences: writes past 1024 were silently dropped by JS typed arrays, so a
+hierarchy deeper than 1024 stopped detecting cycles and could spin forever; and because the buffer was shared and
+un-reentrant, a `findRoot` called from inside a `traverse` callback clobbered the outer walk's state.
+
+Depth > 1024 is not realistic. Re-entrancy was — `traverse` takes a user callback.
+
+Both walks now keep their own path array, which is per call and grows, so neither failure mode exists. It fell out of
+moving these two off the static-plus-`ecd` shape onto the system; the module global, `check_loop` and `genLoopString`
+went with it. A 2048-deep chain is in the spec.
+
+---
+
+**D9 — transform sockets update twice per frame. [read]** — *performance, low*
+
+`TransformAttachmentBinding.link()` subscribes to the parent's and the attachment's transform changes, *and*
+`AttachmentSystem.__updateAll()` calls `binding.update()` for every binding every frame unconditionally. Either the
+subscription or the sweep is redundant. (`BoneAttachmentBinding` genuinely needs the per-frame sweep — its pose is a
+query with no change signal — so the sweep is the one to keep, and the `TransformAttachmentBinding` subscriptions are
+the removable half.)
+
+---
+
+**D10 — decompose round-trip drifts and drops shear. [repro]** — *correctness, low-to-medium*
+
+Numbers in §2.3. Scale drifts to ~1.4e-6 over 64 rotation-only levels and fires spurious `scale.onChanged` at every
+level; shear from a non-uniformly-scaled rotated parent is silently best-fitted away.
+
+Not cheaply fixable — it is inherent to storing the world transform as a decomposed `Transform` — and Unreal has the
+same limitation.
+
+The documentation half is **done**: `TransformAttachment` now carries the non-uniform-scale caveat and the drift
+figure. The behaviour is unchanged and the defect stays open on that basis. Still worth considering: whether
+`UpdateContext.update()` should compose into the child's `matrix` and skip the decompose for consumers that only read
+the matrix.
+
+---
+
+**D11 — neither system had a spec. [repro — no such files]** — *test coverage, medium* — **FIXED 2026-08-24.**
+
+There was no `TransformAttachmentSystem.spec.js` and no `ParentEntitySystem.spec.js`. `TransformAttachment.spec.js` and
+`EntityNode.spec.js` between them test `setFlag`/`clearFlag`/`getFlag`/`writeFlag` — twice, once each, in identical
+form — plus JSON round-trip and `addChild`/`removeChild` bookkeeping on *unbuilt* nodes.
+
+**The composition contract itself was untested.** Nothing asserted that a child's world transform equals parent ×
+local, that a change propagates, that a chain composes, or that a queued attachment links when its parent arrives.
+Nine other specs register both systems, but as fixture scaffolding — `MeshSystem3.spec.js` registers them so a model
+can expand, not to check them.
+
+Both specs now exist, on real `EntityManager`/`EntityComponentDataset` objects, and cover the composition contract,
+the index (empty/one/many, ordering, child removal, parent removal, id recycling, snapshot semantics), the queue path,
+subtree traversal against the full-scan implementation it replaced, cycles, and the D3 detach in both dispatch orders.
+`EntityChildIndex` has its own spec for what the systems cannot reach through their own API. The flag tests remain the
+vacuous-smoke-test shape and were left alone; they are not what this defect was about.
+
+Note that D1 and D2 are both immediately visible from a five-line test, which is why they are still here.
+
+---
+
+## 6. What is worth taking from Scene Graph
+
+In order of value per unit of change. Note that the first item takes Scene Graph's *capability* while explicitly
+rejecting its *storage* — the useful comparison here is not "copy what Unreal did".
+
+### 6.1 Store children — as a system-owned index, not a component — **LANDED 2026-08-24**
+
+Take Scene Graph's *capability* (children are enumerable in O(children)) and reject its *storage*, because meep's
+system layer can derive the same thing without asking the user to maintain anything. Reasoning in §4.2; this is what
+was built.
+
+`ecs/hierarchy/EntityChildIndex.js` holds the structure — a sparse array of parent id → ascending child ids — and both
+systems own one, as `__children`. It has its own spec for the ordering and copy-out contracts.
+
+**The choke points already existed and were already overridden.** `ParentEntitySystem` extends `AbstractContextSystem`,
+whose `link()`/`unlink()` fire exactly once per entity gaining or losing a `ParentEntity`. `ParentEntitySystem`'s own
+`Context` already overrode both, and already read `this.components[0].entity` to subscribe to the parent's removal.
+Maintaining the index is one insert in `Context.link()` and one remove in `Context.unlink()`, beside code that was
+already there for exactly the same edge.
+
+Design notes that mattered, and how each was settled:
+
+- **Store entity ids, never contexts.** `AbstractContextSystem` pools its contexts through `ObjectPoolFactory` and
+  reuses them after `unlink`. An index holding context references would alias recycled objects. The index stores ids.
+- **Define child order explicitly.** Insertion order is link order, which is deterministic only as far as entity
+  creation order is. **Sorted ascending by entity id on insert**, via a binary-search insert — chosen over documenting
+  link order because it makes iteration order independent of the thing that is hard to reason about, and child fan-out
+  is small enough that the splice is not worth defending against.
+- **Hand out a snapshot, not the live array.** `handleParentEntityRemoval` destroys children from inside the cascade,
+  so a consumer iterating a live array mutates under itself. `findChildrenOf` kept its `(result, result_offset, ...)
+  -> count` shape — the `ecd` argument dropped, since the system knows its own dataset — which preserves the house
+  convention from the bvh3 query API. `countChildrenOf` was added beside it, to size a buffer without filling one.
+- **The index does not serialize, and that is the point.** It is rebuilt from `ParentEntity` on load, so there is no
+  format, no version, and no stale-id migration. **This does sharpen D6:** `ParentEntity.serializable === false` means
+  a loaded scene has no `ParentEntity` components to rebuild *from*, so the lifetime hierarchy comes back empty. The
+  index makes that omission visible rather than causing it.
+- **Entity ids are recycled**, so a parent whose last child leaves has its entry deleted outright rather than left
+  empty. An id that comes back has to come back childless; both specs pin it.
+
+**Static-with-`ecd` versus instance.** `traverse` and `findChildrenOf` need the index, so they had to move onto the
+system. `findRoot`, `isAncestorOf` and `findParentEntity` walk child → parent and did not, but leaving them static
+would have meant two ways to ask the same system the same kind of question. All five are instance methods now and the
+`ecd` parameter is gone from all of them. Per library semantics the unreferenced ones were carried across rather than
+deleted.
+
+**Migration cost, measured before and confirmed after:** `ParentEntitySystem.traverse` had **exactly one caller** in
+the whole tree (`sg_hierarchy_compute_bounding_box_via_parent_entity.js:30`), which now takes the system in place of
+the `ecd`. `findChildrenOf`, `findRoot` and `isAncestorOf` had **zero** external callers. So the "you have to reach
+for the system" awkwardness cost one production signature change, plus standing up an `EntityManager` in
+`sg_hierarchy_compute_bounding_box_via_parent_entity.spec.js`, which had been running on a bare ECD.
+
+Payoff: killed D7 and D8, made D3 small enough to fix in the same pass (§6.3), and unblocks `SendUp`/`SendDown`. It did
+**not** let `HierarchicalEntityListView` drop its private `Map<parent, children[]>` — see §4.2 for why that map is not
+this index.
+
+**The same index shape applies to the spatial hierarchy**, and landed there too. `TransformAttachmentSystem` already
+keyed `__contexts` by child; the parent → children direction goes in at `link()` and out at `unlink()`. Inserting at
+`link()` rather than `__finalize_link()` means **a queued child is in the index before it binds** — the question the
+index answers is "which children point at me", and that is true of a child still waiting for its parent to gain a
+`Transform`. The consequence, documented on the system: a non-zero child count does not imply those children are
+composing yet.
+
+### 6.2 Make reparenting a real, single operation
+
+**Not done — still the largest open item.** One function — `hierarchy_reparent(ecd, entity, new_parent)` — that
+updates both components together and is the only supported path. Fix D1 inside it and let `EntityNode.parent` delegate
+to it. This is Scene Graph's `AddEntities` semantics, minus the phase machine. D4's documented immutability means
+reparenting is a remove/re-add of the components, not a field write — which is the contract this function should
+encode rather than leave to callers, and which §6.1 turned from a convention into something the child indices depend
+on.
+
+### 6.3 Detach on parent death — **LANDED 2026-08-24**
+
+`TransformAttachmentSystem` now listens for `EntityRemoved` on the parent (as `ParentEntitySystem`'s `Context` already
+did) and drops the child's `TransformAttachment`. This fixes D3, and makes the independent use of the two relations
+actually safe.
+
+One prediction here did not hold up. The expectation was that the 6.1 index would turn "which children do I unlink"
+into a lookup; in practice the listener is registered **per child context**, exactly as `ParentEntitySystem` does it,
+because a single per-parent listener would have needed its own count of *bound* children to know when to register and
+unregister — the index deliberately includes queued children, which must not register one. Per-child is less state
+and mirrors the sibling system. The index is still what makes the direction answerable at all; this fix just did not
+need to ask. Details, including the stale-dispatch guard, are in D3.
+
+### 6.4 `SendUp` / `SendDown`
+
+Now cheap — 6.1 exists, so `SendDown` is a traversal that already terminates and `SendUp` is
+`ParentEntitySystem.findRoot`'s walk with a visitor. Replaces the manual `findRoot`-and-dispatch idiom. Not built;
+nothing in the tree asks for it yet.
+
+### 6.5 Document the couplings — **DONE 2026-08-24**
+
+`TransformAttachment` needed what `ParentEntity` already had. All three halves are now on the component: the
+`parent`-immutability note (D4), the non-uniform-scale and drift caveat (D10), and the statement that without a
+lifetime relation an attachment does not survive its parent — which, since D3, means the component is removed and the
+entity becomes a world-space root rather than freezing.
+
+Both `parent` fields also now say *why* they must not be mutated in place: each system resolves the parent once at
+link and indexes the edge at the same moment, so an in-place write desynchronises both.
+
+## 7. What is not worth taking
+
+- **`Origin`-defaults-to-parent.** §4.1 — meep's two-field split is better and matches the codebase's stated
+  preference for uniform control flow over sentinels.
+- **A child list as stored, authored state.** §4.2 — take the enumerability, not the component. Scene Graph can afford
+  a stored child list because its hierarchy *is* the entity and there is only one writer; in an ECS the same list
+  becomes a second, user-writable copy of an edge that already exists on the child, with no mechanism keeping the two
+  ends honest. Derive it in the system instead. This is the one place where the conventional engine answer and
+  `ChildEntities` agree with each other and are both wrong.
+- **Tags.** A zero-field component already is a tag, and stays typed.
+- **The five-phase lifecycle, wholesale.** The valuable half is the ordering guarantee that removes the retry queues;
+  adopting five named phases across every system is a much larger change than the problem warrants. If anything here
+  is worth doing it is the *guarantee*, not the vocabulary.
+- **Scoped access.** A Verse language feature with no analogue here.
+
+## 8. The one thing this review would change first
+
+Not any single defect — **`EntityNode`'s status.**
+
+It is documented as sugar and treated as sugar, but it holds the local transform that animation writes to, so it is
+load-bearing runtime state. Every gap in this document traces back to that: reparenting is broken because the fix
+belongs on the components but the API lives on the node; the transform has two homes because the node keeps its own;
+subtree queries scanned because the node had `children` and nothing at the dataset level did.
+
+That last clause is no longer true, which sharpens the question rather than answering it: since §6.1 there **is** a
+child enumeration below the node, owned by the systems. `EntityNode.children` is now a second answer to a question the
+dataset can already answer — a list of nodes, only available to whoever built the tree, next to a list of entity ids
+available to anything holding an entity id.
+
+Decide which one is the hierarchy. If it is the components, `EntityNode` must become genuinely stateless — its
+`transform` accessor forwarding to `attachment.transform`, its `children` reading through `ParentEntitySystem` — and
+animation binds to components. If it is `EntityNode`, then say so, and stop describing it as sugar.
+
+Scene Graph made this choice: the entity is the hierarchy, `transform_component.LocalTransform` is the one local
+transform, and there is no second object graph. That is the part of the design worth copying — not the API surface.
+
+---
+
+## Sources
+
+Unreal / Scene Graph — Epic documentation and reporting:
+
+- [Getting Started in Scene Graph in Fortnite](https://dev.epicgames.com/documentation/fortnite/getting-started-in-scene-graph-in-fortnite)
+- [entity class — Verse API reference](https://dev.epicgames.com/documentation/en-us/fortnite/verse-api/versedotorg/scenegraph/entity)
+- [component class — Verse API reference](https://dev.epicgames.com/documentation/en-us/fortnite/verse-api/versedotorg/scenegraph/component)
+- [Transforms in Scene Graph](https://dev.epicgames.com/documentation/en-us/fortnite/transforms-in-scene-graph-in-unreal-editor-for-fortnite)
+- [Scene Graph Best Practices](https://dev.epicgames.com/documentation/fortnite/scene-graph-best-practices-in-fortnite?lang=en-US)
+- [Scene Graph is Now Available as an Experimental Feature in UEFN](https://www.fortnite.com/news/scene-graph-is-now-available-as-an-experimental-feature-in-uefn)
+- [Unreal Engine 6 Will Combine UEFN and UE Into a "Unified Engine"](https://80.lv/articles/upd-unreal-engine-6-will-combine-uefn-and-ue-into-a-unified-engine)
+- [10 things CG artists need to know about Unreal Engine 6](https://www.cgchannel.com/2026/06/10-things-cg-artists-need-to-know-about-unreal-engine-6/)
+- [Mass Framework overview](https://vrealmatic.com/unreal-engine/mass) — for the Scene Graph ≠ Mass distinction