@forgeax/engine-scene 0.1.23 → 0.1.25

package/src/systems/propagate-transforms.ts

@@ -2,6 +2,7 @@ import {
   defineSystem,
   defineSystemSet,
   type EcsError,
+  ENTITY_NULL_RAW,
   type EntityHandle,
   FixedUpdate,
   type Query,
@@ -9,9 +10,17 @@ import {
   Update,
   type World,
 } from '@forgeax/engine-ecs';
+import {
+  type DerivedColumnBinding,
+  type DerivedRangeCursor,
+  type DerivedRangeWriter,
+  getDerivedWriter,
+  worldInternal,
+} from '@forgeax/engine-ecs/internal';
 import { type Mat4, mat4 } from '@forgeax/engine-math';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { ChildOf } from '../components/child-of';
+import { Children } from '../components/children';
 import { GlobalTransform, Transform } from '../components/transform';
 import { SceneError } from '../errors';
 
@@ -20,22 +29,129 @@ export const PROPAGATE_TRANSFORMS_FIXED_SYSTEM = 'propagateTransformsFixed' as c
 export const TransformSet = defineSystemSet({ name: 'transform' });
 export const TransformFixedSet = defineSystemSet({ name: 'transform-fixed' });
 
+/**
+ * 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;
+}
+
+let propagationTrace: TransformPropagationTrace | undefined;
+let hierarchyRootCursorAllocationCount = 0;
+let propagationTraceRootCursorAllocationStart = 0;
+
+function createHierarchyRootCursor(): DerivedRangeCursor {
+  hierarchyRootCursorAllocationCount += 1;
+  return { bindingIndex: -1, row: -1 };
+}
+
+export function beginTransformPropagationTrace(): void {
+  propagationTraceRootCursorAllocationStart = hierarchyRootCursorAllocationCount;
+  propagationTrace = {
+    hierarchyRootInvocations: 0,
+    hierarchyRootCursorReuses: 0,
+    hierarchyRootCursorAllocations: 0,
+    hierarchyEntityLookups: 0,
+    hierarchyRowsEvaluated: 0,
+    hierarchyEdgesVisited: 0,
+    hierarchyPublishedRows: 0,
+    hierarchyPublishedRuns: 0,
+    hierarchyResidualParentProbes: 0,
+    flatStructuralRootRows: 0,
+  };
+}
+
+export function endTransformPropagationTrace(): TransformPropagationTrace {
+  const trace = propagationTrace;
+  propagationTrace = undefined;
+  const rootCursorAllocations =
+    hierarchyRootCursorAllocationCount - propagationTraceRootCursorAllocationStart;
+  propagationTraceRootCursorAllocationStart = hierarchyRootCursorAllocationCount;
+  if (trace !== undefined) {
+    trace.hierarchyRootCursorAllocations = rootCursorAllocations;
+    return trace;
+  }
+  return {
+    hierarchyRootInvocations: 0,
+    hierarchyRootCursorReuses: 0,
+    hierarchyRootCursorAllocations: 0,
+    hierarchyEntityLookups: 0,
+    hierarchyRowsEvaluated: 0,
+    hierarchyEdgesVisited: 0,
+    hierarchyPublishedRows: 0,
+    hierarchyPublishedRuns: 0,
+    hierarchyResidualParentProbes: 0,
+    flatStructuralRootRows: 0,
+  };
+}
+
+function countPropagation(name: keyof TransformPropagationTrace): void {
+  const trace = propagationTrace;
+  if (trace !== undefined) trace[name] += 1;
+}
+
 interface Scratch {
   position: Float32Array;
   rotation: Float32Array;
   scale: Float32Array;
   local: Mat4;
-  hierarchyPath: number[];
+  parent: Mat4;
+  candidate: Mat4;
+  hierarchyStackEntities: EntityHandle[];
+  hierarchyStackChildren: number[];
+  hierarchyProbeEntities: EntityHandle[];
+  hierarchyCurrentCursor: DerivedRangeCursor;
+  hierarchyParentCursor: DerivedRangeCursor;
+  hierarchyChildCursor: DerivedRangeCursor;
+  hierarchyResidualCursor: DerivedRangeCursor;
+  hierarchyResidualParentCursor: DerivedRangeCursor;
+  hierarchyRootCursor: DerivedRangeCursor;
+  hierarchyStates: Uint8Array[];
+  hierarchyChanged: Uint8Array[];
+  hierarchyBindingTables: number[];
+  hierarchyBindingRows: number[];
+  flatChanged: Uint8Array[];
+  flatBindingTables: number[];
+  flatBindingRows: number[];
+  flatStructureEpoch: number;
   flatQuery?: FlatQuery;
-  outputQuery?: OutputQuery;
   hierarchyQuery?: HierarchyQuery;
+  transformQuery?: TransformQuery;
+  hierarchyWriter?: HierarchyWriter;
+  transformWriter?: TransformWriter;
   missingGlobalQuery?: MissingGlobalQuery;
   missingTransformQuery?: MissingTransformQuery;
 }
 
-type OutputQuery = Query<readonly [], readonly [typeof GlobalTransform]>;
 type FlatQuery = Query<readonly [typeof Transform], readonly [typeof GlobalTransform]>;
-type HierarchyQuery = Query<readonly [typeof Transform, typeof ChildOf]>;
+type HierarchyQuery = Query<
+  readonly [typeof Transform, typeof ChildOf],
+  readonly [typeof GlobalTransform]
+>;
+type TransformQuery = Query<readonly [typeof Transform], readonly [typeof GlobalTransform]>;
+type HierarchyWriter = DerivedRangeWriter<
+  typeof Transform | typeof ChildOf,
+  typeof GlobalTransform
+>;
+type TransformWriter = DerivedRangeWriter<typeof Transform, typeof GlobalTransform>;
+type HierarchyBinding = DerivedColumnBinding<
+  typeof Transform | typeof ChildOf,
+  typeof GlobalTransform
+>;
+type TransformBinding = DerivedColumnBinding<typeof Transform, typeof GlobalTransform>;
 type MissingGlobalQuery = Query<readonly [], readonly [], readonly []>;
 type MissingTransformQuery = Query<readonly [], readonly [], readonly []>;
 
@@ -60,8 +176,10 @@ function pairError(entity: EntityHandle, expected: string): Result<void, SceneEr
 function ensureQueries(world: World, scratch: Scratch): Result<void, SceneError> {
   if (
     scratch.flatQuery !== undefined &&
-    scratch.outputQuery !== undefined &&
     scratch.hierarchyQuery !== undefined &&
+    scratch.transformQuery !== undefined &&
+    scratch.hierarchyWriter !== undefined &&
+    scratch.transformWriter !== undefined &&
     scratch.missingGlobalQuery !== undefined &&
     scratch.missingTransformQuery !== undefined
   ) {
@@ -73,16 +191,29 @@ function ensureQueries(world: World, scratch: Scratch): Result<void, SceneError>
     without: [ChildOf],
     changed: [Transform],
   });
-  const output = world.query({ write: [GlobalTransform] });
-  const hierarchy = world.query({ read: [Transform, ChildOf] });
+  const hierarchy = world.query({ read: [Transform, ChildOf], write: [GlobalTransform] });
+  const transform = world.query({ read: [Transform], write: [GlobalTransform] });
   const missingGlobal = world.query({ with: [Transform], without: [GlobalTransform] });
   const missingTransform = world.query({ with: [GlobalTransform], without: [Transform] });
-  if (!flatOutput.ok || !output.ok || !hierarchy.ok || !missingGlobal.ok || !missingTransform.ok) {
+  if (
+    !flatOutput.ok ||
+    !hierarchy.ok ||
+    !transform.ok ||
+    !missingGlobal.ok ||
+    !missingTransform.ok
+  ) {
     return pairError(0 as EntityHandle, 'valid Transform and GlobalTransform pair queries');
   }
+  const hierarchyWriter = getDerivedWriter(hierarchy.value, GlobalTransform);
+  const transformWriter = getDerivedWriter(transform.value, GlobalTransform);
+  if (!hierarchyWriter.ok || !transformWriter.ok) {
+    return pairError(0 as EntityHandle, 'dense Transform and ChildOf derived bindings');
+  }
   scratch.flatQuery = flatOutput.value as FlatQuery;
-  scratch.outputQuery = output.value as OutputQuery;
   scratch.hierarchyQuery = hierarchy.value as HierarchyQuery;
+  scratch.transformQuery = transform.value as TransformQuery;
+  scratch.hierarchyWriter = hierarchyWriter.value as HierarchyWriter;
+  scratch.transformWriter = transformWriter.value as TransformWriter;
   scratch.missingGlobalQuery = missingGlobal.value as MissingGlobalQuery;
   scratch.missingTransformQuery = missingTransform.value as MissingTransformQuery;
   return ok(undefined);
@@ -113,7 +244,25 @@ function scratchFor(world: World): Scratch {
     rotation: new Float32Array(4),
     scale: new Float32Array(3),
     local: mat4.create(),
-    hierarchyPath: [] as number[],
+    parent: mat4.create(),
+    candidate: mat4.create(),
+    hierarchyStackEntities: [] as EntityHandle[],
+    hierarchyStackChildren: [] as number[],
+    hierarchyProbeEntities: [] as EntityHandle[],
+    hierarchyCurrentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyParentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyChildCursor: { bindingIndex: -1, row: -1 },
+    hierarchyResidualCursor: { bindingIndex: -1, row: -1 },
+    hierarchyResidualParentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyRootCursor: createHierarchyRootCursor(),
+    hierarchyStates: [],
+    hierarchyChanged: [],
+    hierarchyBindingTables: [],
+    hierarchyBindingRows: [],
+    flatChanged: [],
+    flatBindingTables: [],
+    flatBindingRows: [],
+    flatStructureEpoch: -1,
   };
   SCRATCH.set(world, created);
   return created;
@@ -191,46 +340,7 @@ function composeFlatColumns(
   }
 }
 
-function writeWorld(
-  world: World,
-  output: ReturnType<World['query']> extends Result<infer Q, unknown> ? Q : never,
-  entity: EntityHandle,
-  value: Mat4,
-): Result<void, SceneError> {
-  const row = output.at(entity);
-  if (row === undefined) {
-    return err(
-      new SceneError({
-        code: 'hierarchy-broken',
-        expected: 'each Transform entity to carry a GlobalTransform pair',
-        hint: 'attach GlobalTransform at scene authoring or import time, then retry propagation',
-        detail: { entity, parent: entity },
-      }),
-    );
-  }
-  const current = world.get(entity, GlobalTransform);
-  if (!current.ok)
-    return err(
-      new SceneError({
-        code: 'hierarchy-broken',
-        expected: 'each Transform entity to carry a GlobalTransform pair',
-        hint: 'attach GlobalTransform at scene authoring or import time, then retry propagation',
-        detail: { entity, parent: entity },
-      }),
-    );
-  let changed = false;
-  for (let index = 0; index < value.length; index += 1) {
-    if (current.value.world[index] !== value[index]) {
-      changed = true;
-      break;
-    }
-  }
-  if (!changed) return ok(undefined);
-  row.mut(GlobalTransform).world.set(value);
-  return ok(undefined);
-}
-
-function propagateFlat(scratch: Scratch): Result<void, SceneError> {
+function propagateFlat(world: World, scratch: Scratch): Result<void, SceneError> {
   const query = scratch.flatQuery;
   if (query === undefined)
     return err(
@@ -252,182 +362,843 @@ function propagateFlat(scratch: Scratch): Result<void, SceneError> {
     }
   } catch (cause) {
     const error = cause as EcsError;
-    return err(
-      new SceneError({
-        code: 'hierarchy-broken',
-        expected: 'derived GlobalTransform range publication to succeed',
-        hint: error.hint,
-        detail: {
-          kind: 'derived-write',
-          entity: 0 as EntityHandle,
-          parent: 0 as EntityHandle,
-          bindingIndex,
-          base: 0,
-          start: 0,
-          count: 0,
-          cause: error,
-        },
-      }),
-    );
+    return err(derivedWriteError(error, bindingIndex));
+  }
+
+  // A structural relation change can turn an unchanged Transform row into a
+  // flat root (most importantly ChildOf removal). The changed Transform query
+  // above cannot observe that transition, so once per structure epoch scan the
+  // already-bound numeric Transform rows and publish only differing roots.
+  const transformWriter = scratch.transformWriter;
+  if (transformWriter === undefined) {
+    return pairError(0 as EntityHandle, 'dense Transform and GlobalTransform derived bindings');
+  }
+  const transformBindings = transformWriter.bindings as readonly TransformBinding[];
+  const structureEpoch = world[worldInternal].getStructureEpoch();
+  if (scratch.flatStructureEpoch === structureEpoch) return ok(undefined);
+
+  ensureFlatBuffers(scratch, transformBindings);
+  resetFlatBuffers(scratch);
+  for (let bindingIndex = 0; bindingIndex < transformBindings.length; bindingIndex += 1) {
+    const binding = transformBindings[bindingIndex];
+    const changed = scratch.flatChanged[bindingIndex];
+    if (binding === undefined || changed === undefined) continue;
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      const entity = (binding.entities[row] ?? 0) as EntityHandle;
+      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, 'parent');
+      if (parentRaw !== undefined && parentRaw !== ENTITY_NULL_RAW) continue;
+      countPropagation('flatStructuralRootRows');
+      composeBindingRow(binding, row, undefined, 0, scratch, changed);
+    }
+  }
+  for (let bindingIndex = 0; bindingIndex < transformBindings.length; bindingIndex += 1) {
+    const changed = scratch.flatChanged[bindingIndex];
+    if (changed === undefined) continue;
+    const published = transformWriter.publishChangedRows(bindingIndex, changed);
+    if (!published.ok) return err(derivedWriteError(published.error, bindingIndex));
   }
+  scratch.flatStructureEpoch = structureEpoch;
   return ok(undefined);
 }
 
-interface HierarchyEntry {
-  readonly entity: EntityHandle;
-  parent: EntityHandle | undefined;
-  readonly position: Float32Array;
-  readonly rotation: Float32Array;
-  readonly scale: Float32Array;
-  readonly world: Mat4;
-  state: 0 | 1 | 2;
+interface TransformColumnShape {
+  readonly pos: ArrayLike<number>;
+  readonly quat: ArrayLike<number>;
+  readonly scale: ArrayLike<number>;
+}
+
+interface OutputColumnShape {
+  readonly world: Float32Array;
+}
+
+interface HierarchyColumnShape extends TransformColumnShape {
+  readonly parent: ArrayLike<number>;
+}
+
+function transformColumns(binding: TransformBinding | HierarchyBinding): TransformColumnShape {
+  return binding.read as unknown as TransformColumnShape;
 }
 
-function findEntry(entries: readonly HierarchyEntry[], entity: EntityHandle): number {
-  for (let index = 0; index < entries.length; index += 1) {
-    if (entries[index]?.entity === entity) return index;
+function hierarchyColumns(binding: HierarchyBinding): HierarchyColumnShape {
+  return binding.read as unknown as HierarchyColumnShape;
+}
+
+function worldColumn(binding: TransformBinding | HierarchyBinding): Float32Array {
+  return (binding.write as unknown as OutputColumnShape).world;
+}
+
+function hierarchyError(
+  code: 'hierarchy-broken' | 'hierarchy-cycle',
+  entity: EntityHandle,
+  parent: EntityHandle,
+  expected: string,
+  hint: string,
+): SceneError {
+  return new SceneError({ code, expected, hint, detail: { entity, parent } });
+}
+
+function writeCandidate(
+  binding: TransformBinding | HierarchyBinding,
+  row: number,
+  candidate: Mat4,
+  changed: Uint8Array,
+): void {
+  const worlds = worldColumn(binding);
+  const base = row * 16;
+  for (let index = 0; index < 16; index += 1) {
+    if (worlds[base + index] !== candidate[index]) {
+      worlds.set(candidate, base);
+      changed[row] = 1;
+      return;
+    }
   }
-  return -1;
 }
 
-function resolveEntry(
-  index: number,
-  entries: HierarchyEntry[],
-  world: World,
-  output: ReturnType<World['query']> extends Result<infer Q, unknown> ? Q : never,
+function composeBindingRow(
+  binding: TransformBinding | HierarchyBinding,
+  row: number,
+  parentBinding: TransformBinding | undefined,
+  parentRow: number,
   scratch: Scratch,
-): Result<void, SceneError> {
-  const entry = entries[index];
-  if (entry === undefined || entry.state === 2) return ok(undefined);
-  if (entry.state === 1) {
-    // A cycle is an input error, but leaving every member on its previous
-    // GlobalTransform would make the renderer consume stale derived facts.
-    // Cut the complete active cycle segment to roots for this failed frame;
-    // the authored ChildOf values remain untouched and the next repaired
-    // propagation recomputes the normal hierarchy.
-    const cycleParent = entry.parent ?? entry.entity;
-    const cycleStart = scratch.hierarchyPath.indexOf(index);
-    const start = cycleStart < 0 ? 0 : cycleStart;
-    for (let pathIndex = start; pathIndex < scratch.hierarchyPath.length; pathIndex += 1) {
-      const cycleEntry = entries[scratch.hierarchyPath[pathIndex] ?? -1];
-      if (cycleEntry !== undefined) cycleEntry.parent = undefined;
+  changed: Uint8Array,
+): void {
+  // Hierarchy bindings carry the parent column; flat structural-root repair
+  // uses the same numeric kernel but is intentionally counted separately.
+  if ('parent' in (binding.read as object)) countPropagation('hierarchyRowsEvaluated');
+  const local = transformColumns(binding);
+  const offset = row * 3;
+  composeColumns(local.pos, local.quat, local.scale, scratch.local, scratch, offset, row * 4);
+  if (parentBinding === undefined) {
+    scratch.candidate.set(scratch.local);
+  } else {
+    const parentWorld = worldColumn(parentBinding);
+    const parentOffset = parentRow * 16;
+    for (let index = 0; index < 16; index += 1) {
+      scratch.parent[index] = parentWorld[parentOffset + index] ?? 0;
     }
-    return err(
-      new SceneError({
-        code: 'hierarchy-cycle',
-        expected: 'a parent-before-child Transform hierarchy',
-        hint: 'repair the ChildOf cycle and retry TransformPropagation',
-        detail: { entity: entry.entity, parent: cycleParent },
-      }),
-    );
+    // Column-major composition is intentionally identical to the previous
+    // matrix path: Global = Parent * Local, with no TRS decomposition.
+    mat4.multiply(scratch.candidate, scratch.parent, scratch.local);
   }
-  entry.state = 1;
-  scratch.hierarchyPath.push(index);
-  let parentIndex = entry.parent === undefined ? -1 : findEntry(entries, entry.parent);
-  let failure: SceneError | undefined;
-  if (entry.parent !== undefined && parentIndex < 0) {
-    const local = world.get(entry.parent, Transform);
-    const global = world.get(entry.parent, GlobalTransform);
-    if (!local.ok || !global.ok) {
-      // The edge is invalid for this frame.  Treat the child as a local root
-      // so the output column reflects current authored input instead of the
-      // previous frame's world matrix, while still returning the structured
-      // error to the caller.
-      failure = new SceneError({
-        code: 'hierarchy-broken',
-        expected: 'each ChildOf parent to carry Transform and GlobalTransform',
-        hint: 'repair the missing parent pair before retrying propagation',
-        detail: { entity: entry.entity, parent: entry.parent },
-      });
-      entry.parent = undefined;
-      parentIndex = -1;
+  writeCandidate(binding, row, scratch.candidate, changed);
+}
+
+function ensureHierarchyBuffers(scratch: Scratch, bindings: readonly HierarchyBinding[]): void {
+  let same = scratch.hierarchyBindingTables.length === bindings.length;
+  if (same) {
+    for (let index = 0; index < bindings.length; index += 1) {
+      const binding = bindings[index];
+      if (
+        binding === undefined ||
+        scratch.hierarchyBindingTables[index] !== binding.tableId ||
+        scratch.hierarchyBindingRows[index] !== binding.rowCapacity
+      ) {
+        same = false;
+        break;
+      }
+    }
+  }
+  if (same) return;
+  scratch.hierarchyBindingTables = bindings.map((binding) => binding.tableId);
+  scratch.hierarchyBindingRows = bindings.map((binding) => binding.rowCapacity);
+  scratch.hierarchyStates = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+  scratch.hierarchyChanged = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+}
+
+function resetHierarchyBuffers(scratch: Scratch): void {
+  for (let index = 0; index < scratch.hierarchyStates.length; index += 1) {
+    scratch.hierarchyStates[index]?.fill(0);
+    scratch.hierarchyChanged[index]?.fill(0);
+  }
+}
+
+function ensureFlatBuffers(scratch: Scratch, bindings: readonly TransformBinding[]): void {
+  let same = scratch.flatBindingTables.length === bindings.length;
+  if (same) {
+    for (let index = 0; index < bindings.length; index += 1) {
+      const binding = bindings[index];
+      if (
+        binding === undefined ||
+        scratch.flatBindingTables[index] !== binding.tableId ||
+        scratch.flatBindingRows[index] !== binding.rowCapacity
+      ) {
+        same = false;
+        break;
+      }
+    }
+  }
+  if (same) return;
+  scratch.flatBindingTables = bindings.map((binding) => binding.tableId);
+  scratch.flatBindingRows = bindings.map((binding) => binding.rowCapacity);
+  scratch.flatChanged = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+}
+
+function resetFlatBuffers(scratch: Scratch): void {
+  for (const changed of scratch.flatChanged) changed.fill(0);
+}
+
+function derivedWriteError(cause: EcsError, bindingIndex: number): SceneError {
+  return new SceneError({
+    code: 'hierarchy-broken',
+    expected: 'derived GlobalTransform range publication to succeed',
+    hint: cause.hint ?? 'retry propagation on a healthy World',
+    detail: {
+      kind: 'derived-write',
+      entity: 0 as EntityHandle,
+      parent: 0 as EntityHandle,
+      bindingIndex,
+      base: 0,
+      start: 0,
+      count: 0,
+      cause,
+    },
+  });
+}
+
+function findHierarchyLocation(
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  entity: EntityHandle,
+  cursor: DerivedRangeCursor,
+): HierarchyBinding | undefined {
+  countPropagation('hierarchyEntityLookups');
+  if (!writer.locateEntity(entity, cursor)) return undefined;
+  return bindings[cursor.bindingIndex];
+}
+
+function findTransformLocation(
+  writer: TransformWriter,
+  bindings: readonly TransformBinding[],
+  entity: EntityHandle,
+  cursor: DerivedRangeCursor,
+): TransformBinding | undefined {
+  countPropagation('hierarchyEntityLookups');
+  if (!writer.locateEntity(entity, cursor)) return undefined;
+  return bindings[cursor.bindingIndex];
+}
+
+function countPublishedRows(changed: Uint8Array): void {
+  const trace = propagationTrace;
+  if (trace === undefined) return;
+  let runOpen = false;
+  for (let row = 0; row < changed.length; row += 1) {
+    if ((changed[row] ?? 0) !== 0) {
+      trace.hierarchyPublishedRows += 1;
+      if (!runOpen) {
+        trace.hierarchyPublishedRuns += 1;
+        runOpen = true;
+      }
     } else {
-      const relation = world.get(entry.parent, ChildOf);
-      entries.push({
-        entity: entry.parent,
-        parent: relation.ok && relation.value.parent !== null ? relation.value.parent : undefined,
-        position: new Float32Array(local.value.pos),
-        rotation: new Float32Array(local.value.quat),
-        scale: new Float32Array(local.value.scale),
-        world: mat4.create(),
-        state: 0,
-      });
-      parentIndex = entries.length - 1;
+      runOpen = false;
+    }
+  }
+}
+
+function noteHierarchyError(current: SceneError | undefined, next: SceneError): SceneError {
+  if (current === undefined) return next;
+  const currentEntity = Number(current.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+  const nextEntity = Number(next.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+  return nextEntity < currentEntity ||
+    (nextEntity === currentEntity && next.code.localeCompare(current.code) < 0)
+    ? next
+    : current;
+}
+
+function composeLocalHierarchyEntity(
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  entity: EntityHandle,
+  scratch: Scratch,
+  changed: Uint8Array[],
+): boolean {
+  const cursor = scratch.hierarchyCurrentCursor;
+  const binding = findHierarchyLocation(writer, bindings, entity, cursor);
+  if (binding === undefined) return false;
+  composeBindingRow(
+    binding,
+    cursor.row,
+    undefined,
+    0,
+    scratch,
+    changed[cursor.bindingIndex] as Uint8Array,
+  );
+  const states = scratch.hierarchyStates[cursor.bindingIndex];
+  if (states !== undefined) states[cursor.row] = 3;
+  return true;
+}
+
+function handleActiveCycle(
+  repeated: EntityHandle,
+  stackEntities: EntityHandle[],
+  stackChildren: number[],
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  scratch: Scratch,
+  changed: Uint8Array[],
+  report: (error: SceneError) => void,
+): void {
+  let cycleStart = -1;
+  for (let index = 0; index < stackEntities.length; index += 1) {
+    if (stackEntities[index] === repeated) {
+      cycleStart = index;
+      break;
     }
   }
-  if (parentIndex >= 0) {
-    const parentResult = resolveEntry(parentIndex, entries, world, output, scratch);
-    if (!parentResult.ok) failure = parentResult.error;
-    // A cycle fallback can cut this entry's authored edge while resolving its
-    // parent. Re-read the edge before composing so no cycle member consumes an
-    // uninitialized parent matrix.
-    parentIndex = entry.parent === undefined ? -1 : findEntry(entries, entry.parent);
-    if (parentIndex >= 0 && entries[parentIndex]?.state !== 2) parentIndex = -1;
-  }
-  composeColumns(entry.position, entry.rotation, entry.scale, scratch.local, scratch);
-  if (parentIndex >= 0) {
-    const parent = entries[parentIndex];
-    if (parent !== undefined) mat4.multiply(entry.world, parent.world, scratch.local);
+  if (cycleStart < 0) return;
+  const repeatedCursor: DerivedRangeCursor = { bindingIndex: -1, row: -1 };
+  const repeatedBinding = findHierarchyLocation(writer, bindings, repeated, repeatedCursor);
+  const repeatedParent =
+    repeatedBinding === undefined
+      ? repeated
+      : ((hierarchyColumns(repeatedBinding).parent[repeatedCursor.row] ??
+          ENTITY_NULL_RAW) as number as EntityHandle);
+  report(
+    hierarchyError(
+      'hierarchy-cycle',
+      repeated,
+      repeatedParent,
+      'a parent-before-child Transform hierarchy',
+      'repair the ChildOf cycle and retry TransformPropagation',
+    ),
+  );
+  for (let index = cycleStart; index < stackEntities.length; index += 1) {
+    const cycleEntity = stackEntities[index];
+    if (cycleEntity === undefined) continue;
+    composeLocalHierarchyEntity(writer, bindings, cycleEntity, scratch, changed);
+    stackChildren[index] = 0;
+  }
+}
+
+function walkChildren(
+  world: World,
+  root: EntityHandle,
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  transformWriter: TransformWriter,
+  transformBindings: readonly TransformBinding[],
+  scratch: Scratch,
+  report: (error: SceneError) => void,
+  allowCompletedRoot: boolean,
+): void {
+  countPropagation('hierarchyRootInvocations');
+  const stackEntities = scratch.hierarchyStackEntities;
+  const stackChildren = scratch.hierarchyStackChildren;
+  stackEntities.length = 0;
+  stackChildren.length = 0;
+
+  if (allowCompletedRoot) {
+    // Residual recovery may be entered once for each member of a malformed
+    // parent path. State 4 means a previous fallback walk already expanded
+    // this root and all reachable Children edges, so do not repeat that
+    // subtree for every cycle member.
+    const rootCursor = scratch.hierarchyRootCursor;
+    const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
+    if (rootBinding !== undefined) {
+      const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
+      if (state === 4) return;
+    }
   } else {
-    entry.world.set(scratch.local);
+    // This cursor is scratch-owned and reused for every root. A root walk is
+    // a hot invocation; allocating a cursor here would scale object churn with
+    // the number of roots even after all bindings have warmed.
+    const rootCursor = scratch.hierarchyRootCursor;
+    countPropagation('hierarchyRootCursorReuses');
+    const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
+    if (rootBinding !== undefined) {
+      const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
+      if (state !== 0) return;
+    }
   }
-  const write = writeWorld(world, output, entry.entity, entry.world);
-  if (!write.ok) {
-    scratch.hierarchyPath.pop();
-    return write;
+  stackEntities.push(root);
+  stackChildren.push(-1);
+
+  const currentCursor = scratch.hierarchyCurrentCursor;
+  const parentCursor = scratch.hierarchyParentCursor;
+  const childCursor = scratch.hierarchyChildCursor;
+  while (stackEntities.length > 0) {
+    const top = stackEntities.length - 1;
+    const current = stackEntities[top];
+    if (current === undefined) {
+      stackEntities.pop();
+      stackChildren.pop();
+      continue;
+    }
+    const hierarchyBinding = findHierarchyLocation(writer, bindings, current, currentCursor);
+    const nextChild = stackChildren[top] ?? -1;
+    if (nextChild < 0) {
+      if (hierarchyBinding !== undefined) {
+        const state = scratch.hierarchyStates[currentCursor.bindingIndex]?.[currentCursor.row] ?? 0;
+        if (state === 0) {
+          const states = scratch.hierarchyStates[currentCursor.bindingIndex];
+          if (states !== undefined) states[currentCursor.row] = 1;
+          const parentRaw = (hierarchyColumns(hierarchyBinding).parent[currentCursor.row] ??
+            ENTITY_NULL_RAW) as number;
+          let completed = false;
+          if (parentRaw === ENTITY_NULL_RAW) {
+            composeBindingRow(
+              hierarchyBinding,
+              currentCursor.row,
+              undefined,
+              0,
+              scratch,
+              scratch.hierarchyChanged[currentCursor.bindingIndex] as Uint8Array,
+            );
+            completed = true;
+          } else {
+            const parent = parentRaw as EntityHandle;
+            const parentBinding = findTransformLocation(
+              transformWriter,
+              transformBindings,
+              parent,
+              parentCursor,
+            );
+            const parentHierarchy = findHierarchyLocation(writer, bindings, parent, childCursor);
+            if (parentBinding === undefined) {
+              report(
+                hierarchyError(
+                  'hierarchy-broken',
+                  current,
+                  parent,
+                  'each ChildOf parent to carry Transform and GlobalTransform',
+                  'repair the missing parent pair before retrying propagation',
+                ),
+              );
+              composeBindingRow(
+                hierarchyBinding,
+                currentCursor.row,
+                undefined,
+                0,
+                scratch,
+                scratch.hierarchyChanged[currentCursor.bindingIndex] as Uint8Array,
+              );
+              completed = true;
+            } else if (parentHierarchy !== undefined) {
+              const parentState =
+                scratch.hierarchyStates[childCursor.bindingIndex]?.[childCursor.row] ?? 0;
+              if (parentState === 1) {
+                handleActiveCycle(
+                  parent,
+                  stackEntities,
+                  stackChildren,
+                  writer,
+                  bindings,
+                  scratch,
+                  scratch.hierarchyChanged,
+                  report,
+                );
+                completed = true;
+              } else if (parentState === 0) {
+                report(
+                  hierarchyError(
+                    'hierarchy-broken',
+                    current,
+                    parent,
+                    'Children to enumerate every parent-before-child edge',
+                    'repair the Children mirror and retry TransformPropagation',
+                  ),
+                );
+                composeBindingRow(
+                  hierarchyBinding,
+                  currentCursor.row,
+                  undefined,
+                  0,
+                  scratch,
+                  scratch.hierarchyChanged[currentCursor.bindingIndex] as Uint8Array,
+                );
+                completed = true;
+              } else {
+                composeBindingRow(
+                  hierarchyBinding,
+                  currentCursor.row,
+                  parentBinding,
+                  parentCursor.row,
+                  scratch,
+                  scratch.hierarchyChanged[currentCursor.bindingIndex] as Uint8Array,
+                );
+                completed = true;
+              }
+            } else {
+              composeBindingRow(
+                hierarchyBinding,
+                currentCursor.row,
+                parentBinding,
+                parentCursor.row,
+                scratch,
+                scratch.hierarchyChanged[currentCursor.bindingIndex] as Uint8Array,
+              );
+              completed = true;
+            }
+          }
+          if (completed && states !== undefined && states[currentCursor.row] === 1) {
+            states[currentCursor.row] = 2;
+          }
+        }
+      }
+      stackChildren[top] = 0;
+      continue;
+    }
+
+    const childrenLength = world[worldInternal].getArrayLength(current, Children, 'entities') ?? 0;
+    if (nextChild >= childrenLength) {
+      stackEntities.pop();
+      stackChildren.pop();
+      if (allowCompletedRoot) {
+        const completedCursor = scratch.hierarchyResidualCursor;
+        const completedBinding = findHierarchyLocation(writer, bindings, current, completedCursor);
+        const completedStates =
+          completedBinding === undefined
+            ? undefined
+            : scratch.hierarchyStates[completedCursor.bindingIndex];
+        if (completedStates !== undefined && completedStates[completedCursor.row] === 3) {
+          completedStates[completedCursor.row] = 4;
+        }
+      }
+      continue;
+    }
+    stackChildren[top] = nextChild + 1;
+    countPropagation('hierarchyEdgesVisited');
+    const childRaw = world[worldInternal].getArrayElement(current, Children, 'entities', nextChild);
+    if (childRaw === undefined || childRaw === ENTITY_NULL_RAW) {
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          current,
+          current,
+          'Children.entities to contain live child handles',
+          'repair the Children mirror and retry TransformPropagation',
+        ),
+      );
+      continue;
+    }
+    const child = childRaw as EntityHandle;
+    const childBinding = findHierarchyLocation(writer, bindings, child, childCursor);
+    if (childBinding === undefined) {
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          child,
+          current,
+          'each Children entry to carry Transform, GlobalTransform, and ChildOf',
+          'repair the child component pair before retrying propagation',
+        ),
+      );
+      continue;
+    }
+    const childParent = (hierarchyColumns(childBinding).parent[childCursor.row] ??
+      ENTITY_NULL_RAW) as number;
+    const childState = scratch.hierarchyStates[childCursor.bindingIndex]?.[childCursor.row] ?? 0;
+    if (childParent !== (current as number)) {
+      // Leave an unvisited child for the residual row-state pass. That pass
+      // can classify the complete path (including a rootless cycle) without
+      // emitting a premature mirror error that would hide the cycle cause.
+      if (childState === 0) continue;
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          child,
+          current,
+          'Children and ChildOf to describe the same parent',
+          'repair the relationship mirror and retry TransformPropagation',
+        ),
+      );
+      continue;
+    }
+    if (childState === 1) {
+      handleActiveCycle(
+        child,
+        stackEntities,
+        stackChildren,
+        writer,
+        bindings,
+        scratch,
+        scratch.hierarchyChanged,
+        report,
+      );
+    } else if (childState === 0) {
+      stackEntities.push(child);
+      stackChildren.push(-1);
+    }
+  }
+}
+
+function fallbackResidualPath(
+  world: World,
+  path: readonly EntityHandle[],
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  transformWriter: TransformWriter,
+  transformBindings: readonly TransformBinding[],
+  scratch: Scratch,
+  report: (error: SceneError) => void,
+): void {
+  // Root traversal owns the normal path.  A residual path is necessarily a
+  // malformed Children projection (or a rootless cycle); cut the complete
+  // path to local roots in one pass so no stale GlobalTransform survives the
+  // diagnostic.  Keeping the path as an explicit work list also makes this
+  // recovery O(path length), rather than repeatedly searching parent chains.
+  for (const entity of path) {
+    composeLocalHierarchyEntity(writer, bindings, entity, scratch, scratch.hierarchyChanged);
+  }
+  for (const entity of path) {
+    walkChildren(
+      world,
+      entity,
+      writer,
+      bindings,
+      transformWriter,
+      transformBindings,
+      scratch,
+      report,
+      true,
+    );
+  }
+}
+
+function resolveResidualPath(
+  world: World,
+  entity: EntityHandle,
+  writer: HierarchyWriter,
+  bindings: readonly HierarchyBinding[],
+  transformWriter: TransformWriter,
+  transformBindings: readonly TransformBinding[],
+  scratch: Scratch,
+  report: (error: SceneError) => void,
+): void {
+  const path = scratch.hierarchyProbeEntities;
+  path.length = 0;
+  const cursor = scratch.hierarchyResidualCursor;
+  const parentTransformCursor = scratch.hierarchyParentCursor;
+  const parentHierarchyCursor = scratch.hierarchyResidualParentCursor;
+  let current = entity;
+  while (true) {
+    countPropagation('hierarchyResidualParentProbes');
+    const binding = findHierarchyLocation(writer, bindings, current, cursor);
+    if (binding === undefined) break;
+    const states = scratch.hierarchyStates[cursor.bindingIndex];
+    const state = states?.[cursor.row] ?? 0;
+    if (state !== 0) {
+      const columns = hierarchyColumns(binding);
+      const parentRaw = (columns.parent[cursor.row] ?? ENTITY_NULL_RAW) as number;
+      report(
+        hierarchyError(
+          'hierarchy-cycle',
+          current,
+          parentRaw === ENTITY_NULL_RAW ? current : (parentRaw as EntityHandle),
+          'a parent-before-child Transform hierarchy',
+          'repair the ChildOf cycle and retry TransformPropagation',
+        ),
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report,
+      );
+      return;
+    }
+
+    if (states !== undefined) states[cursor.row] = 1;
+    path.push(current);
+    const parentRaw = (hierarchyColumns(binding).parent[cursor.row] ?? ENTITY_NULL_RAW) as number;
+    if (parentRaw === ENTITY_NULL_RAW) {
+      // Every null-parent row is enumerated as a root above.  Reaching one
+      // here means the materialized Children graph failed to expose the
+      // parent-first edge; preserve the explicit malformed-graph error.
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          current,
+          current,
+          'Children to enumerate every parent-before-child edge',
+          'repair the Children mirror and retry TransformPropagation',
+        ),
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report,
+      );
+      return;
+    }
+
+    const parent = parentRaw as EntityHandle;
+    const parentTransform = findTransformLocation(
+      transformWriter,
+      transformBindings,
+      parent,
+      parentTransformCursor,
+    );
+    const parentHierarchy = findHierarchyLocation(writer, bindings, parent, parentHierarchyCursor);
+    if (parentHierarchy === undefined) {
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          current,
+          parent,
+          parentTransform === undefined
+            ? 'each ChildOf parent to carry Transform and GlobalTransform'
+            : 'Children to enumerate every parent-before-child edge',
+          parentTransform === undefined
+            ? 'repair the missing parent pair before retrying propagation'
+            : 'repair the Children mirror and retry TransformPropagation',
+        ),
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report,
+      );
+      return;
+    }
+
+    const parentState =
+      scratch.hierarchyStates[parentHierarchyCursor.bindingIndex]?.[parentHierarchyCursor.row] ?? 0;
+    if (parentState === 0) {
+      current = parent;
+      continue;
+    }
+    if (parentState === 1) {
+      report(
+        hierarchyError(
+          'hierarchy-cycle',
+          parent,
+          current,
+          'a parent-before-child Transform hierarchy',
+          'repair the ChildOf cycle and retry TransformPropagation',
+        ),
+      );
+    } else {
+      report(
+        hierarchyError(
+          'hierarchy-broken',
+          current,
+          parent,
+          'Children to enumerate every parent-before-child edge',
+          'repair the Children mirror and retry TransformPropagation',
+        ),
+      );
+    }
+    fallbackResidualPath(
+      world,
+      path,
+      writer,
+      bindings,
+      transformWriter,
+      transformBindings,
+      scratch,
+      report,
+    );
+    return;
   }
-  entry.state = 2;
-  scratch.hierarchyPath.pop();
-  return failure === undefined ? ok(undefined) : err(failure);
 }
 
 function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneError> {
-  const query = scratch.hierarchyQuery;
-  const output = scratch.outputQuery;
-  if (query === undefined || output === undefined) {
+  const hierarchyWriter = scratch.hierarchyWriter;
+  const transformWriter = scratch.transformWriter;
+  if (hierarchyWriter === undefined || transformWriter === undefined) {
     return err(
       new SceneError({
         code: 'hierarchy-broken',
-        expected: 'paired Transform and GlobalTransform query access',
+        expected: 'paired Transform and GlobalTransform derived bindings',
         hint: 'register the scene components before running TransformPropagation',
       }),
     );
   }
-  const entries: HierarchyEntry[] = [];
-  for (const row of query) {
-    if (findEntry(entries, row.entity) >= 0) continue;
-    const local = row.get(Transform);
-    const parentValue = row.get(ChildOf).parent;
-    const parent = parentValue === null ? undefined : parentValue;
-    entries.push({
-      entity: row.entity,
-      parent,
-      position: new Float32Array(local.pos),
-      rotation: new Float32Array(local.quat),
-      scale: new Float32Array(local.scale),
-      world: mat4.create(),
-      state: 0,
-    });
-  }
-  scratch.hierarchyPath.length = 0;
+  const hierarchyBindings = hierarchyWriter.bindings as readonly HierarchyBinding[];
+  const transformBindings = transformWriter.bindings as readonly TransformBinding[];
+  if (hierarchyBindings.length === 0) {
+    // Keep the flat-only lane independent: it must not allocate hierarchy
+    // markers or scan every Transform row merely to prove that no ChildOf
+    // archetype exists.
+    scratch.hierarchyBindingTables.length = 0;
+    scratch.hierarchyBindingRows.length = 0;
+    scratch.hierarchyStates.length = 0;
+    scratch.hierarchyChanged.length = 0;
+    return ok(undefined);
+  }
+  ensureHierarchyBuffers(scratch, hierarchyBindings);
+  resetHierarchyBuffers(scratch);
   let firstError: SceneError | undefined;
-  for (let index = 0; index < entries.length; index += 1) {
-    const result = resolveEntry(index, entries, world, output, scratch);
-    if (!result.ok) {
-      const currentEntity = Number(result.error.detail?.entity ?? Number.MAX_SAFE_INTEGER);
-      if (firstError === undefined) {
-        firstError = result.error;
-      } else {
-        const firstEntity = Number(firstError.detail?.entity ?? Number.MAX_SAFE_INTEGER);
-        if (
-          currentEntity < firstEntity ||
-          (currentEntity === firstEntity && result.error.code.localeCompare(firstError.code) < 0)
-        ) {
-          firstError = result.error;
-        }
+  const report = (error: SceneError): void => {
+    firstError = noteHierarchyError(firstError, error);
+  };
+
+  // Start only at actual roots (flat Transform rows and null-parent
+  // ChildOf rows). Descendants are discovered exclusively through the ECS
+  // materialized Children lists, so every normal frame is parent-first and
+  // linear in rows plus relationship edges.
+  for (const binding of transformBindings) {
+    const entities = binding.entities;
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      const entity = (entities[row] ?? 0) as EntityHandle;
+      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, 'parent');
+      if (parentRaw === undefined || parentRaw === ENTITY_NULL_RAW) {
+        walkChildren(
+          world,
+          entity,
+          hierarchyWriter,
+          hierarchyBindings,
+          transformWriter,
+          transformBindings,
+          scratch,
+          report,
+          false,
+        );
       }
     }
   }
+
+  // Any remaining hierarchy row is either behind a malformed/missing mirror
+  // edge or belongs to a rootless cycle. Follow each residual parent chain
+  // once with the same row-state machine (not a per-node parent search), then
+  // cut that complete residual path to local space. This keeps malformed
+  // coverage linear in residual rows and edges while normal frames remain
+  // exclusively Children-driven.
+  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+    const binding = hierarchyBindings[bindingIndex];
+    if (binding === undefined) continue;
+    const entities = binding.entities;
+    const states = scratch.hierarchyStates[bindingIndex];
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      if ((states?.[row] ?? 0) !== 0) continue;
+      const entity = (entities[row] ?? 0) as EntityHandle;
+      resolveResidualPath(
+        world,
+        entity,
+        hierarchyWriter,
+        hierarchyBindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report,
+      );
+    }
+  }
+
+  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+    const changed = scratch.hierarchyChanged[bindingIndex];
+    if (changed === undefined) continue;
+    countPublishedRows(changed);
+    const published = hierarchyWriter.publishChangedRows(bindingIndex, changed);
+    if (!published.ok) {
+      const cause = published.error as EcsError;
+      report(derivedWriteError(cause, bindingIndex));
+    }
+  }
   return firstError === undefined ? ok(undefined) : err(firstError);
 }
 
@@ -435,7 +1206,7 @@ export function propagateTransforms(world: World): Result<void, SceneError> {
   const scratch = scratchFor(world);
   const pairs = validateTransformPairs(world, scratch);
   if (!pairs.ok) return pairs;
-  const flat = propagateFlat(scratch);
+  const flat = propagateFlat(world, scratch);
   if (!flat.ok) return flat;
   return propagateHierarchy(world, scratch);
 }