@forgeax/engine-scene 0.1.21 → 0.1.24

package/README.md

@@ -6,27 +6,98 @@
 ## Smallest useful example
 
 ```ts
-import { scenePlugin, Transform } from '@forgeax/engine-scene';
-import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { scenePlugin, Transform } from '@forgeax/engine/scene';
+import { createWorldContext, World } from '@forgeax/engine/ecs';
 
 const world = new World();
 const context = await createWorldContext(world, [scenePlugin()]);
-const entity = world.spawn({ component: Transform, data: {} }).unwrap();
+const entity = world
+  .spawn({ component: Transform, data: {} })
+  .unwrap();
 void entity;
 await context.fiber.restart();
 ```
 
 `scenePlugin()` is a native Cordis plugin. Its Fiber installs hierarchy
-propagation and removes it when the realm unloads. Read failures as
-`SceneError` and branch on `error.code`; do not parse messages.
+propagation and removes it when the realm unloads. The direct
+`propagateTransforms(world)` entry point returns `Result<void, SceneError>`;
+branch on `error.code` and repair a diagnosable stale edge, mirror mismatch, or
+cycle through `World.set`/`World.removeComponent` (or the owning structural
+command) before retrying while the World is healthy.
 
-Transform propagation publishes the exact recomputed frontier to the World's
-engine-owned change journal after a successful pass. A no-change pass publishes
-nothing. Persistent consumers can therefore update a moved subtree without
-rescanning unrelated transforms, while `Transform.world` remains the sole
-resolved world-space authority.
+When the plugin runs from the scheduled path, `world.update(deltaSeconds)`
+wraps a thrown Scene failure as `system-failed`; the wrapper's
+`error.detail.cause` is the original `SceneError` (including its structured
+`code`/`detail`). That post-write system failure poisons the World, so the next
+use returns `world-poisoned`. Inspect `detail.cause`, stop using that World
+identity, discard it, and ask the App execution owner to call
+`app.execution.rebuild()` for a fresh World. Do not retry a poisoned or
+partially-written World in place.
 
-The authority also applies to dynamic loading: import `Transform`, `ChildOf`, and `scenePlugin` from `@forgeax/engine-scene` when a host resolves packages at runtime.
+If an explicitly malformed internal fixture reports a `Children` mirror
+mismatch, never write the target array directly. A same-target
+`world.set(child, ChildOf, { parent })` intentionally records the source
+evidence but skips mirror/index churn, so it cannot repair that mismatch. On a
+healthy World, repair through the source owner by removing and re-adding
+`ChildOf` (or reparenting through another target and then back to the intended
+one); if the failure has poisoned the World, discard it and rebuild through the
+App instead.
+
+Transform propagation writes the exact recomputed frontier into
+`GlobalTransform` and advances those rows' ordinary component versions only
+after a successful pass. A no-change pass advances no `GlobalTransform` row.
+Persistent consumers keep a `changed: [GlobalTransform]` Query, so a moved
+subtree is exposed as contiguous spans without a parallel event journal.
+`Transform` remains authored local TRS; `GlobalTransform` is the resolved
+world-space authority.
+
+For a valid hierarchy, propagation expands the ECS-maintained `Children`
+buffer from each root in parent-first order. `ChildOf` is the writable source
+fact; `Children` is a read-only materialized target, so source mutations and
+their reverse lists converge before the frame pass. The numeric traversal
+borrows ECS columns and uses only constant matrix scratch plus depth/row
+markers; it does not build a Scene graph or per-node matrix cache.
+
+Removing `ChildOf` is a structural root transition. Even when the authored
+`Transform` is unchanged, the next propagation composes and publishes that
+entity as a flat local root; ordinary same-value hierarchy recomputation still
+does not publish an unchanged `GlobalTransform` row.
+
+Flat propagation uses the same numeric kernel inline or through an installed
+SharedKernel executor. It borrows the existing changed query, joins root
+matrices before resolving the hierarchy, and leaves small or fragmented ranges
+inline. Scene builds its self-contained kernel module into `pkg/` from the same
+TypeScript source; no new Worker pool, component-name registry, or transform
+change journal is introduced. Partial shared writes poison the owning World.
+
+`Transform` declares the generic ECS requirement `GlobalTransform`. Therefore
+ordinary `world.spawn`, `world.addComponent`, and deferred `Commands.spawn`
+materialize the transient world column automatically at the structural
+boundary; scene code does not need a special pair-completion helper and the
+frame loop never scans entities to repair them. Explicit `GlobalTransform`
+data remains valid when an importer or recovery path needs to provide it.
+
+`ChildOf` declares `Transform` as a relationship-source requirement. A child
+created with only `{ component: ChildOf, data: { parent } }` therefore receives
+the full local/world pair transitively, while explicit `Transform` data still
+wins. This keeps hierarchy authoring small without adding per-frame repair or
+an additional scene-side component registry.
+
+Deferred `Commands.spawn` uses the same `{ component, data }` entries as
+`World.spawn`; the pending child is materialized and linked at command flush.
+For an existing child, the generic reparent call is
+`world.reparent(child, newParent, ChildOf, { parent: newParent })` and routes
+through the same relationship owner.
+
+`ChildOf` uses `linkedSpawn: true`: despawning a parent recursively despawns
+its linked hierarchy. A generic relationship may opt out, but that is not the
+Scene hierarchy lifecycle.
+
+Removing the required component is still an explicit malformed-state escape
+hatch, not an automatic cascade. Propagation reports that state as a
+structured `SceneError`, preserving a clear owner and recovery path.
+
+The authority also applies to dynamic loading: import `Transform`, `ChildOf`, and `scenePlugin` from `@forgeax/engine/scene` when a host resolves packages at runtime.
 
 ## Boundary
 

package/dist/__tests__/fixtures/malformed-hierarchy-edge.d.ts

@@ -1,8 +1,10 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 /**
- * Scene-owned malformed-edge fixture. The public relationship write accepts
- * stale handles as data; the projection then owns the liveness diagnostic.
- * Keeping this fixture on `world.set` avoids a private ECS graph seam.
+ * Scene-owned malformed-edge fixture. Production relationship writes reject
+ * stale targets and cycles before touching either side of the relationship.
+ * This test-only fixture deliberately corrupts the source column through the
+ * existing package-internal graph seam so projection can exercise its
+ * fail-closed diagnostics without weakening the public write contract.
  */
 export declare function setMalformedParentEdge(world: World, child: EntityHandle, parent: EntityHandle): void;
 //# sourceMappingURL=malformed-hierarchy-edge.d.ts.map

package/dist/__tests__/fixtures/malformed-hierarchy-edge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"malformed-hierarchy-edge.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/malformed-hierarchy-edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,IAAI,CAEN"}
+{"version":3,"file":"malformed-hierarchy-edge.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/malformed-hierarchy-edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAM/D;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,IAAI,CAmBN"}

package/dist/__tests__/flat-propagation.contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flat-propagation.contract.test.d.ts.map

package/dist/__tests__/flat-propagation.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-propagation.contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/flat-propagation.contract.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/flat-propagation.derived-writer.contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flat-propagation.derived-writer.contract.test.d.ts.map

package/dist/__tests__/flat-propagation.derived-writer.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-propagation.derived-writer.contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/flat-propagation.derived-writer.contract.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/flat-propagation.perf.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flat-propagation.perf.test.d.ts.map

package/dist/__tests__/flat-propagation.perf.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-propagation.perf.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/flat-propagation.perf.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/hierarchy-propagation.perf.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hierarchy-propagation.perf.test.d.ts.map

package/dist/__tests__/hierarchy-propagation.perf.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-propagation.perf.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/hierarchy-propagation.perf.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/scene-binding.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scene-binding.integration.test.d.ts.map

package/dist/__tests__/scene-binding.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-binding.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/scene-binding.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/schedule-order.contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schedule-order.contract.test.d.ts.map

package/dist/__tests__/schedule-order.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-order.contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/schedule-order.contract.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/structural.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=structural.test.d.ts.map

package/dist/__tests__/structural.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/structural.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/transform-carrier-consumers.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transform-carrier-consumers.test-d.d.ts.map

package/dist/__tests__/transform-carrier-consumers.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-carrier-consumers.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-carrier-consumers.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/transform-carrier-prototype.bench.d.ts

@@ -0,0 +1,39 @@
+type Workload = {
+    readonly workloadId: 'flat-dynamic' | 'hierarchy-dynamic' | 'sparse-dynamic' | 'structural-churn';
+    readonly rows: number;
+    readonly movers: number;
+};
+type CandidateId = 'B-independent-lanes' | 'C-ordinary-pair';
+type CandidateReceipt = {
+    readonly schemaVersion: 1;
+    readonly candidateId: CandidateId;
+    readonly workload: Workload;
+    readonly seed: number;
+    readonly frameCount: number;
+    readonly moverDensity: number;
+    readonly writerInference: 'local-only';
+    readonly queryInference: 'world-only';
+    readonly consumers: {
+        readonly authoringImport: boolean;
+        readonly propagation: boolean;
+        readonly query: boolean;
+        readonly querySpan: boolean;
+        readonly rendererSync: boolean;
+    };
+    readonly allocations: {
+        readonly warmup: number;
+        readonly steadyState: number;
+    };
+    readonly memoryBytes: number;
+    readonly stageTimingMs: {
+        readonly writer: number;
+        readonly propagation: number;
+        readonly query: number;
+        readonly total: number;
+    };
+    readonly worldChecksum: number;
+    readonly conceptCount: number;
+};
+export declare function collectPrototypeReceipts(): readonly CandidateReceipt[];
+export {};
+//# sourceMappingURL=transform-carrier-prototype.bench.d.ts.map

package/dist/__tests__/transform-carrier-prototype.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-carrier-prototype.bench.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-carrier-prototype.bench.ts"],"names":[],"mappings":"AAUA,KAAK,QAAQ,GAAG;IACd,QAAQ,CAAC,UAAU,EAAE,cAAc,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,KAAK,WAAW,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;AAE7D,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;QAClC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAiFF,wBAAgB,wBAAwB,IAAI,SAAS,gBAAgB,EAAE,CAKtE"}

package/dist/__tests__/transform-carrier-prototype.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transform-carrier-prototype.test-d.d.ts.map

package/dist/__tests__/transform-carrier-prototype.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-carrier-prototype.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-carrier-prototype.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/transform-carrier-prototype.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transform-carrier-prototype.test.d.ts.map

package/dist/__tests__/transform-carrier-prototype.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-carrier-prototype.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-carrier-prototype.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/transform-component-version.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transform-component-version.unit.test.d.ts.map

package/dist/__tests__/transform-component-version.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-component-version.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-component-version.unit.test.ts"],"names":[],"mappings":""}

package/dist/assets/scene-decoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/scene-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EAKd,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,UAAU,EAAE,OAAO,CAEvB,CAAC;AAqBpC,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAEnF;AA+FD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAWtD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAIhF,CAAC"}
+{"version":3,"file":"scene-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/scene-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EAKd,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,UAAU,EAAE,OAAO,CAEvB,CAAC;AAqBpC,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAEnF;AAoGD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAWtD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAIhF,CAAC"}

package/dist/components/child-of.d.ts

@@ -3,25 +3,34 @@ export { ChildOf } from './children';
  * Hierarchy back-reference: pointer from child entity to its parent.
  *
  * Store the parent `Entity` handle (returned by `world.spawn(...).unwrap()`)
- * in the `parent` field; `propagateTransforms` reads it each frame to
- * compose the child's derived `Transform.world` mat4 (child.world =
- * parent.world x child local). Despawning a child auto-detaches it from the
- * parent's Children list (relationship `onRemove` hook). Despawning the
- * parent does not auto-clean the child's ChildOf; the consumer removes the
- * stale ChildOf (`world.removeComponent`) or checks `world.get(parent, Entity)` for liveness.
+ * in the `parent` field; `propagateTransforms` follows the ECS-maintained
+ * `Children` list each frame to compose the child's derived
+ * `GlobalTransform.world` mat4 (child.world = parent.world x child local).
+ * `Transform` declares `GlobalTransform` as a
+ * generic ECS requirement, so normal spawn/add/command paths materialize the
+ * pair without scene-specific repair. Propagation still fails closed when an
+ * owner explicitly removes one half. Despawning a child auto-detaches it from
+ * its parent's Children list; despawning the parent follows ChildOf's
+ * linkedSpawn cascade, while a malformed internal fixture can still leave a
+ * stale source for Scene diagnostics.
  *
- * Because ChildOf declares a `relationship` mirror, the engine keeps the
- * parent's `Children.entities` reverse list consistent automatically: adding
- * ChildOf appends the child to the parent's Children, removing it (or
- * reparenting via the `exclusive` arm) prunes the stale entry. AI users no
- * longer hand-maintain both sides (the prior OOS-10 contract is retired).
+ * Because ChildOf declares a `relationship` mirror and a structural
+ * `Transform` requirement, the engine keeps the parent's `Children.entities`
+ * reverse list consistent automatically and materializes the local/world pair
+ * when the child did not author one: adding ChildOf appends the child to the
+ * parent's Children, removing it (or reparenting via the `exclusive` arm)
+ * prunes the stale entry. AI users no longer hand-maintain both sides (the
+ * prior OOS-10 contract is retired).
  * Reparenting is a plain re-add: `world.addComponent(child, { component:
  * ChildOf, data: { parent: newParent } })` on an entity that already carries
- * ChildOf auto-reparents (exclusive arm), or use `world.reparent(child,
- * newParent)`.
+ * ChildOf auto-reparents (exclusive arm). The generic convenience method has
+ * the same owner path and requires the relationship component plus its data:
+ * `world.reparent(child, newParent, ChildOf, { parent: newParent })`.
  *
  * @example Spawn a child entity referencing an already-spawned root:
- *   const root = world.spawn({ component: Transform, data: {...} }).unwrap();
+ *   const root = world.spawn(
+ *     { component: Transform, data: {...} },
+ *   ).unwrap();
  *   const child = world.spawn(
  *     { component: Transform, data: {...} },
  *     { component: ChildOf, data: { parent: root } },

package/dist/components/child-of.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"child-of.d.ts","sourceRoot":"","sources":["../../src/components/child-of.ts"],"names":[],"mappings":"AA2DA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}
+{"version":3,"file":"child-of.d.ts","sourceRoot":"","sources":["../../src/components/child-of.ts"],"names":[],"mappings":"AA6DA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}

package/dist/components/children.d.ts

@@ -2,25 +2,26 @@
  * Hierarchy forward-list of child entities.
  *
  * `entities` is a variable-length `array<entity>` field; each element is
- * an `Entity` u32 the AI user pushed via
- * `world.push(parent, Children, 'entities', child)`. The value returned by
- * `world.get(parent, Children).unwrap().entities` is a read-only
+ * an `Entity` u32 the ECS relationship owner materialized. The value returned
+ * by `world.get(parent, Children).unwrap().entities` is a detached read-only
  * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
- * the snapshot's `length` equals the live element count.
+ * mutating the returned array cannot change ECS-owned storage, and the
+ * snapshot's `length` equals the live element count. Internal Scene/ECS paths
+ * use the package-internal zero-copy array seams instead of this snapshot.
  *
  * Invariants:
- *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
- *     upward, D-P2). The forward list is for AI-user traversal / debug /
- *     inspection.
+ *   - `propagateTransforms` consumes Children from the ECS-owned materialized
+ *     buffer and expands each root parent-first. The forward list is also
+ *     available for AI-user traversal / debug / inspection.
  *   - Children <-> ChildOf consistency is maintained by the engine via the
  *     ChildOf `relationship` mirror hook (see ./child-of.ts): adding /
  *     removing / reparenting ChildOf on a child auto-updates the parent's
  *     `entities` list. AI users do not hand-sync the two sides for the
  *     hierarchy.
- *   - Stored entity u32s are NOT auto-cleared when the referenced entity is
- *     despawned (OOS-01 above); a `world.get(despawnedChild, ...)` call
- *     returns `Result.err(...)` so AI users discover the dangling state
- *     through the engine's structured-error channel.
+ *   - ChildOf's linked lifecycle keeps ordinary Children entries aligned: a
+ *     child despawn prunes its source slot and a parent despawn cascades. A
+ *     deliberately malformed/non-linked edge remains observable as a dead
+ *     handle and must be diagnosed through the structured error channel.
  *
  * @example Spawn a parent and two children via ChildOf (engine maintains Children):
  *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
@@ -36,8 +37,8 @@
  *   const snap = world.get(parent, Children).unwrap().entities;
  *   for (let i = 0; i < snap.length; i++) {
  *     const child = snap[i];
- *     // ... consume; world.get(child, ...) surfaces a structured error
- *     // if the child has been despawned (OOS-01 dangling-entity surface).
+ *     // ... consume; probe the handle before using it when reading a
+ *     // deliberately malformed/non-linked relationship.
  *   }
  */
 export declare const ChildOf: import("@forgeax/engine-ecs").Component<"ChildOf", {

package/dist/components/children.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"children.d.ts","sourceRoot":"","sources":["../../src/components/children.ts"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAgB,OAAO;;IAAU,QAAQ;;GAO9C,CAAC"}
+{"version":3,"file":"children.d.ts","sourceRoot":"","sources":["../../src/components/children.ts"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAgB,OAAO;;IAAU,QAAQ;;GAY9C,CAAC"}

package/dist/components/transform.d.ts

@@ -1,52 +1,16 @@
+/** Scene-owned derived world transform. Only TransformPropagation writes it. */
+export declare const GlobalTransform: import("@forgeax/engine-ecs").Component<"GlobalTransform", {
+    readonly world: "array<f32, 16>";
+}>;
 /**
- * Transform: local position `pos` (xyz), rotation `quat` (quaternion,
- * component order [x, y, z, w]), scale `scale` (xyz), plus the resolved
- * `world` mat4 (column-major 16 floats).
- *
- * Local TRS is stored as three inline stride-N array<f32, N> columns. The
- * propagate kernel composes each entity's local TRS into a mat4 and writes it
- * into the `world` column (root: world = local; child: world = parent.world x
- * local) using `@forgeax/engine-math` mat4 / vec3 / quat APIs (charter P4: do
- * not reinvent math). MVP recomposes every frame; dirty-flag optimization is
- * owned by feat-future-render-world.
- *
- * The `world` column is a fixed-capacity `array<f32, 16>` (feat-20260602):
- * the 16 contiguous floats live inline in a stride-16 column -- no BufferPool
- * slot. Read it via `world.get(e, Transform).world` which returns a live
- * `Float32Array` aliasing the column buffer. The view is transient: it aliases
- * the archetype column buffer and is valid only until the next structural
- * change (spawn / despawn / addComponent / removeComponent). Re-fetch the view
- * on every access; holding a view across a structural change is undefined
- * behaviour (the backing `ArrayBuffer` is detached on column growth, and
- * swap-remove at the same row index points to the wrong entity). All existing
- * hot paths (propagate / render-extract / pick) already comply -- see
- * `packages/ecs/README.md` Transient view contract section.
+ * Authored local position, rotation and scale columns.
  *
- * All three local columns carry explicit layer-2 defaults (identity
- * transform): `pos: [0, 0, 0]`, `quat: [0, 0, 0, 1]` (identity quaternion,
- * [x, y, z, w]), `scale: [1, 1, 1]`. quat and scale MUST stay explicit: the
- * layer-3 fallback for array<f32, N> is all-zero, which would land an invalid
- * zero quaternion / zero scale. The `world` field defaults to the identity
- * mat4. AI users spawn with `data: {}` or with only the fields they need to
- * override.
- *
- * @example Minimal spawn (local defaulted to identity, world = identity mat4):
- *   world.spawn({ component: Transform, data: {} });
- *
- * @example Override only the position, leaving rotation/scale at identity:
- *   world.spawn({ component: Transform, data: { pos: [0, 6, 0] } });
- *
- * @example Full explicit local form (defaults are opt-in):
- *   world.spawn({ component: Transform, data: {
- *     pos: [1, 2, 3],
- *     quat: [0, 0, 0, 1], // [x, y, z, w]
- *     scale: [1, 1, 1],
- *   } });
+ * The ECS `requires` declaration is the generic structural invariant: callers
+ * add `Transform`, while `GlobalTransform` is materialized once at spawn/add.
  */
 export declare const Transform: import("@forgeax/engine-ecs").Component<"Transform", {
     readonly pos: "array<f32, 3>";
     readonly quat: "array<f32, 4>";
     readonly scale: "array<f32, 3>";
-    readonly world: "array<f32, 16>";
 }>;
 //# sourceMappingURL=transform.d.ts.map

package/dist/components/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/components/transform.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,SAAS;;;;;EAUpB,CAAC"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/components/transform.ts"],"names":[],"mappings":"AAMA,gFAAgF;AAChF,eAAO,MAAM,eAAe;;EAM3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;EASrB,CAAC"}

package/dist/errors.d.ts

@@ -1,12 +1,33 @@
-import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { EcsError, EntityHandle } from '@forgeax/engine-ecs';
 export type SceneErrorCode = 'hierarchy-broken' | 'hierarchy-cycle';
 /** Scene-instantiation failures owned by the scene package. */
 export type SceneInstanceErrorCode = 'component-not-defined' | 'scene-override-type-mismatch';
 export { ComponentNotDefinedError } from '@forgeax/engine-ecs/projection';
-export interface SceneErrorDetail {
+/** The structured ECS failure retained by a Scene derived-write diagnostic. */
+export interface SceneErrorCause {
+    readonly code: EcsError['code'];
+    readonly expected?: string;
+    readonly hint?: string;
+    readonly detail?: unknown;
+}
+/** Location detail shared by hierarchy diagnostics and derived-write errors. */
+export interface SceneHierarchyErrorDetail {
+    readonly kind?: 'hierarchy';
+    readonly entity: EntityHandle;
+    readonly parent: EntityHandle;
+}
+/** A flat derived publication failure with its original ECS error intact. */
+export interface SceneDerivedWriteErrorDetail {
+    readonly kind: 'derived-write';
     readonly entity: EntityHandle;
     readonly parent: EntityHandle;
+    readonly bindingIndex: number;
+    readonly base: number;
+    readonly start: number;
+    readonly count: number;
+    readonly cause: SceneErrorCause;
 }
+export type SceneErrorDetail = SceneHierarchyErrorDetail | SceneDerivedWriteErrorDetail;
 export declare class SceneError extends Error {
     readonly code: SceneErrorCode;
     readonly expected: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,8BAA8B,CAAC;AAE9F,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAElC,IAAI,EAAE;QAChB,IAAI,EAAE,cAAc,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B;CAQF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,8BAA8B,CAAC;AAE9F,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,GAAG,4BAA4B,CAAC;AAExF,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAElC,IAAI,EAAE;QAChB,IAAI,EAAE,cAAc,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B;CAQF"}

package/dist/index.d.ts

@@ -4,11 +4,12 @@ export { ChildOf } from './components/child-of';
 export { Children } from './components/children';
 export { MorphWeights } from './components/morph-weights';
 export { Name } from './components/name';
-export { Transform } from './components/transform';
+export { GlobalTransform, Transform } from './components/transform';
 export { ComponentNotDefinedError, SceneError, type SceneErrorCode, type SceneInstanceErrorCode, } from './errors';
+export { resolveSceneEntity, type SceneBindingDeclarationError, type SceneBindingError, type SceneEntityRef, sceneEntity, validateSceneBindings, } from './instances/binding';
 export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
 export { type ExternalizedSceneAsset, externalizeSceneAsset, type SceneComponentSchemaResolver, type SceneExternalizationError, } from './instances/externalization';
-export { type SceneAssetResolver, type SceneInstanceStatePayload, type SceneInstantiateDiagnostic, type SceneInstantiateFlatOk, type SceneInstantiateOk, type SceneMembersSpawn, worldApplyMountOverride, worldBuildSceneEntityComponentDatas, worldDespawnDescendants, worldDespawnScene, worldDetachSceneMember, worldGetSceneAssetForInstance, worldGetSceneAssetResolver, worldGetSceneInstanceState, worldInstantiateScene, worldInstantiateSceneAsset, worldInstantiateSceneAssetFlat, worldInstantiateSceneFlat, worldInstantiateScenePayload, worldInstantiateSceneRec, worldMountOverridesToStateMap, worldReattachSceneMember, worldRemoveSceneOverride, worldResolveMountSource, worldResolveSceneAsset, worldResolveSceneInstanceStatePayload, worldSetSceneAssetResolver, worldSetSceneOverride, worldSpawnMountEntity, worldSpawnSceneMembers, worldValidateMountOverrides, } from './instances/scene-instances';
+export { type SceneAssetResolver, type SceneInstanceStatePayload, type SceneInstantiateDiagnostic, type SceneInstantiateFlatOk, type SceneInstantiateOk, type SceneMembersSpawn, worldApplyMountOverride, worldBuildSceneEntityComponentDatas, worldDespawnDescendants, worldDespawnScene, worldDetachSceneMember, worldGetSceneAssetForInstance, worldGetSceneAssetResolver, worldGetSceneInstanceState, worldInstantiateScene, worldInstantiateSceneAsset, worldInstantiateSceneAssetFlat, worldInstantiateSceneFlat, worldInstantiateScenePayload, worldInstantiateSceneRec, worldMountOverridesToStateMap, worldReattachSceneMember, worldRemoveSceneOverride, worldResolveMountSource, worldResolveSceneAsset, worldResolveSceneEntity, worldResolveSceneInstanceStatePayload, worldSetSceneAssetResolver, worldSetSceneOverride, worldSpawnMountEntity, worldSpawnSceneMembers, worldValidateMountOverrides, } from './instances/scene-instances';
 export { scenePlugin } from './plugin';
 export { projectHierarchy, type SceneHierarchyDiagnostic, type SceneHierarchySnapshot, } from './systems/hierarchy-projection';
 export { PROPAGATE_TRANSFORMS_SYSTEM, propagateTransforms, registerPropagateTransforms, TransformSet, } from './systems/propagate-transforms';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EACL,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,mCAAmC,EACnC,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,qCAAqC,EACrC,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,YAAY,GACb,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,WAAW,EACX,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EACL,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,mCAAmC,EACnC,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,qCAAqC,EACrC,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,YAAY,GACb,MAAM,gCAAgC,CAAC"}