# 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/`.

On 2026-08-22, the acquisition-free decoder and verified modern cFSD dataset
readers moved from the retiring `tools-fsd` package. The runtime copy contains
only caller-supplied byte decoding, inert schemas, and reader registration; it
does not contain acquisition, build selection, native loader modules, decoded
tables, or game data.

| Legacy package | Source revision/state | Runtime classes | Runtime imports |
|---|---|---|---|
| `tools-fsd` | `1cef89b88c6285f6874420519cfc8f1bd4085281` (source and reader trees clean; documentation-only retirement edits present) | `CjsFsdFormat`, `CjsFsd64Format`, `CjsFsd64Reader`, schema readers | `@carbonenginejs/runtime-resource/formats/fsd`, `@carbonenginejs/runtime-resource/formats/fsd/64`, `@carbonenginejs/runtime-resource/formats/fsd/64/readers` |

The runtime layout also reserves `formats/fsd/32` for legacy Carbon FSD. That
format is headerless and schema-driven, so the current facade identifies it
only from an explicit caller/profile declaration and throws
`CJS_FSD_32_UNSUPPORTED` when reading. Modern cFSD is independently recognized
by its fixed envelope and 64-bit payload length. The two layouts are related
formats, not aliases. Donor MIT license and notice files are retained under
`format-notices/fsd/`.

## 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.