@woosh/meep-engine 3.60.4 → 3.60.5

package/src/engine/ecs/transform/TRANSFORM64_MIGRATION_PLAN_2026_09_04.md

@@ -1,521 +0,0 @@
-# Transform → Transform64 migration plan
-
-*Revision 3, 2026-09-04. Revision 2 was rejected on three counts, all correctly: it invented a
-change-detection mechanism next to one the ECS already has, it proposed deleting engine code on
-"no importers" evidence, and its facade would have left the abstraction layers Transform64 exists to
-remove. This revision replaces the architecture; the survey work underneath it stands.*
-
-*Update, 2026-09-05: the change-detection mechanism specified below - `EventType.ComponentChanged`
-carrying `{klass, instance}` - has been replaced by one event name per component that announces
-itself: `TRANSFORM64_EVENT_CHANGE` (`@transform64/change`) and `TRANSFORM_ATTACHMENT_EVENT_CHANGE`
-(`@transform_attachment/change`), each sent with no payload, so a listener is woken only by the
-thing it asked about and has nothing to filter. `EventType.ComponentChanged` is gone, and with it
-the residual unknown about broadening it. Everything else here stands; read `ComponentChanged`
-throughout as "the changed component's own event".*
-
----
-
-## Where things stand
-
-`Transform64` is a `Float64Array` subclass, 23 elements: a column-major matrix at `[0..15]` whose
-translation column `[12..14]` **is** the translation, a rotation quaternion at `[16..19]`, a scale at
-`[20..22]`. One buffer, one allocation, no sub-objects, no signals, no flags. Thirty-six source files
-use it — `Node3D`, `Mesh`, the pose and skinning pipeline, the glTF loader, `MeshSystem`,
-`m4_decompose_array`.
-
-`Transform` is the registered ECS component: a class holding a live `Vector3` position, a live
-`Quaternion` rotation, a live `Vector3` scale, and a `Float32Array` matrix, whose constructor
-subscribes to all three sub-object signals and recomposes the matrix on every change. **256 files**
-import it across `src`, `editor` and `samples` — **100 production, 156 spec**.
-
-The origin commit `71ae86be1` calls Transform64 "a passive Float64Array transform **component**". The
-ECS side was always the destination. The work stalled at the renderer seam, and the seam is where the
-engine currently loses precision.
-
-### The gap
-
-`Transform` tells the world it moved. `Transform64` cannot, and — by design — must not learn how:
-it is one prototype over a `Float64Array` and nothing else. No fields, no callbacks, no version
-counter, no cached views. Anything that would widen the buffer or hang state off the instance
-defeats the reason the type exists.
-
-So notification has to live where notification already lives: in the dataset.
-
----
-
-## The three decisions this revision makes
-
-### 1. Change detection is `EventType.ComponentChanged`, sent through `sendEvent`
-
-The ECS already has a per-entity event channel, and component lifecycle already travels on it:
-
-```js
-// EntityComponentDataset.js:1202
-this.sendEvent(entity_id, EventType.ComponentAdded,   { klass: componentClass, instance: component_instance });
-// EntityComponentDataset.js:1068
-this.sendEvent(entity_id, EventType.ComponentRemoved, { klass: componentClass, instance: componentInstance });
-```
-
-`EventType` (`src/engine/ecs/EventType.js`) has exactly three members today. The addition is a
-fourth, with the identical payload shape:
-
-```js
-export const EventType = {
-    EntityRemoved:    "entityRemoved",
-    ComponentAdded:   "componentAdded",
-    ComponentRemoved: "componentRemoved",
-    ComponentChanged: "componentChanged"     // <- new: { klass, instance }
-};
-```
-
-A writer that mutates a component in place announces it:
-
-```js
-ecd.sendEvent(entity, EventType.ComponentChanged, { klass: Transform64, instance: t64 });
-```
-
-A consumer subscribes the way `PathDisplaySystem.js:125` already does, in `link`, and filters on
-`klass`. `addEntityEventListener` / `removeEntityEventListener` need no change, and the existing
-"any event" listener path picks it up for free.
-
-**Why coarse, and not per-field channels.** An earlier draft proposed a per-channel version column
-(translation / rotation / scale). That is wrong on its own terms: after
-`Transform64.multiplyTransforms` or `fromMatrix` rewrites the buffer wholesale, there is no channel
-the write belongs to — the honest answer is "all of them", which is the same as no channel at all.
-It also duplicates a distinction the dataset already draws: added / removed / changed is the
-component's lifecycle, and a second, finer axis running beside it is two mechanisms where one will
-do. Fine granularity is only meaningful when component data is flat, and a transform's is not.
-
-Making it the consumer's problem to work out what changed is the correct trade. **Over-reaction is
-acceptable** — a consumer that only cares about translation waking on a rotation write does redundant
-work, not wrong work. Where a consumer genuinely cannot afford that, it compares against its own
-retained copy; that cost sits with the one consumer that needs it rather than in the type everyone
-pays for.
-
-### 2. Nothing gets deleted on reachability evidence
-
-Revision 2 proposed deleting `EntityPath` / `EntityPathMarker`, `PerfectPanner`, `createDebugLabel`,
-`fabrik_solve`, `SpriteSystemPE` / `Sprite`, `setMesh` and `updateNodeByTransformAndBBB`, on the
-grounds that nothing in the repository imports them.
-
-**That reasoning does not hold for a library.** meep is an engine; its consumers are downstream
-applications, and `package.json` exports `./src/*`, `./editor/*` and `./samples/*` wholesale with all
-three in `files`. Every source file is published API. "No internal importer" is a statement about
-this repository, not about whether anyone calls it.
-
-There is no delete stage. Those files migrate like everything else. Two notes carried forward, as
-observations rather than licence:
-
-- `engine/graphics/ecs/mesh/setMesh.js:47` calls `component.internalApplyTransform`, which a
-  repository-wide grep finds at exactly that one call site. It would throw if reached. That is a bug
-  to fix or report, not evidence of death.
-- `src/view/minimap/**` imports `../../../../model/game/...` from the parent `moh` repository, and
-  `vitest.config.mjs:14-19` excludes its spec for that reason, in its own words. It is live code
-  whose dependency and whose consumer both sit outside this tree. Do not remove that exclude line.
-
-### 3. No facade, no views. `Transform` survives untouched and ends up unused
-
-Revision 2 proposed making `Transform` a subclass of `Transform64` with live `Vector3`/`Quaternion`
-views over its buffer, so the 256 importers would keep compiling unchanged. Rejected, for the reason
-that motivates the whole exercise: persisting a view layer reinstates exactly the abstraction
-Transform64 was built to strip. A `Transform64` is a bare `Float64Array` with one prototype in the
-chain. Views over its buffer, held anywhere durable, are the old design wearing new storage.
-
-The end state instead:
-
-| | |
-|---|---|
-| `Transform.js` | **Unchanged.** Byte-identical to today, still exported, still serializable |
-| `Transform64.js` | **Unchanged in shape.** 23 elements, no added fields |
-| Engine use of `Transform` | **None.** Every system, every editor tool, every spec is on `Transform64` |
-| `EventType.ComponentChanged` | The one new mechanism, in the ECS where it belongs |
-
-`Transform` becomes what an engine keeps for its consumers: a supported type that the engine itself
-no longer builds on. No shim to remove, no deprecation cliff, no deletion to schedule.
-
-**What replaces the facade as the migration vehicle** is the bridge that already exists and already
-works. `TerrainSystem` and `MeshSystem` do this today: hold a `Transform64`, poll the entity's
-`Transform`, and use `t64_equals_transform` to skip the copy when nothing moved. That is the
-sanctioned temporary state — one side owns the value, the other mirrors it — and it is temporary per
-subsystem, not per codebase.
-
-**The allocating getters stay as they are.** `t.translation` returning a fresh `Float64Array` view is
-the correct behaviour for a type that holds no state; caching it would mean a field. Hot paths use
-the scalar accessors (`translation_x`, `rotation_w`, …) and free functions that take
-`(array, offset)`. That is a call-site rule, enforced by the audit in Stage 2, not a type change.
-
----
-
-## Stages
-
-Ordering is by dependency, not by size. Every stage leaves the repository green.
-
-### Stage 0 — `Transform64` becomes a registered component · **M**
-
-**Goal:** an entity can carry a `Transform64`, and it survives a save round-trip.
-
-**Touches** `engine/ecs/transform/Transform64SerializationAdapter.js` (new),
-`engine/ecs/storage/populateEngineSerializationRegistry.js`, `engine/ecs/EntityComponentDataset.js`
-(verification only).
-
-**Work.** `registerComponentType` (`EntityComponentDataset.js:802`) keys off the class reference and
-imposes no shape requirement, so a `Float64Array` subclass registers as-is — but confirm the storage
-path, the clone path and `getAllComponents` before relying on it, since a typed-array subclass is
-unlike every component registered so far. Then add the adapter, modelled directly on
-`TransformSerializationAdapter`:
-
-```js
-export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter {
-    klass = Transform64;
-    version = 1;
-    // translation: 3 × Float64, as TransformSerializationAdapter already does
-    // rotation:    quat3_encode_to_uint32, as today
-    // scale:       v3_binary_equality_encode, as today
-    // matrix:      NOT serialized — derived by updateMatrix() on load
-}
-```
-
-Register it beside the existing one at `populateEngineSerializationRegistry.js:200`.
-
-**Note on the save format.** `TransformSerializationAdapter` already writes `writeFloat64` for
-position (`:24-26`) and already encodes rotation to a uint32. The byte layout for a `Transform64` is
-therefore *the same layout*, and the two adapters can share an encoding. Save compatibility is a
-smaller problem than it looks; the open question is the type name the registry keys on, which
-Stage 8 settles.
-
-**Proves it** A new `Transform64SerializationAdapter.spec.js` round-tripping through `BinaryBuffer`,
-plus a dataset spec that registers `Transform64`, links it to an entity, reads it back by class, and
-removes it.
-
-**Unblocks** everything.
-
----
-
-### Stage 1 — `EventType.ComponentChanged` · **S**
-
-**Goal:** the signalling mechanism exists and is documented, before anything sends it.
-
-**Touches** `engine/ecs/EventType.js`, `engine/ecs/EntityComponentDataset.js` (doc only).
-
-**Work.** Add the enum member. Document the `{ klass, instance }` payload contract on `sendEvent`
-next to the `@see` block at `:1721`. Nothing dispatches it yet, and no consumer subscribes — this
-stage is deliberately inert so the mechanism can be reviewed on its own.
-
-Decide here, and write down, whether the dataset itself should send it from any built-in path
-(it should not: the dataset cannot know a caller finished mutating a buffer, and a write-through
-accessor is the field-carrying design this plan rejects).
-
-**Proves it** `EventType.spec.js`: sending `ComponentChanged` reaches a listener registered with
-`addEntityEventListener`, reaches an "any event" listener, and does not fire on unrelated entities.
-
-**Unblocks** every migrated writer.
-
----
-
-### Stage 2 — Tripwires and the enrolment ratchet · **M**
-
-**Goal:** "the migration progressed" and "no hot path regressed" both become machine-checkable.
-
-**Touches** a new `engine/ecs/transform/migration_enrolment.spec.js`; a dev-only allocation counter.
-
-**Work.** Two guards.
-
-*The ratchet.* A spec holding the explicit list of files still importing `Transform.js`, scanning
-`src`, `editor` and `samples`. It fails if a file not on the list imports it (new coupling) and fails
-if a listed file no longer does (stale list — update it, and the number only falls). This is the
-progress meter for every later stage and the exit criterion at the end.
-
-*The allocation audit.* A dev-mode counter incremented by `Transform64`'s `translation` / `rotation` /
-`scale` getters — **behind a build flag, not a field on the instance**, so the shipped type is
-unchanged. Specs for the hot paths (physics step, `MeshSystem` update, first-person camera
-composition) assert the count is zero across a simulated frame. This is what makes "hot paths use
-scalar accessors" enforceable rather than a review convention.
-
-**Proves it** Both specs, red before the guard exists and green after.
-
-**Unblocks** every claim of progress made below.
-
----
-
-### Stage 3 — The scalar and free-function vocabulary · **M**
-
-**Goal:** every read and write a migrated call site needs, without allocating and without a view.
-
-**Touches** `core/geom/vec3/**`, `core/geom/3d/quaternion/**`, `core/geom/3d/mat4/**`,
-`engine/ecs/transform/t64_*.js`.
-
-**Work.** Inventory what the 256 files actually call — the census is dominated by `.position.set`,
-`.position.x/y/z`, `.rotation.set`, quaternion conversions (`toEulerAnglesYXZ`,
-`fromEulerAnglesYXZ`, `fromAxisAngle`, `multiplyQuaternions`, `rotateTowards`, `computeTwistAngle`)
-and `.scale.setScalar`. Map each to an existing `v3_*` / `quat3_*` free function; write only the ones
-genuinely missing. Follow the established convention — free functions over methods, no variant
-factories.
-
-The reading vocabulary is already there: `translation_x`, `rotation_w`, `scale_z`, and raw indexing
-via the exported offset constants. The writing vocabulary is `setTranslation` / `setRotation` /
-`setScale` plus `updateMatrix`.
-
-**The one rule that matters.** A write to rotation or scale needs `updateMatrix()`; a translation-only
-write does not, because the translation *is* the matrix column. Both then need the Stage 1 event.
-Where a call site does several writes, one `updateMatrix()` and one event at the end — not per write.
-
-**Proves it** Each new free function gets a spec. No behaviour change yet.
-
-**Unblocks** Stages 4–10.
-
----
-
-### Stage 4 — The graphics3 ↔ shade seam · **S**
-
-**Goal:** close the half-migrated seam first, because it is the one place both types already meet and
-the pattern the rest copies.
-
-**Touches** `engine/graphics3/MeshSystem.js`, `TerrainSystem.js`, `pose/query_entity_node_world_pose.js`,
-`shade_node_to_entity_composition.js`, `camera_sync_from_transform.js`, `DecalSystem.js`.
-
-**Work.** These systems hold a `Transform64` and mirror an entity's `Transform` into it. Once the
-entity carries a `Transform64` directly, the mirror and the poll both go away: the system reads the
-component. `t64_copy_from_transform` loses callers here; keep it until its last caller anywhere is
-gone.
-
-**The trap, verified.** `TerrainSystem.js:352` guards with `t64_equals_transform`, which compares
-*components only, by deliberate design* — its own doc says a matrix comparison "would answer a
-question about the lossy half", because `Transform`'s matrix is f32 while its components are f64.
-`Transform64.equals` is the opposite: "strict equality across the whole transform, `matrix` included".
-Swapping one for the other turns the guard matrix-inclusive, so a stale matrix on either side reads
-as a move, and the per-frame top-level acceleration structure rebuild this guard exists to prevent
-comes back. The replacement is a components-only comparison between two `Transform64`s — a new
-`t64_equals_components`, not `equals`.
-
-**Proves it** Existing `MeshSystem.spec.js` / `TerrainSystem.spec.js` green, plus a new spec asserting
-the tile guard still skips when only the matrix differs.
-
-**Unblocks** the pattern every later system follows.
-
----
-
-### Stage 5 — Readers · **L**
-
-**Goal:** migrate every site that only reads a transform. No event, no ordering question.
-
-**Touches** roughly 34 production files across `engine/sound/**`, `engine/navigation/ecs/**`,
-`engine/grid/**`, `engine/intelligence/behavior/**`, `engine/achievements/**`,
-`generation/markers/**`, `engine/ecs/terrain/**`, `engine/ecs/fow/**`, and the read half of
-`engine/graphics3/*System.js`.
-
-**Work.** Switch `dependencies` from `Transform` to `Transform64`; replace `.position.x` with
-`.translation_x` and friends. Hot loops take the scalar accessors; cold sites may use the allocating
-getters. Mechanical, one commit per subsystem, each independently revertible.
-
-**Proves it** Each subsystem's existing spec, unchanged in intent, with its fixture switched.
-
----
-
-### Stage 6 — Writers, and physics determinism · **L**
-
-**Goal:** migrate every site that writes a transform, and settle what f64 does to determinism.
-
-**Touches** `engine/physics/**` (the largest cluster), `engine/ecs/parent`,
-`engine/ecs/transform-attachment`, `engine/graphics3` write paths, `engine/animation/**`.
-
-**Work.** Each writer: write through the scalar setters, call `updateMatrix()` once if rotation or
-scale changed, then send `EventType.ComponentChanged`. Subscribers that previously hung off
-`position.onChanged` move to `addEntityEventListener` in `link` and drop it in `unlink`.
-
-**The precision change, and it is a fix.** `Transform.multiplyTransforms` composes through a
-module-level `const scratch_matrix = new Float32Array(16)` (`Transform.js:15`, used at `:361`), and
-that is the method `TransformAttachmentSystem.UpdateContext.update()` (`:63-67`) calls for **every
-attached entity's world pose**. Measured: `16777218` where exact is `16777217.75`. Every attachment's
-world transform is quantised to f32 today. Moving to `Transform64.multiplyTransforms` removes the
-quantisation — which means `engine/physics/determinism.spec.js` will see different numbers. They will
-be *more* accurate, and determinism is preserved (f64 arithmetic is as reproducible as f32 across
-platforms), but any fixture with baked-in expected values must be re-baselined deliberately, in its
-own commit, with the diff reviewed rather than accepted wholesale.
-
-**Proves it** Physics suite green after a reviewed re-baseline; a new spec asserting a rotation write
-emits exactly one `ComponentChanged` and a translation write emits one without an `updateMatrix`.
-
----
-
-### Stage 7 — Retained sub-object references · **M**
-
-**Goal:** close the pattern that has no `Transform64` equivalent.
-
-**Touches** roughly 14 sites in `engine/sound/**` and `engine/animation/**`, plus anything the
-Stage 2 ratchet surfaces.
-
-**Work.** These hold `transform.position` past the statement that fetched it — stored in a field,
-captured in a closure, or handed to an animation track. A `Transform64` getter returns a fresh view
-each call, so the reference is not live and identity comparison is meaningless. Each site becomes
-either a retained *copy* (when it wanted a snapshot) or a retained `{ entity, dataset }` pair re-read
-on use (when it wanted liveness). Animation tracks that write into a retained sub-object become
-writes through the component plus a Stage 1 event.
-
-**Proves it** A spec per converted site asserting the value tracks (or deliberately does not track)
-subsequent writes.
-
----
-
-### Stage 8 — Serialization identity, network, rollback · **M**
-
-**Goal:** decide what the persisted type is called, and what goes on the wire.
-
-**Touches** `Transform64SerializationAdapter`, `populateEngineSerializationRegistry.js`,
-`engine/network/adapters/TransformReplicationAdapter.js`, `engine/interpolation/**`.
-
-**Work.** Two decisions, both one-way.
-
-*Save identity.* The registry keys on the adapter's `klass`. Entities saved with a `Transform` load
-as `Transform`; entities saved with a `Transform64` load as `Transform64`. Whether old saves upgrade
-in place (via `TransformSerializationUpgrader_0_1`, extended) or the engine simply reads both is a
-product decision, not a technical one — state it and move on.
-
-*Wire format.* `TransformReplicationAdapter` deliberately uses Float32 for position and says so at
-`:19-30`: distinct from the save adapter precisely so saves keep full precision while the wire stays
-cheap. **That reasoning survives the migration unchanged** — the replication adapter keeps quantising
-on the wire regardless of the component's internal precision. This is not a bandwidth regression, and
-any claim that f64 doubles the packet is wrong.
-
-**Rollback.** Snapshot/restore must copy the buffer, not alias it. A `Transform64` is a
-`Float64Array`, so `set()` on a same-length buffer is the copy; `slice()` returns a plain
-`Float64Array` by the type's `Symbol.species`, which is correct for a snapshot but is *not* a
-`Transform64` — restore paths must not assume the prototype survived.
-
-**Proves it** Round-trip specs both ways; the existing network end-to-end and rollback specs green.
-
----
-
-### Stage 9 — Editor and samples · **L**
-
-**Goal:** the 19 production and 14 spec files in `editor/`, plus 2 in `samples/`.
-
-**Touches** `editor/ecs/component/{prototypeObjectEditor,registerEngineComponentEditors}.js`,
-`editor/tools/{TransformToolV2.js,v2/TransformControls.js,v2/GizmoNode.js}`,
-`editor/actions/concrete/TransformModifyAction.js`, the six `process/symbolic/*SymbolicDisplay.js`,
-`editor/selection/editor_pick.js`, `editor/templates/entity_templates.js`,
-`editor/persistence/buildNewSceneDataset.js`, `editor/camera/camera_framing.js`,
-`editor/view/prepareMeshLibrary.js`.
-
-**Work.** Two genuinely hard files and a mechanical tail.
-
-*The inspector.* `prototypeObjectEditor` builds a UI by walking a component's shape. A `Transform64`
-is 23 indexed numbers with accessors on the prototype — walked naively it renders 23 unlabelled
-fields. It needs a dedicated `Transform64Editor` registered by constructor identity, ahead of any
-generic `Float64Array` handling, presenting translation / rotation / scale as the three groups a user
-expects.
-
-*Undo/redo.* `TransformModifyAction` captures and restores a transform. Establish exactly what it
-captures; a captured `Transform64` must be a copied buffer, and a captured sub-object view is not a
-capture at all. This is Stage 7's problem in the one place where getting it wrong silently corrupts a
-user's edit history.
-
-**Proves it** Editor specs green; a new spec asserting an undo after a gizmo drag restores the exact
-prior buffer.
-
-**Unblocks** the exit criterion, which scans `editor/` too.
-
----
-
-### Stage 10 — First-person · **L**
-
-**Goal:** the largest single cluster — 32 files, of which 3 are production.
-
-**Touches** `engine/control/first-person/**`.
-
-**Work.** The survey's useful finding is that the cluster is 29 specs over a small production
-surface, concentrated in `FirstPersonPlayerControllerSystem.js`. The work is mostly fixture
-migration. The production work is the euler/quaternion conversions and the `forward`/`up`/`right`
-axes, all of which `Transform64` already offers directly — including as setters, which `Transform`
-does not have.
-
-**Proves it** The 29 specs, migrated fixture by fixture.
-
----
-
-### Stage 11 — Specs, docs, and the exit · **L**
-
-**Goal:** the remaining spec tree, the published surface, and a checkable finish.
-
-**Touches** the residual specs across all three roots, `README.md`, any shipped `.md` naming
-`Transform`, `npm run generate-types` output.
-
-**Work.** Migrate remaining fixtures. Regenerate declarations and confirm the consumer type-check
-budget has not risen. Note in the CHANGELOG that the engine now builds on `Transform64` and that
-`Transform` remains supported and unchanged — this is an addition, not a break, so it needs no major.
-
-**Exit criterion**
-
-```bash
-# 1. the engine no longer builds on the legacy component
-npx vitest run src/engine/ecs/transform/migration_enrolment.spec.js
-#    ALLOWED list === [] , roots = ["src", "editor", "samples"]
-
-# 2. Transform is byte-identical to where it started
-git diff --stat <migration-base>..HEAD -- src/engine/ecs/transform/Transform.js   # expect: EMPTY
-
-# 3. Transform64 gained no fields
-git diff <migration-base>..HEAD -- src/engine/ecs/transform/Transform64.js | grep '^+' | grep -v '^+++'
-#    expect: no new instance fields; TRANSFORM64_SIZE still 23
-
-# 4. no hot path allocates a view
-npx vitest run -t "allocates no component views"
-
-# 5. everything still passes
-npx vitest run && npm run check-types && npm run build-module
-```
-
-Checks 2 and 3 are the ones that distinguish this plan from the revision it replaces: the migration
-is done when the engine stopped using `Transform`, **not** when `Transform` changed.
-
----
-
-## Risk register
-
-| Risk | Early sign | Mitigation |
-|---|---|---|
-| Two sources of truth on one entity — a system reads `Transform` while another writes `Transform64` | A value that updates one frame late, or not at all, in a partially migrated subsystem | Migrate by entity archetype, not by file. The bridge helpers are the sanctioned interim, and only one side owns the value at a time |
-| Missing `updateMatrix()` after a rotation or scale write | A stale matrix reaching the renderer — visible as an object rendering at its previous orientation | The Stage 2 audit spec; and the rule that one write group ends in one `updateMatrix` + one event |
-| Over-reaction becomes a perf problem, not just redundant work | Frame time rising in a subsystem after its Stage 6 commit | Accepted by design; where it bites, the one affected consumer retains a copy and compares. Do not reintroduce channels |
-| Determinism fixtures re-baselined without review | A physics fixture diff accepted wholesale in a large commit | Re-baseline in its own commit, diff reviewed, and only after Stage 6's precision change is understood |
-| `Float64Array` subclass breaks something in component storage that only shows at scale | Clone, snapshot or serialization behaving oddly for `Transform64` but not other components | Stage 0 verifies the storage, clone and `getAllComponents` paths explicitly before anything depends on them |
-| Undo/redo captures a view instead of a copy | An undo that restores the *current* value, i.e. does nothing | Stage 9's dedicated spec |
-| `Symbol.species` surprises — `slice()` returns a plain `Float64Array` | A restore path producing an object without `Transform64`'s prototype | Called out in Stage 8; snapshot with `set()` into a real `Transform64` |
-
----
-
-## Summary
-
-| # | Stage | Effort | Blocked by |
-|---|---|---|---|
-| 0 | `Transform64` registered as a component + serialization adapter | M | — |
-| 1 | `EventType.ComponentChanged` | S | — |
-| 2 | Tripwires: enrolment ratchet + allocation audit | M | — |
-| 3 | Scalar and free-function vocabulary | M | — |
-| 4 | graphics3 ↔ shade seam | S | 0, 3 |
-| 5 | Readers | L | 3, 4 |
-| 6 | Writers + physics determinism | L | 1, 3, 5 |
-| 7 | Retained sub-object references | M | 3, 6 |
-| 8 | Serialization identity, network, rollback | M | 0 |
-| 9 | Editor and samples | L | 3, 6 |
-| 10 | First-person | L | 3, 6 |
-| 11 | Specs, docs, exit | L | 4–10 |
-
-**Critical path:** 0 → 3 → 4 → 5 → 6 → 11. Stages 1, 2 and 8 run alongside. Stages 9 and 10 are
-large but parallel to each other once 6 lands.
-
----
-
-## Residual unknowns
-
-- **Whether component storage handles a typed-array subclass cleanly.** Registration does — it keys
-  on the class reference and imposes no shape. Storage, cloning and any structured-clone path are
-  unverified. Stage 0 exists to settle this, and if it fails, the shape of the answer changes (a thin
-  subclass carrying ECS metadata, which would be a departure from "one prototype, nothing more" and
-  would need your call).
-- **Whether `EventType.ComponentChanged` should be sent for components other than transforms.** It is
-  a general mechanism and this plan only uses it for one type. Broadening it is a separate decision.
-- **The migration-by-archetype boundary.** Which entities carry which transform during the interim is
-  the highest-risk part of this plan and the least specified. Stage 4 establishes the pattern on the
-  smallest cluster deliberately, so the boundary is learned somewhere cheap.
-- **File counts** are `256 / 100 / 156` by direct grep across `src`, `editor` and `samples` on
-  2026-09-04. Re-derive before building the Stage 2 ratchet rather than trusting this number.