@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/formats/provenance.md

@@ -1,196 +1,196 @@
-# Format ownership and fork provenance
-
-Status: Stable  
-Scope: `@carbonenginejs/runtime-resource/formats`  
-Audience: Users, integrators, and maintainers  
-Summary: Records where each format implementation came from, retained snapshots and digests, and what was deliberately not copied.
-
-On 2026-07-13, the non-shader runtime format implementations below were copied
-once into `runtime-resource`. The table records the donor revisions or
-working-tree states used for that migration; it does not assert that a
-standalone repository still exists. Any surviving standalone repository is
-historical provenance, not an upstream for the runtime copy.
-
-Copied paths were `src/` and the behavioral `test/` corpus. Package publishing
-scripts and CLIs were not copied. Exact donor license and notice files are kept
-under `format-notices/<format>/`.
-
-| Legacy package | Source revision/state | Runtime class | Runtime import |
-|---|---|---|---|
-| `format-black` | `9fcaaff9e5f28c90b628d8a10b7c79aff7913a90` | `CjsBlackFormat` | `@carbonenginejs/runtime-resource/formats/black` |
-| `format-cmf` | unborn working-tree snapshot | `CjsCmfFormat` | `@carbonenginejs/runtime-resource/formats/cmf` |
-| `format-dds` | `66fa149cd826e1114ad0be84479f89dee753ed76` | `CjsDdsFormat` | `@carbonenginejs/runtime-resource/formats/dds` |
-| `format-dxbc` | `3790bda40d7d0d3b774eeb4d82a13827dbe332df` | `CjsDxbcFormat` | `@carbonenginejs/runtime-resource/formats/dxbc` |
-| `format-hlsl` | `e494203f3a1e10866fbe148b460297045cd959ed` | `CjsHlslFormat` | `@carbonenginejs/runtime-resource/formats/hlsl` |
-| `format-webgl` | `428bc141d090b7416745ea43bf3fc320b9e99b43` | `CjsWebglFormat` | `@carbonenginejs/runtime-resource/formats/webgl` |
-| `format-webgpu` | `ffabae8c6a6c658f30807582300aa97522964ee7` | `CjsWebgpuFormat` | `@carbonenginejs/runtime-resource/formats/webgpu` |
-| `format-fbx` | `8d0fcc2fe44c8096b35e360a903bff30b49eb592` | `CjsFbxFormat` | `@carbonenginejs/runtime-resource/formats/fbx` |
-| `format-flac` | unborn working-tree snapshot | `CjsFlacFormat` | `@carbonenginejs/runtime-resource/formats/flac` |
-| `format-gif` | `5d831c5c0533a9579682f776274574289a520899` | `CjsGifFormat` | `@carbonenginejs/runtime-resource/formats/gif` |
-| `format-gltf` | `d0dadf920828bceec987c2a5fa1f161f81db28aa` | `CjsGltfFormat` | `@carbonenginejs/runtime-resource/formats/gltf` |
-| `format-jpeg` | `bed2253ea979bba27812420fa897987d82a91793` | `CjsJpegFormat` | `@carbonenginejs/runtime-resource/formats/jpeg` |
-| `format-mp3` | unborn working-tree snapshot | `CjsMp3Format` | `@carbonenginejs/runtime-resource/formats/mp3` |
-| `format-mp4` | `cffc5a57b115a99ed9e0947a6b9d3390ffc3581c` | `CjsMp4Format` | `@carbonenginejs/runtime-resource/formats/mp4` |
-| `format-obj` | `e5d3f9a1520c7855bd5b6edc1e2304a7b4e18176` | `CjsObjFormat` | `@carbonenginejs/runtime-resource/formats/obj` |
-| `format-ogg` | unborn working-tree snapshot | `CjsOggFormat` | `@carbonenginejs/runtime-resource/formats/ogg` |
-| `format-png` | `04dbb7c0f289043c3c32d9141ec3ef74aeeb1c43` | `CjsPngFormat` | `@carbonenginejs/runtime-resource/formats/png` |
-| `format-red` | `98beab6988111418d6e09827b92d27e08da4c05b` | `CjsRedFormat` | `@carbonenginejs/runtime-resource/formats/red` |
-| `format-stl` | `4858f9a37bf140a3c544fa30a13a6fcce015247b` | `CjsStlFormat` | `@carbonenginejs/runtime-resource/formats/stl` |
-| `format-tga` | `b0f9df263727057537b2279322e8cd088f366179` | `CjsTgaFormat` | `@carbonenginejs/runtime-resource/formats/tga` |
-| `format-wav` | unborn working-tree snapshot | `CjsWavFormat` | `@carbonenginejs/runtime-resource/formats/wav` |
-| `format-webm` | `459203ac293d0d53fff0e43494b7e47d8d4c92bd` | `CjsWebmFormat` | `@carbonenginejs/runtime-resource/formats/webm` |
-| `format-webp` | `19155e9cc7ae05845c23a3c259d3a586569eba40` | `CjsWebpFormat` | `@carbonenginejs/runtime-resource/formats/webp` |
-| `format-yaml` | `3d7e1d1cf9b7a936283d6050efe43a0a9fadb6a4` | `CjsYamlFormat` | `@carbonenginejs/runtime-resource/formats/yaml` |
-
-The unborn donors had no commit-addressable `HEAD`; this document deliberately
-records them as working-tree snapshots rather than inventing a revision. Their
-copied runtime files are the deterministic retained snapshot.
-
-On 2026-07-24, following `format-gr2`'s MIT relicense (its EUPL-derived
-BitKnit decoder was replaced by a clean-room implementation written from the
-published specification in that package's `docs/formats/bitknit2.md`), the
-GR2/GSF reader joined the runtime copies:
-
-| Legacy package | Source revision/state | Runtime class | Runtime import |
-|---|---|---|---|
-| `format-gr2` | `fa64607de7a3a96ed3b1aec5288bf71057642043` (v0.2.0, MIT) | `CjsGr2Format` | `@carbonenginejs/runtime-resource/formats/gr2` |
-
-The donor engine was folded into the single public `CjsGr2Format` class, so
-the copied `CjsFormatGr2` name is gone and `formats/gr2/core/` holds only
-role-named helper modules, matching every other format. Donor license and
-notice files are kept under `format-notices/gr2/`.
-
-## Black definition snapshot
-
-The Black reader uses the package-owned generated definition snapshot at
-`src/formats/black/core/black-schema-v1-2026-07-23.json`. The Red format exposes
-the same catalog for discovery, but its YAML reader currently accepts named
-fields without registry enforcement. The refreshed consumer snapshot landed
-in runtime-resource revision `6beda70` with SHA-256
-`9234DD86DBB5EB3676EF060E383ADBCE8F073941E76A32865D3528DD5DA7B737`.
-Its exact tools-core generator revision was not recorded and remains unknown;
-this page does not infer one from the consumer commit.
-
-This retained generated artifact keeps the published readers deterministic and
-browser-safe without a runtime dependency on a sibling checkout or an
-unpublished generator export. Future schema generation is owned by
-`tools-core/schema`. A consumer of generated output is responsible for
-reviewing and copying the result into its own worktree; an updated snapshot
-must record the generator revision and new digest here.
-
-This generator boundary is transitional. As runtime classes gain embedded
-schema, the shared snapshot and its copy-in step can be reduced and eventually
-removed once every required class is self-describing.
-
-## Native additions
-
-Formats below were authored directly in `runtime-resource` and have no legacy
-donor package. Their `format-notices/<format>/` entries record third-party
-format attribution rather than fork provenance.
-
-| Format | Runtime class | Runtime import | Notes |
-|---|---|---|---|
-| Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` | Original code; chunk layout from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Also carries the SoundbanksInfo JSON helpers (`parseSoundbanksInfo`, `buildSoundbanksCatalog`, `joinSoundbanksInfo`) and `wwiseIdFromName` (FNV-1 32 of the lowercased name, verified against EVE bank/language ids). HIRC entries additionally decode version-stable typed fields (event action lists, action type/target, sound and music-track source ids), pinned by hexdump against bank generator version 150, and the `wwise` static namespace groups the domain toolkit (SoundbanksInfo helpers, id hash, `wwise.eventMediaFromBanks` event → media resolution over inspected banks — graph interpretation for consumers; never used by the resource lifecycle). |
-| Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` | Original code; container/codec-tag behavior from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Includes a Wwise-Vorbis→Ogg repacker (`emit: "ogg"`), an original reimplementation of the ww2ogg algorithm with inline granule computation (no revorb pass needed), and a PTADPCM/16-bit-PCM decoder (`emit: "pcm"` / `toPcm()`, AudioBuffer-ready float32; PTADPCM algorithm from community documentation, verified against EVE media). |
-
-The BNK toolkit also exposes `wwise.sfxNodesFromBanks`: typed, exact-end
-version-150 Random/Sequence, Switch/State, and Layer tails plus event/action
-records and explicit parser diagnostics. It preserves resource facts for
-consumer-owned lowering and is never invoked by the resource lifecycle.
-
-## Post-fork additions inside copied formats
-
-- `formats/dds` gained original, dependency-free **BC6H and BC7 CPU decoders**
-  in `runtime-resource` 0.8.0 (2026-07-21). BC6H covers all fourteen modes,
-  signed and unsigned HDR, transformed endpoints, partition/anchor fixups,
-  interpolation, reserved opaque-black modes, and float RGBA output. BC7 covers
-  all eight modes,
-  two- and three-subset partitions, anchor fixups, P-bits, dual index streams,
-  channel rotation, edge blocks, and the reserved transparent mode. Fixed bit
-  layouts and tables follow the Khronos Data Format Specification and Microsoft
-  BC6H/BC7 documentation. Tests cover every mode and signed/unsigned fixtures;
-  BC7 was also checked against randomized valid-mode blocks and both decoders
-  were exercised on real EVE textures acquired through `tools-core`.
-- `formats/stl` received a writer hardening pass (2026-07-18) without changing
-  its donor origin: binary provenance headers now round-trip the caller's solid
-  name, shared triangle indices are validated as in-range safe integers, scaled
-  coordinates must remain finite, and binary coordinates must fit float32
-  instead of silently becoming infinities. Writer JSDoc and ASCII/binary
-  round-trip/error coverage were expanded in the runtime-owned copy.
-- `formats/cmf` gained a **binary CMF v1 writer** (2026-07-15,
-  `src/formats/cmf/core/writer.js`, `CjsCmfFormat.write`/`writeAsync` and
-  `Write`/`WriteAsync`): original code implementing CarbonEngine's
-  `cmf::BuildFile` behavior — tagged self-relative span flattening with leaf
-  chunk dedup, BufferView→section remapping in first-encounter order,
-  meshoptimizer vertex/index compression (index compression canonicalizes
-  triangle rotation, matching the engine's own writer test expectations), and
-  the post-crc32 file checksum. Verified by write→read roundtrips against the
-  runtime reader; CarbonEngine's `mesh` CMF sources were the behavioral
-  reference, no code copied. `writeShared`/`writeSharedAsync` plus
-  `core/pack.js` (channel interleaving, index packing, unique buffer-index
-  assignment) serialize shared geometry directly, enabling GR2/OBJ/glTF→CMF —
-  verified against real EVE `.gr2` models fetched via
-  `@carbonenginejs/tool-index` (positions exact, triangles equivalent).
-- `formats/cmf` also gained the **GR2 skeleton/animation converter**
-  (2026-07-15, `src/formats/cmf/core/gr2Anim.js`, applied automatically by
-  `writeShared`): GR2-shaped skeletons (root list or `models[].skeleton`)
-  convert to CMF bones/parents/rest transforms with inverse binds rebuilt
-  from the rest hierarchy; decoded Granny curves convert to CMF Step/Linear
-  channels — degree ≤ 1 exactly, degree 2 via adaptive de Boor resampling
-  with discontinuities snapped to one float32 ULP. Consumes only decoded
-  `{knots, controls}` data so the MIT runtime stays independent of the GR2
-  package. Validated on EVE ships (cde3_t3, gde3_t3, cfaux1_t1, mfaux1_t1:
-  3,377 channels ≤ 8.3e-4 positional / ≤ 0.14° rotational vs the GR2 runtime
-  sampler; 9 Granny curve formats) and characters (basicfemale: 132-bone
-  skeleton, exact skin weights).
-- `formats/ogg` gained a pure-JS **Ogg Vorbis PCM decoder** (2026-07-15,
-  `src/formats/ogg/core/{vorbis.js,imdct.js}`, `emit: "pcm"`/`"audio"`):
-  original code implementing the Vorbis I specification (floor 1, residues
-  0/1/2, square-polar coupling, FFT-based IMDCT, windowed overlap-add).
-  stb_vorbis (public domain) was consulted as a behavioral reference and is
-  the source of the spec's floor1 `inverse_db_table` constants; no licensed
-  code was copied. Validated bit-comparable to ffmpeg (max diff ~3e-8) and
-  vgmstream (±1 int16 LSB) across the EVE Vorbis corpus.
-
-## Wem packed-codebook snapshot
-
-The wem Ogg repacker ships a package-owned copy of the aoTuV 6.03 packed
-Vorbis codebook library at
-`src/formats/wem/core/packedCodebooksAotuv603.js` (base64 module). It was
-copied byte-identically from `packed_codebooks_aoTuV_603.bin` in the ww2ogg
-distribution (`github.com/hcs64/ww2ogg`), 74,387 bytes, SHA-256
-`00a93eab267d281401b1efd54e888a2e183299b9e6c446c48d09f701a89d9d27`, retrieved
-2026-07-15. The data is BSD-licensed (Xiph.org Foundation, Adam Gashlin);
-attribution and the full license terms are recorded in
-`format-notices/wem/NOTICE` and `format-notices/wem/LICENSE`. An updated
-snapshot must record its new source and digest here.
-
-## Deliberately not copied
-
-- `format-gr2` migrated into `formats/gr2` on 2026-07-24 (see the dated
-  table above) after its EUPL constraint was resolved; its standalone
-  repository is now a frozen legacy distribution like the other donors.
-- `format-carbon` is historical provenance for the current copied snapshot,
-  not the authority for future regeneration. `tools-core/schema` owns schema
-  generation, while each consuming package reviews and copies generated output
-  into its own worktree. Black consumes the retained snapshot; Red exposes the
-  copied catalog but does not yet enforce it while reading YAML fields.
-- The shader formats were excluded from the original migration while their
-  implementations were still being finished. That sequencing guard was lifted
-  on 2026-07-29 and they moved in as ordinary formats. All four landed:
-  `formats/dxbc`, `formats/hlsl`, `formats/webgl`, and `formats/webgpu`. Their
-  standalone repositories remain in place, unmodified by the move. Their
-  local-only test fixtures are game-derived and were deliberately not copied;
-  the suites that need them skip with an explicit reason.
-
-## Typed-array ownership adjustments
-
-The runtime copies preserve caller byte objects by reference. During the fork,
-three avoidable source-buffer copies were changed to views:
-
-- CMF compressed sections use `Uint8Array.subarray`.
-- glTF GLB chunks use `Uint8Array.subarray`.
-- FBX raw binary property payloads use `Uint8Array.subarray`.
-
-Decoder output buffers and GIF per-frame snapshots still allocate because those
-values have independent semantic identity.
+# Format ownership and fork provenance
+
+Status: Stable  
+Scope: `@carbonenginejs/runtime-resource/formats`  
+Audience: Users, integrators, and maintainers  
+Summary: Records where each format implementation came from, retained snapshots and digests, and what was deliberately not copied.
+
+On 2026-07-13, the non-shader runtime format implementations below were copied
+once into `runtime-resource`. The table records the donor revisions or
+working-tree states used for that migration; it does not assert that a
+standalone repository still exists. Any surviving standalone repository is
+historical provenance, not an upstream for the runtime copy.
+
+Copied paths were `src/` and the behavioral `test/` corpus. Package publishing
+scripts and CLIs were not copied. Exact donor license and notice files are kept
+under `format-notices/<format>/`.
+
+| Legacy package | Source revision/state | Runtime class | Runtime import |
+|---|---|---|---|
+| `format-black` | `9fcaaff9e5f28c90b628d8a10b7c79aff7913a90` | `CjsBlackFormat` | `@carbonenginejs/runtime-resource/formats/black` |
+| `format-cmf` | unborn working-tree snapshot | `CjsCmfFormat` | `@carbonenginejs/runtime-resource/formats/cmf` |
+| `format-dds` | `66fa149cd826e1114ad0be84479f89dee753ed76` | `CjsDdsFormat` | `@carbonenginejs/runtime-resource/formats/dds` |
+| `format-dxbc` | `3790bda40d7d0d3b774eeb4d82a13827dbe332df` | `CjsDxbcFormat` | `@carbonenginejs/runtime-resource/formats/dxbc` |
+| `format-hlsl` | `e494203f3a1e10866fbe148b460297045cd959ed` | `CjsHlslFormat` | `@carbonenginejs/runtime-resource/formats/hlsl` |
+| `format-webgl` | `428bc141d090b7416745ea43bf3fc320b9e99b43` | `CjsWebglFormat` | `@carbonenginejs/runtime-resource/formats/webgl` |
+| `format-webgpu` | `ffabae8c6a6c658f30807582300aa97522964ee7` | `CjsWebgpuFormat` | `@carbonenginejs/runtime-resource/formats/webgpu` |
+| `format-fbx` | `8d0fcc2fe44c8096b35e360a903bff30b49eb592` | `CjsFbxFormat` | `@carbonenginejs/runtime-resource/formats/fbx` |
+| `format-flac` | unborn working-tree snapshot | `CjsFlacFormat` | `@carbonenginejs/runtime-resource/formats/flac` |
+| `format-gif` | `5d831c5c0533a9579682f776274574289a520899` | `CjsGifFormat` | `@carbonenginejs/runtime-resource/formats/gif` |
+| `format-gltf` | `d0dadf920828bceec987c2a5fa1f161f81db28aa` | `CjsGltfFormat` | `@carbonenginejs/runtime-resource/formats/gltf` |
+| `format-jpeg` | `bed2253ea979bba27812420fa897987d82a91793` | `CjsJpegFormat` | `@carbonenginejs/runtime-resource/formats/jpeg` |
+| `format-mp3` | unborn working-tree snapshot | `CjsMp3Format` | `@carbonenginejs/runtime-resource/formats/mp3` |
+| `format-mp4` | `cffc5a57b115a99ed9e0947a6b9d3390ffc3581c` | `CjsMp4Format` | `@carbonenginejs/runtime-resource/formats/mp4` |
+| `format-obj` | `e5d3f9a1520c7855bd5b6edc1e2304a7b4e18176` | `CjsObjFormat` | `@carbonenginejs/runtime-resource/formats/obj` |
+| `format-ogg` | unborn working-tree snapshot | `CjsOggFormat` | `@carbonenginejs/runtime-resource/formats/ogg` |
+| `format-png` | `04dbb7c0f289043c3c32d9141ec3ef74aeeb1c43` | `CjsPngFormat` | `@carbonenginejs/runtime-resource/formats/png` |
+| `format-red` | `98beab6988111418d6e09827b92d27e08da4c05b` | `CjsRedFormat` | `@carbonenginejs/runtime-resource/formats/red` |
+| `format-stl` | `4858f9a37bf140a3c544fa30a13a6fcce015247b` | `CjsStlFormat` | `@carbonenginejs/runtime-resource/formats/stl` |
+| `format-tga` | `b0f9df263727057537b2279322e8cd088f366179` | `CjsTgaFormat` | `@carbonenginejs/runtime-resource/formats/tga` |
+| `format-wav` | unborn working-tree snapshot | `CjsWavFormat` | `@carbonenginejs/runtime-resource/formats/wav` |
+| `format-webm` | `459203ac293d0d53fff0e43494b7e47d8d4c92bd` | `CjsWebmFormat` | `@carbonenginejs/runtime-resource/formats/webm` |
+| `format-webp` | `19155e9cc7ae05845c23a3c259d3a586569eba40` | `CjsWebpFormat` | `@carbonenginejs/runtime-resource/formats/webp` |
+| `format-yaml` | `3d7e1d1cf9b7a936283d6050efe43a0a9fadb6a4` | `CjsYamlFormat` | `@carbonenginejs/runtime-resource/formats/yaml` |
+
+The unborn donors had no commit-addressable `HEAD`; this document deliberately
+records them as working-tree snapshots rather than inventing a revision. Their
+copied runtime files are the deterministic retained snapshot.
+
+On 2026-07-24, following `format-gr2`'s MIT relicense (its EUPL-derived
+BitKnit decoder was replaced by a clean-room implementation written from the
+published specification in that package's `docs/formats/bitknit2.md`), the
+GR2/GSF reader joined the runtime copies:
+
+| Legacy package | Source revision/state | Runtime class | Runtime import |
+|---|---|---|---|
+| `format-gr2` | `fa64607de7a3a96ed3b1aec5288bf71057642043` (v0.2.0, MIT) | `CjsGr2Format` | `@carbonenginejs/runtime-resource/formats/gr2` |
+
+The donor engine was folded into the single public `CjsGr2Format` class, so
+the copied `CjsFormatGr2` name is gone and `formats/gr2/core/` holds only
+role-named helper modules, matching every other format. Donor license and
+notice files are kept under `format-notices/gr2/`.
+
+## Black definition snapshot
+
+The Black reader uses the package-owned generated definition snapshot at
+`src/formats/black/core/black-schema-v1-2026-07-23.json`. The Red format exposes
+the same catalog for discovery, but its YAML reader currently accepts named
+fields without registry enforcement. The refreshed consumer snapshot landed
+in runtime-resource revision `6beda70` with SHA-256
+`9234DD86DBB5EB3676EF060E383ADBCE8F073941E76A32865D3528DD5DA7B737`.
+Its exact tools-core generator revision was not recorded and remains unknown;
+this page does not infer one from the consumer commit.
+
+This retained generated artifact keeps the published readers deterministic and
+browser-safe without a runtime dependency on a sibling checkout or an
+unpublished generator export. Future schema generation is owned by
+`tools-core/schema`. A consumer of generated output is responsible for
+reviewing and copying the result into its own worktree; an updated snapshot
+must record the generator revision and new digest here.
+
+This generator boundary is transitional. As runtime classes gain embedded
+schema, the shared snapshot and its copy-in step can be reduced and eventually
+removed once every required class is self-describing.
+
+## Native additions
+
+Formats below were authored directly in `runtime-resource` and have no legacy
+donor package. Their `format-notices/<format>/` entries record third-party
+format attribution rather than fork provenance.
+
+| Format | Runtime class | Runtime import | Notes |
+|---|---|---|---|
+| Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` | Original code; chunk layout from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Also carries the SoundbanksInfo JSON helpers (`parseSoundbanksInfo`, `buildSoundbanksCatalog`, `joinSoundbanksInfo`) and `wwiseIdFromName` (FNV-1 32 of the lowercased name, verified against EVE bank/language ids). HIRC entries additionally decode version-stable typed fields (event action lists, action type/target, sound and music-track source ids), pinned by hexdump against bank generator version 150, and the `wwise` static namespace groups the domain toolkit (SoundbanksInfo helpers, id hash, `wwise.eventMediaFromBanks` event → media resolution over inspected banks — graph interpretation for consumers; never used by the resource lifecycle). |
+| Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` | Original code; container/codec-tag behavior from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Includes a Wwise-Vorbis→Ogg repacker (`emit: "ogg"`), an original reimplementation of the ww2ogg algorithm with inline granule computation (no revorb pass needed), and a PTADPCM/16-bit-PCM decoder (`emit: "pcm"` / `toPcm()`, AudioBuffer-ready float32; PTADPCM algorithm from community documentation, verified against EVE media). |
+
+The BNK toolkit also exposes `wwise.sfxNodesFromBanks`: typed, exact-end
+version-150 Random/Sequence, Switch/State, and Layer tails plus event/action
+records and explicit parser diagnostics. It preserves resource facts for
+consumer-owned lowering and is never invoked by the resource lifecycle.
+
+## Post-fork additions inside copied formats
+
+- `formats/dds` gained original, dependency-free **BC6H and BC7 CPU decoders**
+  in `runtime-resource` 0.8.0 (2026-07-21). BC6H covers all fourteen modes,
+  signed and unsigned HDR, transformed endpoints, partition/anchor fixups,
+  interpolation, reserved opaque-black modes, and float RGBA output. BC7 covers
+  all eight modes,
+  two- and three-subset partitions, anchor fixups, P-bits, dual index streams,
+  channel rotation, edge blocks, and the reserved transparent mode. Fixed bit
+  layouts and tables follow the Khronos Data Format Specification and Microsoft
+  BC6H/BC7 documentation. Tests cover every mode and signed/unsigned fixtures;
+  BC7 was also checked against randomized valid-mode blocks and both decoders
+  were exercised on real EVE textures acquired through `tools-core`.
+- `formats/stl` received a writer hardening pass (2026-07-18) without changing
+  its donor origin: binary provenance headers now round-trip the caller's solid
+  name, shared triangle indices are validated as in-range safe integers, scaled
+  coordinates must remain finite, and binary coordinates must fit float32
+  instead of silently becoming infinities. Writer JSDoc and ASCII/binary
+  round-trip/error coverage were expanded in the runtime-owned copy.
+- `formats/cmf` gained a **binary CMF v1 writer** (2026-07-15,
+  `src/formats/cmf/core/writer.js`, `CjsCmfFormat.write`/`writeAsync` and
+  `Write`/`WriteAsync`): original code implementing CarbonEngine's
+  `cmf::BuildFile` behavior — tagged self-relative span flattening with leaf
+  chunk dedup, BufferView→section remapping in first-encounter order,
+  meshoptimizer vertex/index compression (index compression canonicalizes
+  triangle rotation, matching the engine's own writer test expectations), and
+  the post-crc32 file checksum. Verified by write→read roundtrips against the
+  runtime reader; CarbonEngine's `mesh` CMF sources were the behavioral
+  reference, no code copied. `writeShared`/`writeSharedAsync` plus
+  `core/pack.js` (channel interleaving, index packing, unique buffer-index
+  assignment) serialize shared geometry directly, enabling GR2/OBJ/glTF→CMF —
+  verified against real EVE `.gr2` models fetched via
+  `@carbonenginejs/tool-index` (positions exact, triangles equivalent).
+- `formats/cmf` also gained the **GR2 skeleton/animation converter**
+  (2026-07-15, `src/formats/cmf/core/gr2Anim.js`, applied automatically by
+  `writeShared`): GR2-shaped skeletons (root list or `models[].skeleton`)
+  convert to CMF bones/parents/rest transforms with inverse binds rebuilt
+  from the rest hierarchy; decoded Granny curves convert to CMF Step/Linear
+  channels — degree ≤ 1 exactly, degree 2 via adaptive de Boor resampling
+  with discontinuities snapped to one float32 ULP. Consumes only decoded
+  `{knots, controls}` data so the MIT runtime stays independent of the GR2
+  package. Validated on EVE ships (cde3_t3, gde3_t3, cfaux1_t1, mfaux1_t1:
+  3,377 channels ≤ 8.3e-4 positional / ≤ 0.14° rotational vs the GR2 runtime
+  sampler; 9 Granny curve formats) and characters (basicfemale: 132-bone
+  skeleton, exact skin weights).
+- `formats/ogg` gained a pure-JS **Ogg Vorbis PCM decoder** (2026-07-15,
+  `src/formats/ogg/core/{vorbis.js,imdct.js}`, `emit: "pcm"`/`"audio"`):
+  original code implementing the Vorbis I specification (floor 1, residues
+  0/1/2, square-polar coupling, FFT-based IMDCT, windowed overlap-add).
+  stb_vorbis (public domain) was consulted as a behavioral reference and is
+  the source of the spec's floor1 `inverse_db_table` constants; no licensed
+  code was copied. Validated bit-comparable to ffmpeg (max diff ~3e-8) and
+  vgmstream (±1 int16 LSB) across the EVE Vorbis corpus.
+
+## Wem packed-codebook snapshot
+
+The wem Ogg repacker ships a package-owned copy of the aoTuV 6.03 packed
+Vorbis codebook library at
+`src/formats/wem/core/packedCodebooksAotuv603.js` (base64 module). It was
+copied byte-identically from `packed_codebooks_aoTuV_603.bin` in the ww2ogg
+distribution (`github.com/hcs64/ww2ogg`), 74,387 bytes, SHA-256
+`00a93eab267d281401b1efd54e888a2e183299b9e6c446c48d09f701a89d9d27`, retrieved
+2026-07-15. The data is BSD-licensed (Xiph.org Foundation, Adam Gashlin);
+attribution and the full license terms are recorded in
+`format-notices/wem/NOTICE` and `format-notices/wem/LICENSE`. An updated
+snapshot must record its new source and digest here.
+
+## Deliberately not copied
+
+- `format-gr2` migrated into `formats/gr2` on 2026-07-24 (see the dated
+  table above) after its EUPL constraint was resolved; its standalone
+  repository is now a frozen legacy distribution like the other donors.
+- `format-carbon` is historical provenance for the current copied snapshot,
+  not the authority for future regeneration. `tools-core/schema` owns schema
+  generation, while each consuming package reviews and copies generated output
+  into its own worktree. Black consumes the retained snapshot; Red exposes the
+  copied catalog but does not yet enforce it while reading YAML fields.
+- The shader formats were excluded from the original migration while their
+  implementations were still being finished. That sequencing guard was lifted
+  on 2026-07-29 and they moved in as ordinary formats. All four landed:
+  `formats/dxbc`, `formats/hlsl`, `formats/webgl`, and `formats/webgpu`. Their
+  standalone repositories remain in place, unmodified by the move. Their
+  local-only test fixtures are game-derived and were deliberately not copied;
+  the suites that need them skip with an explicit reason.
+
+## Typed-array ownership adjustments
+
+The runtime copies preserve caller byte objects by reference. During the fork,
+three avoidable source-buffer copies were changed to views:
+
+- CMF compressed sections use `Uint8Array.subarray`.
+- glTF GLB chunks use `Uint8Array.subarray`.
+- FBX raw binary property payloads use `Uint8Array.subarray`.
+
+Decoder output buffers and GIF per-frame snapshots still allocate because those
+values have independent semantic identity.

package/docs/formats/stl.md

@@ -1,37 +1,37 @@
-# STL export
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource/formats/stl`  
-Audience: Users and integrators  
-Summary: Defines the STL writer contract for shared geometry, including validation and watertight checking.
-
-## Contract
-
-`CjsStlFormat` writes shared geometry directly to binary or ASCII STL. The
-writer consumes `mesh.vertex.position` and triangular `mesh.indices[].faces`;
-multiple meshes and index groups are flattened in encounter order because STL
-does not carry portable scene, material, skin, or animation structure.
-
-```js
-import { CjsStlFormat } from "@carbonenginejs/runtime-resource/formats/stl";
-
-const bytes = CjsStlFormat.write(sharedGeometry, {
-  binary: true,
-  solidName: "ship_hull",
-  scale: 1000,
-  requireWatertight: true
-});
-```
-
-Writes do not mutate the shared input. Facet normals are recalculated from
-winding by default; set `recalculateNormals: false` to average valid vertex
-normals. Degenerate triangles are skipped by default. Index values must be
-safe integers within the position channel, and binary output rejects
-coordinates outside float32 range instead of silently emitting infinities.
-The `requireWatertight` option rejects open, non-manifold, inconsistently
-wound, or degenerate output.
-
-## Related documentation
-
-- [Format subpaths](README.md)
-- [Format ownership and fork provenance](provenance.md)
+# STL export
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/stl`  
+Audience: Users and integrators  
+Summary: Defines the STL writer contract for shared geometry, including validation and watertight checking.
+
+## Contract
+
+`CjsStlFormat` writes shared geometry directly to binary or ASCII STL. The
+writer consumes `mesh.vertex.position` and triangular `mesh.indices[].faces`;
+multiple meshes and index groups are flattened in encounter order because STL
+does not carry portable scene, material, skin, or animation structure.
+
+```js
+import { CjsStlFormat } from "@carbonenginejs/runtime-resource/formats/stl";
+
+const bytes = CjsStlFormat.write(sharedGeometry, {
+  binary: true,
+  solidName: "ship_hull",
+  scale: 1000,
+  requireWatertight: true
+});
+```
+
+Writes do not mutate the shared input. Facet normals are recalculated from
+winding by default; set `recalculateNormals: false` to average valid vertex
+normals. Degenerate triangles are skipped by default. Index values must be
+safe integers within the position channel, and binary output rejects
+coordinates outside float32 range instead of silently emitting infinities.
+The `requireWatertight` option rejects open, non-manifold, inconsistently
+wound, or degenerate output.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Format ownership and fork provenance](provenance.md)