@forgeax/engine-scene 0.1.21 → 0.1.24

package/src/systems/propagate-transforms.ts

@@ -1,313 +1,1214 @@
 import {
   defineSystem,
   defineSystemSet,
+  type EcsError,
+  ENTITY_NULL_RAW,
   type EntityHandle,
   FixedUpdate,
+  type Query,
   type SystemHandle,
   Update,
   type World,
 } from '@forgeax/engine-ecs';
 import {
-  createWorldProjection,
-  setDerivedComponent,
-  type WorldProjection,
-} from '@forgeax/engine-ecs/projection';
+  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 { Transform } from '../components/transform';
+import { Children } from '../components/children';
+import { GlobalTransform, Transform } from '../components/transform';
 import { SceneError } from '../errors';
-import { projectHierarchy, type SceneHierarchySnapshot } from './hierarchy-projection';
 
 export const PROPAGATE_TRANSFORMS_SYSTEM = 'propagateTransforms' as const;
 export const PROPAGATE_TRANSFORMS_FIXED_SYSTEM = 'propagateTransformsFixed' as const;
 export const TransformSet = defineSystemSet({ name: 'transform' });
 export const TransformFixedSet = defineSystemSet({ name: 'transform-fixed' });
 
-interface LocalState {
-  readonly pos: Float32Array;
-  readonly quat: Float32Array;
-  readonly scale: Float32Array;
+/**
+ * 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;
 }
 
-interface PropagationCache {
-  readonly projection: WorldProjection;
-  readonly hierarchy: SceneHierarchySnapshot;
-  readonly parentOf: ReadonlyMap<EntityHandle, EntityHandle>;
-  readonly childrenOf: ReadonlyMap<EntityHandle, readonly EntityHandle[]>;
-  readonly entities: ReadonlySet<EntityHandle>;
-  readonly locals: Map<EntityHandle, LocalState>;
-  readonly derived: Map<EntityHandle, Float32Array>;
-  result: Result<void, SceneError>;
-}
-
-const CACHE = new WeakMap<World, PropagationCache>();
+let propagationTrace: TransformPropagationTrace | undefined;
+let hierarchyRootCursorAllocationCount = 0;
+let propagationTraceRootCursorAllocationStart = 0;
 
-interface TransformRegistrationLease {
-  refs: number;
+function createHierarchyRootCursor(): DerivedRangeCursor {
+  hierarchyRootCursorAllocationCount += 1;
+  return { bindingIndex: -1, row: -1 };
 }
 
-// A World can be consumed by more than one renderer/view. Keep the schedule
-// registration leased per World so one owner disposing cannot remove the
-// shared transform system from another owner. This is lifecycle bookkeeping,
-// not a second component/system authority; the World schedule remains the
-// source of truth.
-const REGISTRATION_LEASES = new WeakMap<World, TransformRegistrationLease>();
-
-function copyState(value: {
-  readonly pos: ArrayLike<number>;
-  readonly quat: ArrayLike<number>;
-  readonly scale: ArrayLike<number>;
-}): LocalState {
-  return {
-    pos: new Float32Array(value.pos),
-    quat: new Float32Array(value.quat),
-    scale: new Float32Array(value.scale),
+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,
   };
 }
 
-function sameArray(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
-  if (left.length !== right.length) return false;
-  for (let index = 0; index < left.length; index += 1) {
-    if (left[index] !== right[index]) return false;
+export function endTransformPropagationTrace(): TransformPropagationTrace {
+  const trace = propagationTrace;
+  propagationTrace = undefined;
+  const rootCursorAllocations =
+    hierarchyRootCursorAllocationCount - propagationTraceRootCursorAllocationStart;
+  propagationTraceRootCursorAllocationStart = hierarchyRootCursorAllocationCount;
+  if (trace !== undefined) {
+    trace.hierarchyRootCursorAllocations = rootCursorAllocations;
+    return trace;
   }
-  return true;
+  return {
+    hierarchyRootInvocations: 0,
+    hierarchyRootCursorReuses: 0,
+    hierarchyRootCursorAllocations: 0,
+    hierarchyEntityLookups: 0,
+    hierarchyRowsEvaluated: 0,
+    hierarchyEdgesVisited: 0,
+    hierarchyPublishedRows: 0,
+    hierarchyPublishedRuns: 0,
+    hierarchyResidualParentProbes: 0,
+    flatStructuralRootRows: 0,
+  };
 }
 
-function sameState(left: LocalState | undefined, right: LocalState): boolean {
-  return (
-    left !== undefined &&
-    sameArray(left.pos, right.pos) &&
-    sameArray(left.quat, right.quat) &&
-    sameArray(left.scale, right.scale)
-  );
+function countPropagation(name: keyof TransformPropagationTrace): void {
+  const trace = propagationTrace;
+  if (trace !== undefined) trace[name] += 1;
 }
 
-function compose(state: LocalState, out: Mat4): void {
-  mat4.compose(out, state.pos, state.quat, state.scale);
+interface Scratch {
+  position: Float32Array;
+  rotation: Float32Array;
+  scale: Float32Array;
+  local: Mat4;
+  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;
+  hierarchyQuery?: HierarchyQuery;
+  transformQuery?: TransformQuery;
+  hierarchyWriter?: HierarchyWriter;
+  transformWriter?: TransformWriter;
+  missingGlobalQuery?: MissingGlobalQuery;
+  missingTransformQuery?: MissingTransformQuery;
 }
 
-function indexChildren(
-  hierarchy: SceneHierarchySnapshot,
-): ReadonlyMap<EntityHandle, readonly EntityHandle[]> {
-  const childrenOf = new Map<EntityHandle, EntityHandle[]>();
-  for (const [child, parent] of hierarchy.parentOf) {
-    const children = childrenOf.get(parent);
-    if (children === undefined) childrenOf.set(parent, [child]);
-    else children.push(child);
-  }
-  return childrenOf;
-}
+type FlatQuery = Query<readonly [typeof Transform], readonly [typeof GlobalTransform]>;
+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 []>;
 
-function descendants(
-  childrenOf: ReadonlyMap<EntityHandle, readonly EntityHandle[]>,
-  roots: ReadonlySet<EntityHandle>,
-): Set<EntityHandle> {
-  const affected = new Set(roots);
-  const pending = [...roots];
-  for (let index = 0; index < pending.length; index += 1) {
-    const parent = pending[index];
-    if (parent === undefined) continue;
-    for (const child of childrenOf.get(parent) ?? []) {
-      if (affected.has(child)) continue;
-      affected.add(child);
-      pending.push(child);
-    }
-  }
-  return affected;
+interface RegistrationLease {
+  refs: number;
 }
 
-function hierarchyError(hierarchy: SceneHierarchySnapshot): Result<void, SceneError> {
-  const first = hierarchy.diagnostics[0];
-  if (first === undefined) return ok(undefined);
+const SCRATCH = new WeakMap<World, Scratch>();
+const REGISTRATION_LEASES = new WeakMap<World, RegistrationLease>();
+
+function pairError(entity: EntityHandle, expected: string): Result<void, SceneError> {
   return err(
     new SceneError({
-      code: first.code,
-      expected: first.expected,
-      hint: first.hint,
-      detail: first.detail,
+      code: 'hierarchy-broken',
+      expected,
+      hint: 'attach both Transform and GlobalTransform at scene authoring or import time, then retry propagation',
+      detail: { entity, parent: entity },
     }),
   );
 }
 
-function buildCache(world: World, projection: WorldProjection): PropagationCache {
-  const hierarchy = projectHierarchy(world);
-  const locals = new Map<EntityHandle, LocalState>();
-  const entities = new Set<EntityHandle>();
-  const query = world.query({ read: [Transform], optional: [ChildOf] });
-  if (query.ok) {
-    for (const row of query.value) {
-      const transform = row.get(Transform);
-      if (transform === undefined) continue;
-      entities.add(row.entity);
-      locals.set(row.entity, copyState(transform));
-    }
+function ensureQueries(world: World, scratch: Scratch): Result<void, SceneError> {
+  if (
+    scratch.flatQuery !== undefined &&
+    scratch.hierarchyQuery !== undefined &&
+    scratch.transformQuery !== undefined &&
+    scratch.hierarchyWriter !== undefined &&
+    scratch.transformWriter !== undefined &&
+    scratch.missingGlobalQuery !== undefined &&
+    scratch.missingTransformQuery !== undefined
+  ) {
+    return ok(undefined);
   }
-  return {
-    projection,
-    hierarchy,
-    parentOf: hierarchy.parentOf,
-    childrenOf: indexChildren(hierarchy),
-    entities,
-    locals,
-    derived: new Map(),
-    result: ok(undefined),
+  const flatOutput = world.query({
+    read: [Transform],
+    write: [GlobalTransform],
+    without: [ChildOf],
+    changed: [Transform],
+  });
+  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 ||
+    !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.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);
+}
+
+function validateTransformPairs(world: World, scratch: Scratch): Result<void, SceneError> {
+  const queryResult = ensureQueries(world, scratch);
+  if (!queryResult.ok) return queryResult;
+  const missingGlobal = scratch.missingGlobalQuery;
+  const missingTransform = scratch.missingTransformQuery;
+  if (missingGlobal === undefined || missingTransform === undefined) {
+    return pairError(0 as EntityHandle, 'valid Transform and GlobalTransform pair queries');
+  }
+  for (const row of missingGlobal) {
+    return pairError(row.entity, 'each Transform entity to carry a GlobalTransform pair');
+  }
+  for (const row of missingTransform) {
+    return pairError(row.entity, 'each GlobalTransform entity to carry a Transform pair');
+  }
+  return ok(undefined);
+}
+
+function scratchFor(world: World): Scratch {
+  const existing = SCRATCH.get(world);
+  if (existing !== undefined) return existing;
+  const created = {
+    position: new Float32Array(3),
+    rotation: new Float32Array(4),
+    scale: new Float32Array(3),
+    local: mat4.create(),
+    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;
 }
 
-function deriveEntity(
-  world: World,
-  entity: EntityHandle,
-  cache: PropagationCache,
-  affected: ReadonlySet<EntityHandle>,
-  visiting: Set<EntityHandle>,
-  published: Set<EntityHandle>,
-): Result<void, SceneError> {
-  if (!affected.has(entity) || cache.derived.has(entity)) return ok(undefined);
-  if (visiting.has(entity)) return ok(undefined);
-  visiting.add(entity);
-  const local = cache.locals.get(entity);
-  if (local === undefined) {
-    visiting.delete(entity);
-    return ok(undefined);
+function composeColumns(
+  position: ArrayLike<number>,
+  rotation: ArrayLike<number>,
+  scale: ArrayLike<number>,
+  out: Mat4,
+  scratch: Scratch,
+  positionStart = 0,
+  rotationStart = 0,
+): void {
+  scratch.position[0] = position[positionStart] ?? 0;
+  scratch.position[1] = position[positionStart + 1] ?? 0;
+  scratch.position[2] = position[positionStart + 2] ?? 0;
+  scratch.rotation[0] = rotation[rotationStart] ?? 0;
+  scratch.rotation[1] = rotation[rotationStart + 1] ?? 0;
+  scratch.rotation[2] = rotation[rotationStart + 2] ?? 0;
+  scratch.rotation[3] = rotation[rotationStart + 3] ?? 1;
+  scratch.scale[0] = scale[positionStart] ?? 1;
+  scratch.scale[1] = scale[positionStart + 1] ?? 1;
+  scratch.scale[2] = scale[positionStart + 2] ?? 1;
+  mat4.compose(out, scratch.position, scratch.rotation, scratch.scale);
+}
+
+function composeFlatColumns(
+  positions: ArrayLike<number>,
+  rotations: ArrayLike<number>,
+  scales: ArrayLike<number>,
+  worlds: Float32Array,
+  count: number,
+): void {
+  for (let row = 0; row < count; row += 1) {
+    const position = row * 3;
+    const rotation = row * 4;
+    const world = row * 16;
+    const x = rotations[rotation] ?? 0;
+    const y = rotations[rotation + 1] ?? 0;
+    const z = rotations[rotation + 2] ?? 0;
+    const w = rotations[rotation + 3] ?? 1;
+    const x2 = x + x;
+    const y2 = y + y;
+    const z2 = z + z;
+    const xx = x * x2;
+    const xy = x * y2;
+    const xz = x * z2;
+    const yy = y * y2;
+    const yz = y * z2;
+    const zz = z * z2;
+    const wx = w * x2;
+    const wy = w * y2;
+    const wz = w * z2;
+    const sx = scales[position] ?? 1;
+    const sy = scales[position + 1] ?? 1;
+    const sz = scales[position + 2] ?? 1;
+
+    worlds[world] = (1 - (yy + zz)) * sx;
+    worlds[world + 1] = (xy + wz) * sx;
+    worlds[world + 2] = (xz - wy) * sx;
+    worlds[world + 3] = 0;
+    worlds[world + 4] = (xy - wz) * sy;
+    worlds[world + 5] = (1 - (xx + zz)) * sy;
+    worlds[world + 6] = (yz + wx) * sy;
+    worlds[world + 7] = 0;
+    worlds[world + 8] = (xz + wy) * sz;
+    worlds[world + 9] = (yz - wx) * sz;
+    worlds[world + 10] = (1 - (xx + yy)) * sz;
+    worlds[world + 11] = 0;
+    worlds[world + 12] = positions[position] ?? 0;
+    worlds[world + 13] = positions[position + 1] ?? 0;
+    worlds[world + 14] = positions[position + 2] ?? 0;
+    worlds[world + 15] = 1;
   }
-  const parent = cache.parentOf.get(entity);
-  if (parent !== undefined && cache.entities.has(parent)) {
-    const parentResult = deriveEntity(world, parent, cache, affected, visiting, published);
-    if (!parentResult.ok) return parentResult;
-  }
-  const localWorld = mat4.create();
-  compose(local, localWorld);
-  const parentWorld = parent === undefined ? undefined : cache.derived.get(parent);
-  const resolved = mat4.create();
-  if (parentWorld === undefined) resolved.set(localWorld);
-  else mat4.multiply(resolved, parentWorld, localWorld);
-  const write = setDerivedComponent(world, entity, Transform, { world: resolved });
-  if (!write.ok) {
-    visiting.delete(entity);
+}
+
+function propagateFlat(world: World, scratch: Scratch): Result<void, SceneError> {
+  const query = scratch.flatQuery;
+  if (query === undefined)
     return err(
       new SceneError({
         code: 'hierarchy-broken',
-        expected: 'the derived Transform.world write to succeed',
-        hint: 'inspect the ECS mutation error before retrying transform propagation',
-        detail: { entity, parent: entity },
+        expected: 'a valid changed Transform write query',
+        hint: 'register the scene components before running TransformPropagation',
       }),
     );
+  const spans = query.spans();
+  if (!spans.ok) return pairError(0 as EntityHandle, 'dense numeric Transform spans');
+  let bindingIndex = 0;
+  try {
+    for (const span of spans.value) {
+      const local = span.get(Transform);
+      const world = span.mut(GlobalTransform).world;
+      composeFlatColumns(local.pos, local.quat, local.scale, world, span.length);
+      bindingIndex += 1;
+    }
+  } catch (cause) {
+    const error = cause as EcsError;
+    return err(derivedWriteError(error, bindingIndex));
   }
-  cache.derived.set(entity, resolved);
-  published.add(entity);
-  visiting.delete(entity);
+
+  // 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);
 }
 
-function drainPublishedChanges(
-  cache: PropagationCache,
-  published: ReadonlySet<EntityHandle>,
+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 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;
+    }
+  }
+}
+
+function composeBindingRow(
+  binding: TransformBinding | HierarchyBinding,
+  row: number,
+  parentBinding: TransformBinding | undefined,
+  parentRow: number,
+  scratch: Scratch,
+  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;
+    }
+    // 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);
+  }
+  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 {
+      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 drained = cache.projection.poll();
-  if (drained.status === 'rebuild') return true;
-  return drained.changes.every(
-    (change) =>
-      change.kind === 'derived-component-changed' &&
-      change.component === Transform &&
-      published.has(change.entity),
+  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 (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;
+  }
 }
 
-export function propagateTransforms(
+function walkChildren(
   world: World,
-  _hierarchy?: SceneHierarchySnapshot,
-): Result<void, SceneError> {
-  let cache = CACHE.get(world);
-  if (cache === undefined) {
-    cache = buildCache(world, createWorldProjection(world, { components: [Transform, ChildOf] }));
-    CACHE.set(world, cache);
-    const initial = new Set(cache.entities);
-    const published = new Set<EntityHandle>();
-    for (const entity of initial) {
-      const result = deriveEntity(world, entity, cache, initial, new Set(), published);
-      if (!result.ok) return result;
+  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;
     }
-    if (!drainPublishedChanges(cache, published)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+  } else {
+    // 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;
     }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
-  }
-
-  const evidence = cache.projection.poll();
-  if (evidence.status === 'rebuild') {
-    cache = buildCache(world, cache.projection);
-    CACHE.set(world, cache);
-    const all = new Set(cache.entities);
-    const published = new Set<EntityHandle>();
-    for (const entity of all) {
-      const result = deriveEntity(world, entity, cache, all, new Set(), published);
-      if (!result.ok) return result;
+  }
+  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;
     }
-    if (!drainPublishedChanges(cache, published)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+    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;
     }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
-  }
-  if (evidence.changes.length === 0) return cache.result;
-
-  const transformSeeds = new Set<EntityHandle>();
-  let rebuild = false;
-  for (const change of evidence.changes) {
-    if (
-      change.kind === 'entity-removed' ||
-      change.kind === 'component-added' ||
-      change.kind === 'component-removed'
-    ) {
-      rebuild = true;
-      break;
+
+    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;
     }
-    if (change.kind !== 'component-changed') continue;
-    if (change.component === ChildOf) {
-      rebuild = true;
-      break;
+    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;
     }
-    // Derived Transform publications are deliberately not dirty seeds. Only
-    // authored component-changed records can invalidate local TRS state.
-    if (change.component === Transform) transformSeeds.add(change.entity);
-  }
-  if (rebuild) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
-  }
-
-  // A World can record several authored writes before this pass. Read each
-  // seed once so the final local state decides whether propagation is needed.
-  const changed = new Set<EntityHandle>();
-  for (const entity of transformSeeds) {
-    const current = world.get(entity, Transform);
-    if (!current.ok) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+    if (childState === 1) {
+      handleActiveCycle(
+        child,
+        stackEntities,
+        stackChildren,
+        writer,
+        bindings,
+        scratch,
+        scratch.hierarchyChanged,
+        report,
+      );
+    } else if (childState === 0) {
+      stackEntities.push(child);
+      stackChildren.push(-1);
     }
-    const next = copyState(current.value);
-    if (!sameState(cache.locals.get(entity), next)) changed.add(entity);
-    cache.locals.set(entity, next);
   }
-  if (changed.size === 0) return cache.result;
+}
 
-  const affected = descendants(cache.childrenOf, changed);
-  const published = new Set<EntityHandle>();
-  for (const entity of affected) cache.derived.delete(entity);
-  for (const entity of affected) {
-    const result = deriveEntity(world, entity, cache, affected, new Set(), published);
-    if (!result.ok) return result;
+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);
   }
-  if (!drainPublishedChanges(cache, published)) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
+  for (const entity of path) {
+    walkChildren(
+      world,
+      entity,
+      writer,
+      bindings,
+      transformWriter,
+      transformBindings,
+      scratch,
+      report,
+      true,
+    );
   }
-  cache.result = hierarchyError(cache.hierarchy);
-  return cache.result;
+}
+
+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;
+  }
+}
+
+function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneError> {
+  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 derived bindings',
+        hint: 'register the scene components before running TransformPropagation',
+      }),
+    );
+  }
+  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;
+  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);
+}
+
+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(world, scratch);
+  if (!flat.ok) return flat;
+  return propagateHierarchy(world, scratch);
 }
 
 export const PropagateTransforms: SystemHandle<readonly []> = defineSystem({
@@ -341,7 +1242,7 @@ export function registerPropagateTransforms(
         world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
         world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
         REGISTRATION_LEASES.delete(world);
-        CACHE.delete(world);
+        SCRATCH.delete(world);
       }
     };
   }
@@ -360,17 +1261,18 @@ export function registerPropagateTransforms(
       .unwrap();
   }
   world.addSystems(FixedUpdate, TransformFixedSet, [PropagateTransformsFixed]).unwrap();
-  const lease: TransformRegistrationLease = { refs: 1 };
-  REGISTRATION_LEASES.set(world, lease);
+  REGISTRATION_LEASES.set(world, { refs: 1 });
   let active = true;
   return () => {
     if (!active) return;
     active = false;
+    const lease = REGISTRATION_LEASES.get(world);
+    if (lease === undefined) return;
     lease.refs -= 1;
     if (lease.refs !== 0) return;
     world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
     world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
     REGISTRATION_LEASES.delete(world);
-    CACHE.delete(world);
+    SCRATCH.delete(world);
   };
 }