@woosh/meep-engine 3.60.4 → 3.60.5

package/src/CODEC_LAYOUT_VERIFICATION.md

@@ -1,419 +0,0 @@
-# Codec layout — verification before the move
-
-2026-09-02. Re-derivation of the earlier session's claims about where the file-format codecs sit and
-what they depend on, done by resolving imports rather than by reading directory listings. Every
-claim is marked **confirmed**, **corrected** or **refuted**, with the command that decided it.
-
-All commands run from `packages/meep-engine/src`. The suite was green before anything moved:
-`npx vitest run` — 2227 files, 15393 tests, 69 s.
-
-The one tool this used that the earlier session did not is an import resolver: the task's grep
-(`from ['"].*(engine|shade|view)/`) only matches specifiers that *spell* one of those directory
-names, so a file inside `shade/renderer/loader/gltf/` importing `../../texture/TextureRole.js` is
-invisible to it. Resolving each relative specifier against the importing file and classifying the
-result by its top-level directory catches those. The script is a few lines of node; the resolved
-tables below come from it.
-
-```bash
-# resolve every relative import under DIR and print those landing in engine/, shade/ or view/
-node resolve_imports.mjs avif basis ktx2 shade/renderer/loader/gltf shade/renderer/loader/usd \
-     engine/asset/loaders/image/png engine/asset/loaders/image/jpeg
-```
-
----
-
-## Claim A — pure core plus thin skin: **confirmed, with three corrections and one finding that changes the rule**
-
-Resolved imports into `engine/`, `shade/` or `view/`, production files only:
-
-| Tree | Files importing engine/shade/view | What they import |
-|---|---|---|
-| `avif/native/` (110 files) | **1** — `api/avif_to_sampler2d.js` | `engine/graphics/texture/sampler/Sampler2D.js` |
-| `avif/` top level (3 files) | 0 | the encoder pool depends on `native/` and on `OffscreenCanvas` |
-| `basis/` (26 files) | **2** — `transcode_basis.js`, `transcode_uastc.js` | `TextureFormat`, `ShadeTexelData`, `texture_mip_size` |
-| `ktx2/` (7 files) | **2** — `ktx2_read.js`, `vk_format_to_texture_format.js` | `ShadeTexelData`, `gpu_texture_format_is_block_compressed`, `TextureFormat` |
-| `loaders/image/png/` | **1** — `prototypePNG.js` | `Sampler2D`, `sampler2d_to_html_canvas`, `AssetRequestScope`, `ArrayBufferLoader` |
-| `loaders/image/jpeg/` | 0 | — |
-| `loader/gltf/` | see below | — |
-| `loader/usd/` | see below | — |
-
-**Correction A1 — the AVIF skin is one file, not two.** `sampler2d_to_avif.js` imports nothing from
-`engine/`; it takes a duck-typed `{data, width, height, itemSize}` and reaches only `core/`. It is an
-adapter by *intent* (it is named after, and is the inverse of, the `Sampler2D` reader) but not by
-dependency. It still moves with its inverse, because the two are documented as a pair (AVIF decision
-D32) and their round-trip spec tests them together — but the reason is cohesion, not the rule.
-
-**Correction A2 — PNG has two doors, not one.** `ImageDecoderWorker.js` imports `png/PNGReader.js`
-and `codec/ThreadedImageDecoder.js` imports `png/PNG_HEADER_BYTES.js`. Both sit in
-`engine/asset/loaders/image/`, so the earlier "the worker is the only door" undercounted by one; the
-practical consequence is the same — two import lines to update. `prototypePNG.js` is a browser dev
-harness (hard-coded asset path, appends a canvas to `document.body`) and imports the engine; it is
-not format code and cannot move into `format/`. It moves up one level to `loaders/image/`.
-
-**Correction A3 — the glTF/USD seam is not where the earlier table drew it.** The resolver, not the
-grep, decides:
-
-```
-glTF, engine-free (imports core/ only, or nothing):
-  gltf_parse_container.js  gltf_read_accessor.js  gltf_component_type.js  GLTF_PRIMITIVE_MODE.js
-  gltf_used_image_indices.js  coalesce_array_duplicates.js  gltf_node_world_matrices.js  ext/**
-glTF, engine-facing:
-  load_gltf.js  tiny-gltf.js  gltf_create_material.js  gltf_create_texture.js
-  fix_up_material_sides.js  gltf_parse_alpha_mode.js (TransparencyMode)  gltf_image_roles.js (TextureRole)
-
-USD, engine-free:
-  parse_usda.js  usd_triangulate.js  usd_lz4.js  unpack_usdz.js  UsdError.js  usd_compose_transform.js
-USD, engine-facing:
-  load_usd.js  usd_build_scene.js  usd_decode_image.js (ShadeTexture, ShadeImage)
-USD, import-free but renderer-facing by contract:
-  UsdExtensionRegistry.js — its hooks return Node3D; it exists to plug into usd_build_scene
-```
-
-Against the earlier table: `gltf_node_world_matrices` (pure, and already consumed by the node-side
-virtual-geometry builder) was missing from the core list; `usd_compose_transform` was listed as skin
-and is pure; `UsdExtensionRegistry` was listed as core and is the scene builder's plugin registry.
-`gltf_image_roles` and `gltf_parse_alpha_mode` are skin, which the task's grep could not see.
-
-**Is `ktx2_read.js` a clean extraction or a rewrite? Extraction.** The engine coupling is in exactly
-three places, all at the boundary:
-
-1. The three `return` sites construct `ShadeTexelData` (two of them via the transcoders).
-2. Level byte-length validation is *delegated* to that constructor — the reader deliberately does
-   not check that a level's byte count matches its format and extent ("one authority on what a level
-   should weigh"). Two spec tests depend on this delegation.
-3. Its refusals are phrased in terms of what `ShadeTexelData` can model (no arrays, no cubes, no 1D).
-
-The decode path itself — header, DFD, key/values, level index, supercompression, Basis dispatch —
-touches nothing of the engine. The cut is: return a plain `{format, width, height, depth, levels}`
-record; have the reader check each level's byte length against the format table itself (it is a
-container reader, and a mislabelled payload is a malformed file); and move the *engine's*
-constraint — "one level or the whole chain" — into the adapter that builds `ShadeTexelData`, where
-the two spec tests that exercise it go too. The refusal messages that name `ShadeTexelData` are
-reworded to name the constraint. That is a dozen lines and two relocated tests, not a redesign.
-
-**Finding A4 — the texture tier speaks WebGPU format strings, and rule 1 as written cannot be met
-literally without duplication.** Every file on the texture side — the transcoders' target tables,
-`vk_format_to_texture_format`, the reader's block-compressed refusals — is written in terms of
-`TextureFormat` (the `GPUTextureFormat` enum as named constants) and `gpu_texture_format_info` (the
-block-size table), both under `shade/descriptor/texture/format/`, plus `texture_mip_size` from
-`shade/util/`. These are not engine code: they are a web standard's vocabulary as data, with no
-device, no renderer and no DOM behind them, and `shade/descriptor/` as a whole imports nothing but
-`core/` and its own `util/`. A transcoder that writes BC7 blocks has to be able to say "BC7", and the
-alternatives — a parallel enum inside `format/` translated at the adapter, or moving three vendored
-Shade files into `core/` — are either duplication or a change to Shade's layout that this refactor has
-no business making. Importer counts (5, 12 and 11 respectively) are small enough that moving them
-would be *possible*; it would just be the wrong reason to do it.
-
-So rule 1 is refined: **a format package may import `core/`, npm packages, and an explicit allowlist
-of three vocabulary modules — and nothing else under `shade/`, `engine/` or `view/`.** The allowlist
-is enumerated in the structural spec so it is a finite, visible list rather than a directory
-exception, and any fourth entry has to be argued for in a diff. This is the same shape as
-`STILL_COUPLED` in `meep_three_free.spec.js`, and it stays greppable.
-
-**Revised 2026-09-02.** The allowlist is a statement about depth, not about directories. A format
-module may import anything that is itself as low-level as `core/` — the structural spec's second test
-holds every entry to importing nothing but `core/` and other entries — and `Sampler2D` qualifies, a
-typed array with a width and a height. It joined the list together with the two error measures under
-`engine/graphics/texture/sampler/compare/` when the transcode and AVIF specs' five private PSNR copies
-were consolidated there. The rule's job is unchanged: no device, renderer or DOM behind a codec.
-
----
-
-## Claim B — JPEG is dead: **confirmed**
-
-```bash
-grep -rn "jpeg_decode\|JpegImage\|buildHuffmanTable\|idct8x8\|JpegFrame\|decodeScan\|buildComponentData\|jpeg_component_row" \
-  --include=*.js . | grep -v "^./engine/asset/loaders/image/jpeg/"
-# → empty
-grep -rn "loaders/image/jpeg\|/jpeg/" --include=*.js --include=*.json . \
-  | grep -v "^./engine/asset/loaders/image/jpeg/" | grep -v "avif/native/av1/tables"
-# → empty
-```
-
-`guessAssetType.js` maps `jpg`/`jpeg`/`png` to `"image"`. The `"image"` loader is
-`ImageRGBADataLoader`, whose codec chain is `CodecWithFallback(ThreadedImageDecoder, NativeImageDecoder)`.
-`ThreadedImageDecoder.test` sniffs `PNG_HEADER_BYTES` and returns false for everything else;
-`NativeImageDecoder` inherits `Codec.test`, which returns true unconditionally, and decodes through
-`new Image()` and a canvas. So every JPEG the engine has ever loaded went through the browser's
-decoder. The in-tree decoder is reachable from nothing but its own three spec files, which pass.
-
----
-
-## Claim C — `engine/asset/loaders/gltf/` is dead: **already resolved — the directory does not exist**
-
-```bash
-ls engine/asset/loaders/gltf          # → No such file or directory
-git log --oneline -3 -- engine/asset/loaders/gltf
-# a10895194 vestigial GLTF code from before Shade
-```
-
-Commit `a10895194` (five commits back) removed it. Migration step 1 is a no-op and is dropped.
-
----
-
-## Claim D — `core/binary/` is the right home for generic compression: **confirmed; the stated reasoning was wrong**
-
-The claim's justification — "zstd is used by KTX2 and by USD via lz4" — conflates two codecs. The
-actual consumers:
-
-```bash
-grep -rln "binary/lz4\|binary/zstd" --include=*.js . | grep -v "^./core/binary/" | grep -v spec
-# ktx2/ktx2_read.js                                         (zstd)
-# shade/renderer/geometry/virtual/format/frame/vgeo_*.js    (zstd, three files)
-# shade/renderer/loader/usd/usd_lz4.js                      (lz4)
-grep -rn "binary/meshopt" --include=*.js . | grep -v "^./core/binary/meshopt/" | grep -v spec
-# format/scene/gltf/ext/meshopt/MeshoptBufferViewExtension.js            (three imports)
-```
-
-zstd is shared between KTX2 and the virtual-geometry frame format; lz4 is USD-only today; meshopt is
-glTF-only today. So "shared between formats" holds for zstd alone. What actually justifies the tier
-is not the consumer count but the *dependency*: `core/binary/meshopt/` imports `core/assert`,
-`core/math` and `core/geom` and nothing else — it is a byte-array-in, byte-array-out codec with no
-notion of a bufferView, an accessor or a `KHR_` prefix. Everything glTF-specific about meshopt
-(reading the extension object, validating stride and count rules per mode, the two extension names'
-filter sets and version ceilings) already lives in `gltf/ext/meshopt/MeshoptBufferViewExtension.js`,
-exactly where the plan document that introduced it (`MESHOPT_COMPRESSION_PLAN.md` §1) drew the
-seam. `MeshoptCompressionFilter`/`Mode` cite the glTF spec in their doc comments because that is where
-the numbering is defined, not because they depend on it.
-
-**Held: the tier boundary is dependency direction, and meshopt is below formats by that test.**
-That it happens to have one consumer is a fact about today's format list, not about the codec.
-
----
-
-## Claim E — consumer counts are small: **confirmed for five of seven; glTF is larger and USD is zero**
-
-Production importers from outside each tree (specs listed separately):
-
-| Tree | Outside importers (prod) | Files | Outside spec importers |
-|---|---|---|---|
-| `avif/` | 3 lines | `shade/renderer/scene/serialization/{decode_image_source_hdr,deserialize_scene,write_image_source}.js` | 0 |
-| `basis/` | 2 files | `ktx2/ktx2_read.js`, `shade/renderer/loader/gltf/tiny-gltf.js` | 0 imports; **1 spec reading `basis/__fixtures__` by filesystem path** (`gltf_texture_basisu.spec.js`) |
-| `ktx2/` | 1 file | `shade/renderer/loader/gltf/tiny-gltf.js` | 2 (`basis/transcode_*.spec.js` read their fixtures through `ktx2_read`) |
-| `png/` | 2 files, both inside `loaders/image/` | `ImageDecoderWorker.js`, `codec/ThreadedImageDecoder.js` | 0 |
-| `jpeg/` | 0 | — | 0 |
-| `loader/gltf/` engine-free files | **5 files** | `shade/renderer/geometry/virtual/build/gltf/{gltf_open_document,gltf_collect_geometries,gltf_read_geometry}.js` + `GltfDocument.spec.js` + `engine/asset/loaders/gltf_meshopt_compression_loading.spec.js` | — |
-| `loader/gltf/` engine-facing (`load_gltf`) | 5 files | `engine/asset/loaders/GLTFSceneBundleAssetLoader.js`, four `shade/playground/*/main.js` | 1 |
-| `loader/usd/` | **0** | nothing imports `load_usd` anywhere in the repository | 0 |
-
-Outside this package: the game repository at `H:/git/moh` vendors a frozen *copy* of meep
-(`app/src/mir-engine/meep`, version 3.1.0) and its own code imports no codec path
-(`grep -rn "src/(avif|basis|ktx2)/|loaders/image/(png|jpeg)/|renderer/loader/(gltf|usd)/"` over
-`moh` excluding the vendored copy and coverage output → empty). `packages/gpu-inspector-tool` imports
-only `shade/device/timing/profile/*`. **No external importer breaks.**
-
-The migration order changes on one count: the glTF split touches the virtual-geometry builder, which
-the earlier plan did not mention, so it stays last — but for blast radius, not for "judgement about
-the seam" (Claim A settled the seam). USD having zero importers means it is a public API with no
-in-tree caller; that is not a reason to delete it (the package exports `./src/*`), but it is worth
-knowing that nothing but its own specs will exercise the move.
-
----
-
-## Hazards — the earlier list, checked, plus what it missed
-
-| Hazard | Status |
-|---|---|
-| `threaded_image_encoder.js:122` resolves `./encoder_worker.js` via `import.meta.url` | **Real.** The three encoder files move together. It is the only worker `new URL` outside `engine/physics/fluid` (`grep -rn "new URL(" --include=*.js`). |
-| `__fixtures__/` relative paths | Fixture loaders resolve relative to their own spec (`path.resolve(HERE, "__fixtures__")`) and move with them. `basis/__fixtures__/index.json` holds no paths. |
-| `rollup.config.js` | Bundles `engine/asset/loaders/image/ImageDecoderWorker.js`, which stays put; only its import of `PNGReader` changes. `tsconfig.types.json` globs `src/**`. `vitest.config.mjs` globs. `package.json#files` excludes `src/**/__fixtures__/**` by glob. |
-| specs beside sources | Moved with them. |
-| `ktx2` → `basis` edge | Legal within `format/texture/`. |
-| **Missed:** `shade/renderer/loader/gltf/gltf_texture_basisu.spec.js:24,196` reads `../../../../basis/__fixtures__/*.ktx2` by filesystem path | Breaks silently as a missing file, not an import error. Updated in step 2. |
-| **Missed:** `jsdoc_function_type_contract.spec.js` skips top-level `VENDORED = ["shade", "avif"]` | After the move `avif` is no longer top-level; the skip becomes dead. The avif tree contains zero instances of the anti-pattern (`grep` for `function(name:` inside braces → 0), so it can simply be scanned. Entry removed. |
-| **Missed:** `SHADE_ORIGIN.md` records `src/avif` "kept as a sibling so Shade's `../../../../avif/…` imports still resolve" | A note is added under the divergences. |
-| **Missed:** documentation links | `IMAGE_CODEC_REVIEW_2026_08_28.md` (~70 relative links into `avif/native`, `png/`, `jpeg/`), `COMPRESSED_TEXTURE_PLAN_2026_09_01.md` (8), `MESHOPT_COMPRESSION_PLAN.md`, `tools/geometry/virtual/README.md`, `core/color/COLOR_REVIEW_2026_08_28.md`, `avif/native/DECISIONS.md`. Rewritten with `sed` per step. `REVIEW_2026_08_06/*.md` cite absolute paths on another machine and are left as the snapshots they are. |
-| **Missed:** `usd_decode_image.js` carries a *third* PNG decoder (8-bit RGB/RGBA, fixed-Huffman only) | Not a layout matter; recorded as a follow-up below. |
-
----
-
-## The principle, as verified
-
-Unchanged in substance: sort by dependency direction. `core/binary/` below `format/`, `format/` below
-adapters, adapters beside the engine type they produce, loaders on top. Two rules:
-
-1. **A format package imports `core/`, npm packages, and the vocabulary allowlist —
-   nothing else under `engine/`, `shade/` or `view/`.** Enforced by
-   `src/format_tier_boundary.spec.js`, written in the style of `meep_three_free.spec.js`, added in
-   step 2 so every later step runs under it rather than after it.
-2. **An adapter lives beside the engine type it produces**, not beside the format it reads.
-
-## The tree, as it will be built
-
-The `image/texture/scene` grouping is kept. The task's test for it was whether it predicts the
-adapter, and it does at the level that matters — what kind of thing comes out:
-
-| Group | Decodes to | Adapter target(s) actually found |
-|---|---|---|
-| `image/` | interleaved pixel samples | `Sampler2D` (AVIF, directly; PNG via `ImageRGBADataAsset.create()`, which returns a `Sampler2D`) |
-| `texture/` | GPU-format block payloads | `ShadeTexelData` (KTX2; Basis reaches it only through KTX2) |
-| `scene/` | node graphs | `SceneBundle` (glTF), `Node3D[]` (USD — no bundle; `load_usd` returns roots) |
-
-Two of seven are loose at the *type* level (PNG's asset wrapper, USD's bare array) and none at the
-*kind* level. That is enough to justify one directory level; a flat seven would lose the fact that
-`ktx2 → basis` is a within-kind edge. Recorded so the next person does not re-derive it.
-
-```
-src/format/
-  image/avif/       ← avif/native/**      (api/ loses the two sampler files; index.js loses their exports)
-  image/png/        ← engine/asset/loaders/image/png/**  minus prototypePNG.js
-  image/jpeg/       ← engine/asset/loaders/image/jpeg/**
-  texture/basis/    ← basis/**
-  texture/ktx2/     ← ktx2/**
-  scene/gltf/       ← the engine-free glTF files listed under A3, plus ext/**, plus MESHOPT_COMPRESSION_PLAN.md
-  scene/usd/        ← the engine-free USD files listed under A3
-
-src/shade/renderer/texture/source/texel_data_from_ktx2.js      NEW — the ShadeTexelData half of ktx2_read
-src/engine/graphics/texture/sampler/avif_to_sampler2d.js       ← avif/native/api/  (names kept, see below)
-src/engine/graphics/texture/sampler/sampler2d_to_avif.js       ← avif/native/api/
-src/engine/asset/loaders/image/avif/{threaded_image_encoder,encoder_worker,encode_image_source}.js
-src/engine/asset/loaders/image/prototypePNG.js                 ← png/prototypePNG.js
-src/engine/asset/loaders/image/codec/JpegCodec.js              NEW — decision 1
-```
-
-Deviations from the proposed tree, and why:
-
-- **No `texel_data_from_basis.js`.** Nothing outside `ktx2_read` calls the transcoders with a
-  payload; `tiny-gltf` imports only their `*_formats()` lists. One adapter, one door.
-- **No `vk_format_to_texture_format.js` in `shade/renderer/texture/source/`.** It maps Vulkan format
-  numbers to WebGPU format strings using nothing but the vocabulary allowlist. It is KTX2 knowledge and
-  stays in `format/texture/ktx2/`. Moving it would have been the earlier session's rule 1 forcing a file
-  uphill for want of the refinement in A4.
-- **The AVIF sampler pair keeps its file and function names** (`avif_to_sampler2d`,
-  `sampler2d_to_avif`) rather than becoming `sampler2d_from_avif`. Three consumers, a decision log
-  (D32) and a plan document name them; the destination directory is not uniformly prefixed
-  (`downloadSamplerAsPNG.js`, `HarmonicDiffusionGrid.js`); and a rename is not what this refactor is for.
-- **`avif/index.js` is deleted, `avif/native/index.js` becomes `format/image/avif/index.js`.**
-  Neither has an importer. The outer one re-exported the worker pool alongside the codec, which is
-  the tier mix this refactor exists to undo; its `decode`/`encode` aliases for the old WebAssembly
-  names have no caller.
-- **`UsdExtensionRegistry.js` stays with `usd_build_scene`.** Import-free, but its whole contract is
-  "return a `Node3D`", and it is consulted from the builder. Dependency direction is the rule; where
-  a file has none, the type its contract names decides.
-- **The encoder pool lands in `engine/asset/loaders/image/avif/` with a caveat.** It encodes, and
-  "loaders" is the wrong verb. It goes there anyway because its decode-direction sibling
-  (`codec/ThreadedImageDecoder.js`, also a worker pool) already lives one directory over, and one
-  place for "image codec worker pools" beats a new top-level directory for three files.
-
-## Decision 1 — JPEG: **move it and wire it, as the last fallback**
-
-The 2026-08-28 review (item C1) recommended registering it behind `Codec`, and its item C4 was then
-*done* — `getData` was rewritten around `jpeg_component_row.js` a week ago, with byte-for-byte
-verification against the old output. Deleting a decoder somebody just finished refactoring, with
-three passing spec files, would be the wrong reading of "dead". It is unreachable, not unwanted.
-
-What "wire it" means here is constrained by one fact: in a browser, `NativeImageDecoder` decodes
-JPEG with the platform's own decoder, and a pure-JavaScript decoder on the main thread is slower and
-blocks. So `JpegCodec` goes **after** `NativeImageDecoder` in `ImageRGBADataLoader`'s chain —
-`[ThreadedImageDecoder, NativeImageDecoder, JpegCodec]`. `NativeImageDecoder.test` claims everything
-(it inherits the base class's `return true`), so in a browser nothing changes; where there is no
-`Image` — node, a worker — the native decoder throws, `CodecWithFallback` moves on, and JPEG becomes
-loadable for the first time. Zero behaviour change where it already worked; a working decoder where
-it did not. Teaching `ImageDecoderWorker` to decode JPEG off the main thread is the version with a
-real payoff for the browser, and it is a measured trade (a JS decoder in a worker versus the
-platform's on the main thread), so it is a follow-up rather than a side effect of a layout change.
-
-## Decision 2 — how far the skins are cut
-
-| Skin | Verdict | What is done |
-|---|---|---|
-| `ktx2_read.js` | extraction | plain record out; per-level byte check moves in; "1 or full chain" moves to the adapter with its two tests |
-| `transcode_basis.js`, `transcode_uastc.js` | extraction | plain record out; `TextureFormat` stays via allowlist |
-| `avif_to_sampler2d.js` | already separate | relocated |
-| glTF, USD | file moves only | the seam is a file boundary already |
-| `tiny-gltf.js` | left as is | it *is* the loader; it imports the adapter |
-| `usd_decode_image.js` | left as is, then taken as a follow-up | duplicate PNG decoder, since replaced by `PNGReader` + the adapter |
-| `UsdExtensionRegistry.js` | left with the builder | see above |
-
-## Migration order, resequenced
-
-Each step: `git mv`, fix imports, run the suite, commit with `--only`.
-
-0. This document.
-1. ~~Delete `engine/asset/loaders/gltf/`~~ — already gone (`a10895194`).
-2. `format/texture/` — Basis and KTX2; the `ShadeTexelData` cut; the adapter; the structural spec;
-   `gltf_texture_basisu.spec.js` fixture path; `tiny-gltf` import.
-3. `format/image/avif/` — plus the sampler pair to `engine/graphics/texture/sampler/`, the encoder
-   trio to `engine/asset/loaders/image/avif/`, the jsdoc spec's vendored list, `SHADE_ORIGIN.md`.
-4. `format/image/{png,jpeg}/` — plus `prototypePNG.js` up a level, `JpegCodec`, the two PNG doors.
-5. `format/scene/{gltf,usd}/` — plus the virtual-geometry builder's five imports and the tools README.
-
-Step 6 (the structural spec) is folded into step 2 so it guards steps 3–5 as they land.
-
-## As executed
-
-Six commits on `master`, each green on the full suite (2227 → 2230 spec files; 15393 → 15401 tests —
-the adapter spec, the JPEG codec spec, the loader chain tests and the boundary spec are the additions).
-The plan above held. What execution added:
-
-- **Moves went file by file, not by directory.** A directory rename under `src/` was refused with
-  "Permission denied": two vite dev servers and an IDE hold watcher handles on the tree, and Windows
-  will not rename a directory with an open handle. Moving the files out of it is not blocked, so the
-  move tool does that and removes the emptied directories afterwards. History follows the files
-  either way (`git log --follow`).
-- **Imports and markdown links were rewritten by resolution, not substitution.** Every relative
-  specifier — `import … from`, `export … from`, `import()`, `new URL(…, import.meta.url)`, and
-  `](…)` links with `#L` anchors or `:line` suffixes — was resolved against the file's old location,
-  mapped through the move, and re-expressed from the new one. Only specifiers whose target or whose
-  own file moved were touched. Paths in *prose* (backticked, not linked) were updated by hand where
-  they name a live file; recipes of the form `git checkout <sha> -- src/avif/native/…` were left, since
-  they name a path at that commit.
-- **Some working-copy files are CRLF** (`core.autocrlf=true`; `jsdoc_function_type_contract.spec.js`
-  was one). Edit scripts that match multi-line blocks have to match `\r?\n` and write the file's own
-  ending back.
-- **The rollup worker bundle was built** after step 4 (`npx rollup -c`) to prove
-  `ImageDecoderWorker.js` still resolves `PNGReader` from `format/image/png/`; it does, and the output
-  was removed again (`build/` is gitignored).
-- **`Base64.decode` returns an `ArrayBuffer`**, which the codec `test()` contracts do not accept;
-  the two new JPEG specs wrap it in a `Uint8Array`.
-
-Final shape, as committed:
-
-```
-src/format/
-  image/avif/   api/ av1/ bitstream/ color/ heif/ isobmff/ __fixtures__/ index.js DECISIONS.md NOTICE.md
-  image/png/    PNG.js PNGReader.js PNG_HEADER_BYTES.js chunk/ filter/ crc32.js png_inflate.js png_unpack_samples.js
-  image/jpeg/   JpegImage.js jpeg_decode.js jpeg_component_row.js … NOTES.md
-  texture/      TexelPayload.js
-  texture/basis/  etc1s/ uastc/ transcode/ BasisBitReader.js BasisHuffmanTable.js transcode_basis.js transcode_uastc.js __fixtures__/
-  texture/ktx2/   ktx2_read.js ktx2_read_basis_lz_global_data.js vk_format_to_texture_format.js KhrDfModel.js SupercompressionScheme.js __fixtures__/
-  scene/gltf/   gltf_parse_container.js gltf_read_accessor.js gltf_component_type.js GLTF_PRIMITIVE_MODE.js
-                gltf_used_image_indices.js coalesce_array_duplicates.js gltf_node_world_matrices.js ext/ MESHOPT_COMPRESSION_PLAN.md
-  scene/usd/    parse_usda.js usd_triangulate.js usd_lz4.js unpack_usdz.js UsdError.js usd_compose_transform.js
-
-src/shade/renderer/texture/source/texel_data_from_ktx2.js       KTX2 → ShadeTexelData
-src/engine/graphics/texture/sampler/{avif_to_sampler2d,sampler2d_to_avif}.js   AVIF ↔ Sampler2D
-src/engine/asset/loaders/image/avif/                            encoder worker pool
-src/engine/asset/loaders/image/codec/JpegCodec.js               JPEG behind Codec, last in the chain
-src/engine/asset/loaders/image/prototypePNG.js                  dev harness, up one level
-src/shade/renderer/loader/{gltf,usd}/                           scene builders, unchanged in role
-src/format_tier_boundary.spec.js                                the rule
-```
-
-## Follow-ups this refactor surfaced, and where they stand
-
-- **`ImageDecoderWorker` learning JPEG — measured and declined** (2026-09-02). On 1024×1024 Sponza
-  textures the platform decoder takes 6–11 ms wall with about 1.5 ms of that on the main thread; the
-  in-tree decoder takes 128–178 ms wherever it runs, and a worker saves only the 1.5 ms. Fifteen to
-  twenty times the latency for a read-back's worth of main-thread time is the wrong trade for a
-  loader. The bench and its numbers are `shade/playground/image_decode_bench/`; `ThreadedImageDecoder`
-  says why it sniffs PNG only. JPEG and AVIF reach the in-tree decoders only where no browser decoder
-  exists.
-- **`usd_decode_image.js`'s private PNG decoder — taken, 2026-09-02** (separate session): `decode_png`
-  now calls `PNGReader` and widens whatever it returns to RGBA8; the private inflate and its "Dynamic
-  Huffman blocks not supported" throw are gone. The adapter stays with the loader. Spec beside it.
-- **The rest of review item C1 — done** (2026-09-02): `engine/asset/codec/DecodedImage.js` is the one
-  result shape; `AvifCodec` sits last in the chain beside `JpegCodec`; `guessAssetType` maps `.avif`
-  to `"image"`. The codec wraps `avif_to_sampler2d`, not the reverse — the adapter owns the HDR path
-  and the reusable decoder context, and an 8-bit asset codec wants neither.
-- **KTX2 arrays and cube maps — the reader returns them** (2026-09-02). `TexelPayload` carries
-  `layers` and `faces`, a level holds `layers * faces` images in KTX2's order, and the byte check
-  accounts for them. `texel_data_from_ktx2` refuses layers and faces by name until `ShadeTexelData`
-  grows a layer, and is the only place that changes when it does. The format tier still refuses a 3D
-  array (no GPU API has one) and a Basis payload with layers (the transcoders take one image per
-  level).
-- **A USD asset loader** — `load_usd` had no in-tree caller. A loader beside
-  `GLTFSceneBundleAssetLoader`, with `guessAssetType` entries for the USD extensions, was spun off as
-  its own task.
-- **Open:** `NativeImageDecoder.test` returns true for any bytes. A sniff (`PNG`, `0xFFD8`, `ftyp`)
-  would let the chain be ordered by capability rather than by "the browser will probably manage".

package/src/CORRECTNESS_HUNT_2026_07_24.md

@@ -1,142 +0,0 @@
-# Engine correctness bug hunt — 2026-07-24
-
-A targeted correctness sweep of the `meep` engine (`app/src/mir-engine/meep/src/`).
-Targets chosen from **architecture** (foundational / wide-blast-radius code) and **git commit
-history** (recently-landed, thinly-reviewed code). Method: multi-agent finder → adversarial
-verifier; every confirmed defect is pinned with a *failing* test before it is fixed.
-
-## Ground rules
-
-- **Fix only what is provably wrong**, and only after a red test reproduces it. Everything
-  uncertain is written up here rather than "fixed".
-- Black-box tests only — assert on observable behaviour, never on call counts / private paths.
-- No defensive guards for can't-happen conditions; no silent `try/catch`; correctness over bandaids.
-- `assert.*` is stripped in prod — do not test assert-rejections; real `throw` is testable.
-- Keep performance characteristics intact — a correctness fix must not regress the hot path.
-- Tests run from `H:/git/moh` via `node_modules/.bin/jest --config jest.conf.json <pattern>`.
-
-## What is already covered (do not re-litigate)
-
-Per prior review memory, these were swept recently and validated clean or fixed:
-- **Physics core** + reactive (14-bug sweep, 2026-07) — determinism gate green.
-- **Sound / acoustic** simulator + render (Sopra / Steam-Audio-gap work).
-- **Network** core (GNS review) — P0s catalogued separately.
-- **engine review 2026-07-03** — physics/sound/network CLEAN; defects concentrated in
-  ECS lifecycle + graphics bindings + serialization.
-- BVH2/8, clustered-lighting froxel geometry, path tracer, LPG stage correctness, EPA/GJK,
-  fluid MAC, navmesh simplify — each has a standing spec gate.
-
-The hunt therefore targets **the delta since those reviews** and **areas with thin spec coverage**.
-
-## Target map
-
-Tier 1 — recently landed (git history hot spots):
-- Gamepad input subsystem (`engine/input/devices/gamepad/*`, `GamepadDevice.js`)
-- Fog-of-war screen-space shader (`engine/ecs/fow/shader/*`)
-- Trail3D + tube geometry (`engine/graphics/ecs/trail3d/*`, `engine/graphics/trail/tube/*`)
-- Forward+ clustered light live updates (`engine/graphics/ecs/light/*`)
-- HUD edge-stick badge placement (`engine/ecs/gui/hud/*`)
-- Physics delta of the 14-bug sweep (adversarial check of changed files only)
-
-Tier 2 — foundational, wide blast radius (architecture):
-- `core/math/linalg`, `core/math/spline`, `core/math/statistics|random|noise`
-- `core/geom` transforms & primitives (Vector*, Quaternion, AABB, Matrix)
-- `core/collection` data structures
-
-Tier 3 — thin spec coverage:
-- `engine/animation` (16 specs / 83 src) — clip/curve binding, skinning
-- `engine/intelligence` (26 / 71) — behavior trees, blackboard, MCTS
-- `engine/navigation` (14 / 20) — pathfinding, path following
-- `engine/interpolation` (5 / 8) — interp snap was a deferred item
-- `engine/ecs` lifecycle (defects concentrate here per memory)
-- `engine/asset` loaders + serialization
-
-## Hand-verified clean (independent of the agent sweep)
-
-These were read and checked directly (some with a throwaway empirical harness); no defect found:
-
-- **Gamepad stick calibration** (`GamepadStickCalibrator`, `GamepadStick`, `GamepadStickCalibration`,
-  `apply_radial_dead_zone`, `gamepad_write_dpad_vector`) — robust median/MAD learning, self-correcting
-  accepted-magnitude gate, continuous radial dead zone, correct D-pad vector. 22 passing tests.
-- **Tube parallel-transport frame** (`tube_frame_transport` + `v3_orthonormal_matrix_from_normal`) — the
-  degenerate bootstrap correctly takes the perpendicular rows (util stores the input at rows 6..8), so N⊥T.
-- **Quaternion slerp** (`slerpQuaternions`) — correct shortest-path sign flip + lerp fallback near-parallel.
-- **Cubic animation curve** (`spline3_hermite`, `evaluate_two_key_curve`, `AnimationCurve.getKeyIndexLow`) —
-  canonical Hermite basis; tangents scaled by segment dt; binary search boundaries correct.
-- **core/color** — empirical 200k-sample round-trip harness: YCoCg exact, YCbCr ≤1 LSB, HSV ~1e-16,
-  OkLab ~1e-7, RGBE9995 matches the standard RGB9E5 algorithm exactly (the large minor-channel relative
-  error is inherent shared-exponent quantization, not a bug). No defect.
-
-## Findings
-
-The 23-area finder→adversarial-verifier sweep produced 26 candidate findings; 7 were rejected on
-verification, **18 confirmed** (real bug · reachable · node-testable), and **1 uncertain** (real logic
-defect but effectively unreachable on the shipped path — see below). Each confirmed item below was
-re-checked against source and pinned with a *failing* test before fixing.
-
-### Confirmed & fixed (test-first)
-
-| # | Severity | Area | File | Bug | Status |
-|---|----------|------|------|-----|--------|
-| 1 | high | statistics | `core/math/statistics/gaussian_amplitude.js` | Squared the variance in the exponent (passed `variance` to `gaussian()`, which squares its arg) → PDF ~45% off for any variance≠1 | ✅ fixed |
-| 2 | med | statistics | `core/math/statistics/computeStatisticalMean.js` | Loop started at `0` not `start`, but divided by `end-start` → wrong mean for any non-zero start | ✅ fixed |
-| 3 | med | linalg | `core/geom/Quaternion.js` (×3: XYZ/YXZ/ZYX) | `Math.asin` unclamped → **NaN at gimbal lock** (fp overshoot past 1). Hits `copy_transform_to_threejs_object` + first-person yaw seed | ✅ fixed |
-| 4 | med | geom | `core/geom/ConicRay.js` | `sampleRandomDirection` NaN for a cone axis of exactly `(0,0,-1)` (k=1/(1+dZ) singular at the antipode) | ✅ fixed |
-| 5 | low | geom | `core/geom/2d/line/line2_compute_segment_point_distance_sqr.js` | Zero-length segment → `clamp01(0/0)=NaN` (3D twin already guards this) | ✅ fixed |
-| 6 | med | collection | `core/collection/RingBuffer.js` `getHead()` | Returns `undefined` when head wraps to slot 0 on a full buffer (no wrap, unlike `getFromHead`) | ✅ fixed |
-| 7 | med | collection | `core/collection/RingBuffer.js` `contains()` | Scans whole backing array → reports `true` for `shift()`-ed-out elements | ✅ fixed |
-| 8 | low | binary | `engine/ecs/storage/binary/collection/BinaryCollectionDeSerializer.js` | Signed `>>2` corrupts a 32-bit dict back-ref offset ≥2²⁹ (should be `>>>2`) | ✅ fixed |
-| 9 | low | binary | `core/binary/EncodingBinaryBuffer.js` | Signed `>>1` corrupts interned-string back-ref ≥2³⁰ (should be `>>>1`) | ✅ fixed |
-| 10 | low | binary | `core/binary/BinaryBuffer.js` `writeASCIIString` | Boundary `> 0x80` lets non-ASCII U+0080 pass validation (should be `> 0x7F`) | ✅ fixed |
-| 11 | high | ecs | `engine/ecs/EntityComponentDataset.js` `traverseEntities` | Uses **module-shared scratch arrays** → nested traversal corrupts the outer loop (wrong-type component delivered) | ✅ fixed |
-| 12 | high | navigation | `engine/navigation/ecs/path_following/PathFollowingSystem.js` | `next_offset > path_length` (should be `>=`) → non-looping follower snaps to start & never finishes when a step lands exactly on the end | ✅ fixed |
-| 13 | med | navigation | `engine/navigation/ecs/components/Path.js` | `sample_linear`/`sample_catmull_rom` return `(t<0 && …)` — always false for valid offsets → `estimatePathViaIterativeIntegral` returns 0 | ✅ fixed |
-| 14 | med | input | `engine/input/ecs/systems/InputControllerSystem.js` | `link()/unlink()` ignore `enabled` → binding double-registration → double input dispatch after a disable/enable round-trip | ✅ fixed |
-| 15 | med | graphics | `engine/graphics/trail/tube/TubeX.js` | `rotate()` writes recycled segment with reversed winding → lit tubes shaded from the wrong side | ✅ fixed |
-| 16 | med | graphics | `engine/graphics/render/forward_plus/LightManager.js` | Reused sorted-lights array never shrinks → stale light records re-uploaded to the light-data texture every frame | ✅ fixed |
-| 17 | med | animation | `engine/animation/clip/ecd_bind_animation_curve.js` (fix) | LINEAR quaternion tracks nlerp'd component-wise with no hemisphere alignment → long-way rotation on `dot<0` key pairs | ✅ fixed |
-| 18 | low | fow | `engine/ecs/fow/FogOfWar.js` `conceal()` | No dedup guard (unlike `reveal()`) → conflicting fade rows on one cell | 📝 documented (see below) |
-
-19 confirmed defects were addressed test-first (18 from the sweep + the one below that the verifier
-had flagged as "uncertain"). Each fix landed in its subsystem commit with a red-before-green test.
-`#3` clamps all three Euler extractors; `#11` also removes the now-dead scratch pools; `#13` fixes both
-`Path.sample` and its consumer `estimatePathViaIterativeIntegral`.
-
-### Also fixed (verifier had marked "uncertain")
-
-- **`engine/animation/keyed2/AnimationTrackPlayback.js` — `on.ended` never fired when a frame landed
-  exactly on `timeEnd`.** Genuine logic defect: the strict `> __nextKeyTime` guard skips the exact-landing
-  frame, and the next frame fails the `position < timeEnd` guard, so the one-shot `ended` never dispatched.
-  Fixed by adding `|| newPosition >= timeEnd` to the outer guard (mid-track exact landings never reach
-  `timeEnd`, so they are unaffected; fire-once preserved). **Reachability caveat, recorded for the owner:**
-  the only in-engine driver (`ScriptSystem`, variable-rate float time) makes an exact landing a measure-zero
-  event, so this hardens the public primitive rather than fixing an observed in-game leak.
-
-### Not auto-fixed — owner decision required
-
-- **`#18` `FogOfWar.conceal()` missing dedup.** `reveal()` is idempotent (it guards on `samplerData === 255`
-  and immediately moves the cell off that state). `conceal()` guards only `value !== 255` and does **not**
-  move the cell, so a second `conceal` — or a `conceal` while the cell is mid-`reveal` — stacks a second,
-  opposing fade row on the same cell; the two rows then fight and the final visibility is decided by fade
-  timing, not by the last command (plus a one-frame flicker). **Why deferred:** (1) no in-engine caller uses
-  `conceal()` (`FogOfWarRevealerSystem` only reveals), so it is public-API-only, LOW severity; (2) the
-  *correct* conflict semantics are a design choice (should `conceal` cancel an in-progress `reveal`, or be
-  ignored?); and (3) an efficient "one fade row per cell" guard needs a cell→row index that `RowFirstTable`
-  does not provide — a naive per-cell scan of `fadeMask` is `O(rows·cells)` and could be costly for large
-  concealed regions. **Recommended fix:** enforce "at most one fade row per cell, latest command wins" by
-  updating an existing row's `speed`/target in place instead of adding, backed by a cell→row map.
-
-### Follow-up noted (not a regression)
-
-- **`#17` CubicTangents quaternion tracks.** The hemisphere-alignment fix covers LINEAR tracks (glTF's
-  default). GLTF cubic-spline (`CubicTangents`) quaternion tracks pack in/out tangents per key and would need
-  those tangents negated alongside the value; left as a follow-up.
-
-### Pre-existing failures (NOT caused by this sweep)
-
-- `engine/control/first-person/WallRunScenarios.spec.js` has 4 failing "unhappy path" tests. Confirmed
-  pre-existing by re-running the suite against the original `Quaternion.js` (identical 4 failures). The
-  commit that added them ("WallRun scenarios + 3 gaps they surfaced") marks them as gap-documenting tests
-  for unimplemented behaviour. Out of scope here.
-
-Full suite after the sweep: **8846 passed, 4 failed (the pre-existing WallRun gaps), 118 skipped.**