@forgeax/engine-scene 0.1.23 → 0.1.25

package/dist/instances/scene-instances.d.ts

@@ -250,7 +250,7 @@ export declare function worldValidateMountOverrides(world: World, mount: SceneIn
  * chain `cube -> innerSyntheticRoot -> mountEntity -> outerSyntheticRoot`,
  * so it MUST carry Transform whenever Transform is registered (mirrors
  * the D-V-0 synthetic-root invariant). Otherwise propagateTransforms
- * walking the chain hits a Transform-less parent and emits per-frame
+ * expanding the chain hits a Transform-less parent and emits per-frame
  * `RhiError(hierarchy-broken)` (verify R1 root cause of the
  * hello-scene-nesting demo black frames).
  */

package/dist/systems/propagate-transforms.d.ts

@@ -5,6 +5,27 @@ export declare const PROPAGATE_TRANSFORMS_SYSTEM: "propagateTransforms";
 export declare const PROPAGATE_TRANSFORMS_FIXED_SYSTEM: "propagateTransformsFixed";
 export declare const TransformSet: import("@forgeax/engine-ecs").SystemSet;
 export declare const TransformFixedSet: import("@forgeax/engine-ecs").SystemSet;
+/**
+ * Optional, test-owned counters for the parent-first executor. The counters
+ * are disabled unless a caller brackets a run with begin/end; production
+ * propagation therefore pays only one predictable branch per instrumented
+ * event. They are deliberately not a second execution state or a public
+ * dirty/cache contract.
+ */
+export interface TransformPropagationTrace {
+    hierarchyRootInvocations: number;
+    hierarchyRootCursorReuses: number;
+    hierarchyRootCursorAllocations: number;
+    hierarchyEntityLookups: number;
+    hierarchyRowsEvaluated: number;
+    hierarchyEdgesVisited: number;
+    hierarchyPublishedRows: number;
+    hierarchyPublishedRuns: number;
+    hierarchyResidualParentProbes: number;
+    flatStructuralRootRows: number;
+}
+export declare function beginTransformPropagationTrace(): void;
+export declare function endTransformPropagationTrace(): TransformPropagationTrace;
 export declare function propagateTransforms(world: World): Result<void, SceneError>;
 export declare const PropagateTransforms: SystemHandle<readonly []>;
 export declare const PropagateTransformsFixed: SystemHandle<readonly []>;

package/dist/systems/propagate-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"propagate-transforms.d.ts","sourceRoot":"","sources":["../../src/systems/propagate-transforms.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,YAAY,EAEjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,eAAO,MAAM,2BAA2B,EAAG,qBAA8B,CAAC;AAC1E,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AACrF,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,iBAAiB,yCAA+C,CAAC;AA6Z9E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAO1E;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,SAAS,EAAE,CAOxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,SAAS,EAAE,CAI7D,CAAC;AAEH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,IAAI,CA8CZ"}
+{"version":3,"file":"propagate-transforms.d.ts","sourceRoot":"","sources":["../../src/systems/propagate-transforms.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,YAAY,EAEjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAS7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,eAAO,MAAM,2BAA2B,EAAG,qBAA8B,CAAC;AAC1E,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AACrF,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,iBAAiB,yCAA+C,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;IAClC,8BAA8B,EAAE,MAAM,CAAC;IACvC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,6BAA6B,EAAE,MAAM,CAAC;IACtC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAWD,wBAAgB,8BAA8B,IAAI,IAAI,CAcrD;AAED,wBAAgB,4BAA4B,IAAI,yBAAyB,CAsBxE;AAklCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAO1E;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,SAAS,EAAE,CAOxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,SAAS,EAAE,CAI7D,CAAC;AAEH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,IAAI,CA8CZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-scene",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,10 +22,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.23",
-    "@forgeax/engine-math": "0.1.23",
-    "@forgeax/engine-plugin": "0.1.23",
-    "@forgeax/engine-types": "0.1.23"
+    "@forgeax/engine-ecs": "0.1.25",
+    "@forgeax/engine-math": "0.1.25",
+    "@forgeax/engine-plugin": "0.1.25",
+    "@forgeax/engine-types": "0.1.25"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/fixtures/malformed-hierarchy-edge.ts

@@ -1,15 +1,37 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { componentId } from '../../../../ecs/src/component';
+import { entityIndex } from '../../../../ecs/src/entity-handle';
+import { worldInternal } from '../../../../ecs/src/world-internal';
 import { ChildOf } from '../../index';
 
 /**
- * Scene-owned malformed-edge fixture. The public relationship write accepts
- * stale handles as data; the projection then owns the liveness diagnostic.
- * Keeping this fixture on `world.set` avoids a private ECS graph seam.
+ * Scene-owned malformed-edge fixture. Production relationship writes reject
+ * stale targets and cycles before touching either side of the relationship.
+ * This test-only fixture deliberately corrupts the source column through the
+ * existing package-internal graph seam so projection can exercise its
+ * fail-closed diagnostics without weakening the public write contract.
  */
 export function setMalformedParentEdge(
   world: World,
   child: EntityHandle,
   parent: EntityHandle,
 ): void {
-  world.set(child, ChildOf, { parent }).unwrap();
+  const record = world[worldInternal].getRecords()[entityIndex(child)];
+  if (record === undefined || record.archetypeId < 0) {
+    throw new Error(`Malformed hierarchy fixture child ${child} is not live.`);
+  }
+  const graph = world[worldInternal].getGraph();
+  const archetype = graph.archetypes[record.archetypeId];
+  if (archetype === undefined) throw new Error(`Missing archetype ${record.archetypeId}.`);
+  const table = graph.tables[archetype.tableId];
+  const column = table?.storage.get(componentId(ChildOf))?.fields.get('parent');
+  const tableRow = archetype.rows[record.archetypeRow];
+  if (column === undefined || tableRow === undefined) {
+    throw new Error(`Malformed hierarchy fixture child ${child} lacks ChildOf storage.`);
+  }
+  column.view[tableRow] = parent as number;
+  // Keep the corruption internal, but make the source mutation observable to
+  // the normal change-token consumers so an already-built projection cannot
+  // mask the deliberately malformed value.
+  world[worldInternal].markComponentChanged(child, componentId(ChildOf));
 }

package/src/__tests__/hierarchy-propagation.perf.test.ts

@@ -0,0 +1,149 @@
+// Resource-safe hierarchy performance evidence: the largest default case is
+// 10k fully dynamic nodes. Cross-commit AB/BA timing remains an external
+// runner concern; this gate records deterministic owner counters and exact
+// matrices without claiming a speedup from one local process.
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, GlobalTransform, Transform } from '../index';
+import {
+  beginTransformPropagationTrace,
+  endTransformPropagationTrace,
+  propagateTransforms,
+  type TransformPropagationTrace,
+} from '../systems/propagate-transforms';
+
+type HierarchyShape = 'wide' | 'balanced';
+
+interface Workload {
+  readonly shape: HierarchyShape;
+  readonly rows: number;
+}
+
+interface Receipt {
+  readonly shape: HierarchyShape;
+  readonly rows: number;
+  readonly fullyDynamicRows: number;
+  readonly propagationMs: number;
+  readonly trace: TransformPropagationTrace;
+}
+
+const BRANCHING_FACTOR = 4;
+const WARMUP_FRAMES = 2;
+const WORKLOADS: readonly Workload[] = [
+  { shape: 'wide', rows: 1_000 },
+  { shape: 'wide', rows: 4_000 },
+  { shape: 'wide', rows: 10_000 },
+  { shape: 'balanced', rows: 1_000 },
+  { shape: 'balanced', rows: 4_000 },
+  { shape: 'balanced', rows: 10_000 },
+];
+
+function parentIndex(shape: HierarchyShape, row: number): number {
+  if (row === 0) return -1;
+  return shape === 'wide' ? 0 : Math.floor((row - 1) / BRANCHING_FACTOR);
+}
+
+function spawnNode(world: World, parent: EntityHandle | undefined, localX: number): EntityHandle {
+  const transform = { component: Transform, data: { pos: [localX, 0, 0] } } as const;
+  if (parent === undefined) return world.spawn(transform).unwrap();
+  return world.spawn(transform, { component: ChildOf, data: { parent } }).unwrap();
+}
+
+function setDynamicLocals(
+  world: World,
+  entities: readonly EntityHandle[],
+  parents: Int32Array,
+  expectedWorldX: Float64Array,
+  frame: number,
+): void {
+  for (let row = 0; row < entities.length; row += 1) {
+    const value = ((row * 17 + frame * 31) % 97) + 1;
+    const entity = entities[row];
+    if (entity === undefined) throw new Error(`missing hierarchy entity ${row}`);
+    world.set(entity, Transform, { pos: [value, 0, 0] }).unwrap();
+    const parent = parents[row] ?? -1;
+    expectedWorldX[row] = parent < 0 ? value : (expectedWorldX[parent] ?? 0) + value;
+  }
+}
+
+function assertExactTranslationMatrices(
+  world: World,
+  entities: readonly EntityHandle[],
+  expectedWorldX: Float64Array,
+): void {
+  const expectedIdentity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  for (let row = 0; row < entities.length; row += 1) {
+    const entity = entities[row];
+    if (entity === undefined) throw new Error(`missing hierarchy entity ${row}`);
+    const matrix = world.get(entity, GlobalTransform).unwrap().world;
+    const expectedX = expectedWorldX[row] ?? 0;
+    for (let index = 0; index < 16; index += 1) {
+      const expected = index === 12 ? expectedX : (expectedIdentity[index] ?? 0);
+      expect(matrix[index], `matrix[${row}][${index}]`).toBe(expected);
+    }
+  }
+}
+
+function runWorkload(workload: Workload): Receipt {
+  const world = new World();
+  const entities: EntityHandle[] = [];
+  const parents = new Int32Array(workload.rows);
+  for (let row = 0; row < workload.rows; row += 1) {
+    const parent = parentIndex(workload.shape, row);
+    parents[row] = parent;
+    const parentEntity = parent < 0 ? undefined : entities[parent];
+    entities.push(spawnNode(world, parentEntity, row + 1));
+  }
+
+  const expectedWorldX = new Float64Array(workload.rows);
+  for (let frame = 0; frame < WARMUP_FRAMES; frame += 1) {
+    setDynamicLocals(world, entities, parents, expectedWorldX, frame);
+    propagateTransforms(world).unwrap();
+  }
+
+  setDynamicLocals(world, entities, parents, expectedWorldX, WARMUP_FRAMES);
+  const start = performance.now();
+  beginTransformPropagationTrace();
+  const result = propagateTransforms(world);
+  const propagationMs = Number((performance.now() - start).toFixed(3));
+  const trace = endTransformPropagationTrace();
+  expect(result.ok).toBe(true);
+  assertExactTranslationMatrices(world, entities, expectedWorldX);
+
+  const hierarchyRows = workload.rows - 1;
+  expect(trace.hierarchyRowsEvaluated).toBe(hierarchyRows);
+  expect(trace.hierarchyEdgesVisited).toBe(hierarchyRows);
+  expect(trace.hierarchyEntityLookups).toBeGreaterThan(0);
+  expect(trace.hierarchyEntityLookups).toBeLessThanOrEqual(workload.rows * 8);
+  expect(trace.hierarchyPublishedRows).toBe(hierarchyRows);
+  expect(trace.hierarchyPublishedRuns).toBeGreaterThan(0);
+  expect(trace.hierarchyPublishedRuns).toBeLessThanOrEqual(2);
+  expect(trace.hierarchyRootCursorAllocations).toBe(0);
+  expect(trace.hierarchyResidualParentProbes).toBe(0);
+
+  return {
+    shape: workload.shape,
+    rows: workload.rows,
+    fullyDynamicRows: workload.rows,
+    propagationMs,
+    trace,
+  };
+}
+
+describe('dynamic hierarchy propagation counters', () => {
+  for (const workload of WORKLOADS) {
+    it(`keeps ${workload.shape} ${workload.rows} fully dynamic rows linear`, () => {
+      const receipt = runWorkload(workload);
+      // biome-ignore lint/suspicious/noConsole: deterministic performance receipt.
+      console.info(JSON.stringify({ schemaVersion: 1, workload: receipt }));
+
+      expect(receipt.fullyDynamicRows).toBe(receipt.rows);
+      expect(receipt.trace.hierarchyRowsEvaluated).toBe(receipt.rows - 1);
+      expect(receipt.trace.hierarchyEdgesVisited).toBe(receipt.rows - 1);
+      expect(receipt.trace.hierarchyEntityLookups).toBeLessThanOrEqual(receipt.rows * 8);
+      expect(receipt.trace.hierarchyPublishedRows).toBe(receipt.rows - 1);
+      expect(receipt.trace.hierarchyPublishedRuns).toBeLessThanOrEqual(2);
+      expect(receipt.trace.hierarchyRootCursorAllocations).toBe(0);
+    }, 120_000);
+  }
+});

package/src/__tests__/propagation.unit.test.ts

@@ -4,6 +4,11 @@ import { ChangeEpochExhaustedError } from '../../../ecs/src/errors';
 import { worldInternal } from '../../../ecs/src/world-internal';
 import { ChildOf, GlobalTransform, propagateTransforms, Transform } from '../index';
 import { registerPropagateTransforms } from '../systems';
+import {
+  beginTransformPropagationTrace,
+  endTransformPropagationTrace,
+} from '../systems/propagate-transforms';
+import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
 
 function spawnTransform(world: World, pos: number[], parent?: EntityHandle) {
   const components = [{ component: Transform, data: { pos } }];
@@ -193,6 +198,39 @@ describe('scene propagation', () => {
     expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(101);
   });
 
+  it('recomputes a detached ChildOf entity as a flat root even when local data is unchanged', () => {
+    const world = new World();
+    const parent = spawnTransform(world, [10, 0, 0]);
+    const child = spawnTransform(world, [1, 0, 0], parent);
+    propagateTransforms(world).unwrap();
+
+    world.removeComponent(child, ChildOf).unwrap();
+    const result = propagateTransforms(world);
+
+    expect(result.ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(1);
+  });
+
+  it('reuses one hierarchy root cursor and reports linear traversal counters', () => {
+    const world = new World();
+    for (let index = 0; index < 32; index += 1) {
+      const root = spawnTransform(world, [index, 0, 0]);
+      spawnTransform(world, [1, 0, 0], root);
+    }
+    propagateTransforms(world).unwrap();
+
+    beginTransformPropagationTrace();
+    propagateTransforms(world).unwrap();
+    const trace = endTransformPropagationTrace();
+
+    expect(trace.hierarchyRootInvocations).toBeGreaterThan(0);
+    expect(trace.hierarchyRootCursorReuses).toBe(trace.hierarchyRootInvocations);
+    expect(trace.hierarchyRootCursorAllocations).toBe(0);
+    expect(trace.hierarchyRowsEvaluated).toBeGreaterThanOrEqual(32);
+    expect(trace.hierarchyEdgesVisited).toBeGreaterThanOrEqual(32);
+    expect(trace.hierarchyResidualParentProbes).toBe(0);
+  });
+
   it('publishes a local fallback before returning a stale-parent error', () => {
     const world = new World();
     const parent = spawnTransform(world, [10, 0, 0]);
@@ -202,7 +240,10 @@ describe('scene propagation', () => {
 
     const staleParent = spawnTransform(world, [50, 0, 0]);
     world.despawn(staleParent).unwrap();
-    world.set(child, ChildOf, { parent: staleParent }).unwrap();
+    // Public relationship writes reject stale targets before changing either
+    // side. Corrupt the source only through the test-owned internal fixture
+    // to exercise propagation's explicit malformed-input fallback.
+    setMalformedParentEdge(world, child, staleParent);
     const fault = propagateTransforms(world);
 
     expect(fault.ok).toBe(false);
@@ -210,10 +251,6 @@ describe('scene propagation', () => {
     const fallback = world.get(child, GlobalTransform).unwrap().world;
     expect(fallback[12]).toBeCloseTo(1);
     expect(fallback[12]).not.toBeCloseTo(baseline[12] ?? Number.NaN);
-
-    world.set(child, ChildOf, { parent }).unwrap();
-    expect(propagateTransforms(world).ok).toBe(true);
-    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(baseline[12] ?? 0);
   });
 
   it('cuts every member of a cycle to a finite local root fallback', () => {
@@ -221,7 +258,7 @@ describe('scene propagation', () => {
     const root = spawnTransform(world, [0, 0, 0]);
     const first = spawnTransform(world, [1, 0, 0], root);
     const second = spawnTransform(world, [2, 0, 0], first);
-    world.set(first, ChildOf, { parent: second }).unwrap();
+    setMalformedParentEdge(world, first, second);
 
     const result = propagateTransforms(world);
 
@@ -233,6 +270,33 @@ describe('scene propagation', () => {
     }
   });
 
+  it('bounds rootless-cycle parent probes to one residual pass', () => {
+    const world = new World();
+    const root = spawnTransform(world, [0, 0, 0]);
+    const nodes: EntityHandle[] = [];
+    let parent = root;
+    for (let index = 0; index < 48; index += 1) {
+      const node = spawnTransform(world, [1, 0, 0], parent);
+      nodes.push(node);
+      parent = node;
+    }
+    propagateTransforms(world).unwrap();
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    if (first === undefined || last === undefined) throw new Error('expected cycle nodes');
+    setMalformedParentEdge(world, first, last);
+
+    beginTransformPropagationTrace();
+    const result = propagateTransforms(world);
+    const trace = endTransformPropagationTrace();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('hierarchy-cycle');
+    expect(trace.hierarchyResidualParentProbes).toBeGreaterThan(0);
+    expect(trace.hierarchyResidualParentProbes).toBeLessThanOrEqual(nodes.length + 1);
+    expect(trace.hierarchyEdgesVisited).toBeLessThanOrEqual(nodes.length + 1);
+  });
+
   it('expands a generic ChildOf mutation and updates descendants', () => {
     const world = new World();
     const firstParent = spawnTransform(world, [10, 0, 0]);

package/src/components/child-of.ts

@@ -7,6 +7,8 @@
 // u32 against the live record on read; `world.get(child, ChildOf)` returns
 // the raw encoded Entity and consumers check liveness themselves (via
 // `world.get(parent, Entity)` — returns `err(stale-entity)` for despawned handles).
+// Public source writes validate target liveness before committing; only
+// controlled internal fixtures can create a stale source for diagnostics.
 //
 // feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
 // ChildOf is declared as the holder side of a Bevy-style bidirectional
@@ -30,30 +32,30 @@
 //     the D-1 default from false to true). When linkedSpawn is set to true,
 //     world.despawn(parent) recursively despawns the entire subtree.
 //
-//     The prior default (linkedSpawn: false) meant despawning the parent only
-//     pruned the Children entry, leaving the child entity alive. That behavior
-//     is still available by passing linkedSpawn: false explicitly.
+//     `ChildOf` uses linkedSpawn: true, so despawning a parent recursively
+//     despawns its linked subtree. A generic relationship may opt out with
+//     linkedSpawn: false, but that is not this scene hierarchy's lifecycle.
 //
-// Child despawn auto-detaches from the parent's Children list: the
+// Child despawn auto-detaches from its parent's Children list: the
 // relationship `onRemove` hook fires on `world.despawn(child)` and prunes the
 // child from the parent's `Children.entities` (a write-path hook). Despawning
-// the PARENT does not auto-clean the child's ChildOf: the child's `parent`
-// column keeps the stale encoded Entity. The ECS does not bottom out dangling
-// references on read; the consumer is responsible for cleanup
-// (`world.removeComponent(child, ChildOf)` / `world.get(parent, Entity)` liveness check).
+// the parent follows ChildOf's linkedSpawn cascade and retires the linked
+// subtree. A stale ChildOf source is consequently only an explicitly malformed
+// internal fixture (or a generic non-linked relationship); the consumer repairs
+// it with `world.removeComponent(child, ChildOf)` after the structured error.
 //
-// propagateTransforms system (./systems/propagate-transforms.ts) consumes
-// this component by reading the archetype Uint32Array column directly
-// (query-backed hierarchy access). When a parent has been despawned
+// propagateTransforms system (./systems/propagate-transforms.ts) consumes the
+// ECS-maintained Children buffer for parent-first traversal and reads this
+// source column only to validate the mirrored edge. When a parent has been despawned
 // but the child's stale ChildOf is left in place, the live-map lookup surfaces
-// `RhiError({ code: 'hierarchy-broken' })` - a deliberate per-frame fail-fast
+// `SceneError({ code: 'hierarchy-broken' })` - a deliberate per-frame fail-fast
 // (the consumer is expected to despawn the subtree or remove the stale
 // ChildOf), kept as the explicit-failure surface (charter proposition 4).
 //
 // charter mapping: proposition 2 (industry analogy: Bevy ChildOf is the
 // post-0.15 rename of Parent for the same shape as glTF node parent index
 // + Three.js Object3D.parent) + proposition 4 (explicit failure: dangling
-// parent surfaces structured RhiError) + proposition 5
+// parent surfaces structured SceneError) + proposition 5
 // (consistent abstraction: the schema-vocab 'entity' keyword is the SSOT
 // for entity-typed columns across the engine).
 
@@ -63,15 +65,16 @@ export { ChildOf } from './children';
  * Hierarchy back-reference: pointer from child entity to its parent.
  *
  * Store the parent `Entity` handle (returned by `world.spawn(...).unwrap()`)
- * in the `parent` field; `propagateTransforms` reads it each frame to
- * compose the child's derived `GlobalTransform.world` mat4 (child.world =
- * parent.world x child local). `Transform` declares `GlobalTransform` as a
+ * in the `parent` field; `propagateTransforms` follows the ECS-maintained
+ * `Children` list each frame to compose the child's derived
+ * `GlobalTransform.world` mat4 (child.world = parent.world x child local).
+ * `Transform` declares `GlobalTransform` as a
  * generic ECS requirement, so normal spawn/add/command paths materialize the
  * pair without scene-specific repair. Propagation still fails closed when an
- * owner explicitly removes one half. Despawning a child auto-detaches it from the
- * parent's Children list (relationship `onRemove` hook). Despawning the
- * parent does not auto-clean the child's ChildOf; the consumer removes the
- * stale ChildOf (`world.removeComponent`) or checks `world.get(parent, Entity)` for liveness.
+ * owner explicitly removes one half. Despawning a child auto-detaches it from
+ * its parent's Children list; despawning the parent follows ChildOf's
+ * linkedSpawn cascade, while a malformed internal fixture can still leave a
+ * stale source for Scene diagnostics.
  *
  * Because ChildOf declares a `relationship` mirror and a structural
  * `Transform` requirement, the engine keeps the parent's `Children.entities`
@@ -82,8 +85,9 @@ export { ChildOf } from './children';
  * prior OOS-10 contract is retired).
  * Reparenting is a plain re-add: `world.addComponent(child, { component:
  * ChildOf, data: { parent: newParent } })` on an entity that already carries
- * ChildOf auto-reparents (exclusive arm), or use `world.reparent(child,
- * newParent)`.
+ * ChildOf auto-reparents (exclusive arm). The generic convenience method has
+ * the same owner path and requires the relationship component plus its data:
+ * `world.reparent(child, newParent, ChildOf, { parent: newParent })`.
  *
  * @example Spawn a child entity referencing an already-spawned root:
  *   const root = world.spawn(

package/src/components/children.ts

@@ -1,28 +1,23 @@
 // @forgeax/engine-runtime - Children (forward-list of child entities).
 //
 // Schema: 1 array<entity> field `entities` (variable-length, ECS-managed via
-// the BufferPool slot column + sidecar count column allocated by the ECS M2
-// `world.push` / `world.pop` / `world.capacity` command surface).
+// the BufferPool slot column + sidecar count column allocated by the ECS
+// relationship owner).
 //
 // feat-20260515-buffer-array-vocab-collapse M3 / w17:
 // the legacy `VarArrayView<Entity>` value-shape wrapper was retired in
-// favour of a direct `TypedArray` snapshot returned by `world.get` plus the
-// three `world` commands. AI users mutate the list through:
-//
-//   world.push(parent, Children, 'entities', child).unwrap();
-//   world.pop(parent, Children, 'entities').unwrap();
-//   world.capacity(parent, Children, 'entities').unwrap();
-//
-// And read through the read-only `Uint32Array` snapshot:
+// favour of a direct `TypedArray` snapshot returned by `world.get`. AI users
+// read the engine-maintained list through the read-only `Uint32Array` snapshot:
 //
 //   const snap = world.get(parent, Children).unwrap().entities;
 //   const liveCount = snap.length;
 //   for (let i = 0; i < liveCount; i++) { const child = snap[i]; ... }
 //
 // Snapshot length equals the live element count (sidecar count column owned
-// by the ECS layer); the snapshot is rematerialised on every `world.get`
-// (D-4 no-cache); writes routed through the snapshot are undefined behaviour
-// (the contract is read-only, plan-strategy §2.2 D-R3).
+// by the ECS layer); the public snapshot is detached and rematerialised on
+// every `world.get` (D-4 no-cache), so `fill` or index writes cannot mutate the
+// target. Internal relationship maintenance and Scene traversal borrow the
+// live array through the package-internal zero-copy seams instead.
 //
 // feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
 // Children is the MIRROR side of the ChildOf relationship. Its schema is
@@ -33,9 +28,8 @@
 // "AI users keep the two sides consistent themselves" contract is retired:
 // `world.addComponent(child, ChildOf{parent})` appends `child` to
 // `parent.Children.entities`, `world.removeComponent` / reparent prunes it.
-// AI users still MAY push/pop the list manually (the three `world` commands
-// below remain valid for non-ChildOf forward-lists), but for the ChildOf
-// hierarchy the engine owns consistency.
+// For the ChildOf hierarchy the engine owns consistency; no public target
+// write can diverge from the source relationship.
 //
 // feat-20260514-ecs-children-instances-managed-buffer-array M3 / w13 (kept
 // for context): migrated from the legacy `{ count: 'u32' }` advisory marker
@@ -43,14 +37,12 @@
 //   - OOS-09 (prior loop): no `addChild` / `removeChild` / `removeChildren`
 //     Commands API. Retired this feat: `world.addChild` / `world.removeChild`
 //     / `world.reparent` ship in M3, plus the relationship hook above.
-//   - OOS-01 (prior loop): no dangling-entity sweep on `array<entity>`. If a
-//     child entity has been despawned, the stored u32 still occupies the
-//     slot; AI users explicitly call the engine's entity-liveness check
-//     before consuming a child id (see `world.get(child, ChildOf)` returns
-//     `Result.err(...)` for a despawned entity --- the stored u32 surfaces
-//     as a dead handle, not a silent zero). Charter proposition 4
-//     (explicit failure): the engine does not silently drop dangling
-//     entries.
+//   - Normal ChildOf child despawn invokes the source onRemove hook and
+//     removes the child before the row is retired; parent despawn follows the
+//     linkedSpawn cascade. A dangling u32 is therefore an explicitly malformed
+//     internal fixture or a non-linked generic relationship, not a normal
+//     ChildOf lifecycle result. Consumers still probe liveness before using a
+//     handle and receive the structured ECS error for malformed state.
 //
 // charter mapping: proposition 2 (Bevy ChildOf+Children pair, holder
 // perspective) + proposition 3 (machine-readable schema:
@@ -66,25 +58,26 @@ import { Transform } from './transform';
  * Hierarchy forward-list of child entities.
  *
  * `entities` is a variable-length `array<entity>` field; each element is
- * an `Entity` u32 the AI user pushed via
- * `world.push(parent, Children, 'entities', child)`. The value returned by
- * `world.get(parent, Children).unwrap().entities` is a read-only
+ * an `Entity` u32 the ECS relationship owner materialized. The value returned
+ * by `world.get(parent, Children).unwrap().entities` is a detached read-only
  * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
- * the snapshot's `length` equals the live element count.
+ * mutating the returned array cannot change ECS-owned storage, and the
+ * snapshot's `length` equals the live element count. Internal Scene/ECS paths
+ * use the package-internal zero-copy array seams instead of this snapshot.
  *
  * Invariants:
- *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
- *     upward, D-P2). The forward list is for AI-user traversal / debug /
- *     inspection.
+ *   - `propagateTransforms` consumes Children from the ECS-owned materialized
+ *     buffer and expands each root parent-first. The forward list is also
+ *     available for AI-user traversal / debug / inspection.
  *   - Children <-> ChildOf consistency is maintained by the engine via the
  *     ChildOf `relationship` mirror hook (see ./child-of.ts): adding /
  *     removing / reparenting ChildOf on a child auto-updates the parent's
  *     `entities` list. AI users do not hand-sync the two sides for the
  *     hierarchy.
- *   - Stored entity u32s are NOT auto-cleared when the referenced entity is
- *     despawned (OOS-01 above); a `world.get(despawnedChild, ...)` call
- *     returns `Result.err(...)` so AI users discover the dangling state
- *     through the engine's structured-error channel.
+ *   - ChildOf's linked lifecycle keeps ordinary Children entries aligned: a
+ *     child despawn prunes its source slot and a parent despawn cascades. A
+ *     deliberately malformed/non-linked edge remains observable as a dead
+ *     handle and must be diagnosed through the structured error channel.
  *
  * @example Spawn a parent and two children via ChildOf (engine maintains Children):
  *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
@@ -100,8 +93,8 @@ import { Transform } from './transform';
  *   const snap = world.get(parent, Children).unwrap().entities;
  *   for (let i = 0; i < snap.length; i++) {
  *     const child = snap[i];
- *     // ... consume; world.get(child, ...) surfaces a structured error
- *     // if the child has been despawned (OOS-01 dangling-entity surface).
+ *     // ... consume; probe the handle before using it when reading a
+ *     // deliberately malformed/non-linked relationship.
  *   }
  */
 export const { source: ChildOf, target: Children } = defineRelationship({

package/src/instances/scene-instances.ts

@@ -646,8 +646,8 @@ export function worldInstantiateSceneAsset(
   const mappingPlain: number[] = Array.from(mapping);
   // The synthetic root is the ChildOf parent of every owned root entity
   // (step 5 below) and may itself become a ChildOf parent of a caller-
-  // supplied `parent` chain. propagateTransforms walks ChildOf parents
-  // through the Transform liveMap and treats a parent missing Transform
+  // supplied `parent` chain. propagateTransforms expands the ECS-maintained
+  // Children lists parent-first and treats a parent missing Transform
   // as `hierarchy-broken`, so the synthetic root must carry Transform
   // (identity TRS via layer-2 defaults) when Transform is defined.
   const rootComponents: ComponentData[] = [
@@ -1048,7 +1048,7 @@ export function worldValidateMountOverrides(
  * chain `cube -> innerSyntheticRoot -> mountEntity -> outerSyntheticRoot`,
  * so it MUST carry Transform whenever Transform is registered (mirrors
  * the D-V-0 synthetic-root invariant). Otherwise propagateTransforms
- * walking the chain hits a Transform-less parent and emits per-frame
+ * expanding the chain hits a Transform-less parent and emits per-frame
  * `RhiError(hierarchy-broken)` (verify R1 root cause of the
  * hello-scene-nesting demo black frames).
  */
@@ -1064,7 +1064,7 @@ export function worldSpawnMountEntity(
   };
   const cdRes = worldBuildSceneEntityComponentDatas(world, fakeNode, mapping, diagnostics);
   if (!cdRes.ok) return cdRes;
-  // R2/B-1: ensure Transform is attached so propagateTransforms can walk
+  // R2/B-1: ensure Transform is attached so propagateTransforms can expand
   // through this entity. Layer-2 defaults supply identity TRS; the
   // mount.components overlay (when present and including Transform) takes
   // precedence and is already in cdRes.value.