@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.2

package/docs/audio/reference/classes/trinity.md

@@ -1,19 +1,19 @@
 # Carbon audio graph class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/audio/trinity` classes under `src/audio/trinity/`
+Scope: `@carbonenginejs/runtime/audio/trinity` classes under `src/audio/trinity/`
 Audience: Users, maintainers, and automated readers  
-Summary: Provides one-sentence purpose descriptors for maintained Carbon audio graph classes.
-
-<!-- class:IStretchAudio -->
-## `IStretchAudio`
-
-Required stretch-audio component contract.
-
-- Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/trinityAudioApi/IStretchAudio.js`
-- Visibility: Public
-- Kind: Faithful Carbon port
+Summary: Provides one-sentence purpose descriptors for maintained Carbon audio graph classes.
+
+<!-- class:IStretchAudio -->
+## `IStretchAudio`
+
+Required stretch-audio component contract.
+
+- Export: `@carbonenginejs/runtime/audio/trinity`
+- Source: `src/audio/trinity/trinityAudioApi/IStretchAudio.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
 
 <!-- class:AudActionLogCB -->
 ## `AudActionLogCB`
@@ -21,7 +21,7 @@ Required stretch-audio component contract.
 Queues Carbon-shaped audio action records and flushes them to a registered JavaScript callback during manager processing.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionLogCB.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -31,7 +31,7 @@ Queues Carbon-shaped audio action records and flushes them to a registered JavaS
 Provides the base value contract for one queued Carbon audio action.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecord.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -41,7 +41,7 @@ Provides the base value contract for one queued Carbon audio action.
 Records one event post with time, emitter, playing, event, and name identities.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecordPostEvent.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -51,7 +51,7 @@ Records one event post with time, emitter, playing, event, and name identities.
 Records one stop or break action applied to a playing identity.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecordExecuteActionOnPlayingID.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -61,7 +61,7 @@ Records one stop or break action applied to a playing identity.
 Records one emitter-local switch group and state change.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecordSetSwitch.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -71,7 +71,7 @@ Records one emitter-local switch group and state change.
 Records one global audio state-group change.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecordSetState.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -81,7 +81,7 @@ Records one global audio state-group change.
 Records one global or emitter-local real-time parameter change.
 
 - Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/audio/AudActionLog.js`
+- Source: `src/audio/trinity/audio/AudActionLog/AudActionRecordSetRTPC.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -168,10 +168,10 @@ Provides the fixed high-priority Carbon emitter dedicated to music events.
 <!-- class:AudObstructionOcclusion -->
 ## `AudObstructionOcclusion`
 
-Owns Carbon's caller-supplied per-emitter obstruction/occlusion fade and backend-delivery lifecycle.
+Owns Carbon's caller-supplied line-of-sight state and backend delivery.
 
 - Export: None
-- Source: `src/audio/trinity/audio/AudObstructionOcclusion.js`
+- Source: `src/audio/trinity/audio/AudObstructionOcclusion/AudObstructionOcclusion.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 
@@ -238,20 +238,20 @@ Drives a curve set's time from a monitored real-time parameter with a fallback c
 <!-- class:EmitterState -->
 ## `EmitterState`
 
-Retains obstruction, occlusion, and retry state for one registered emitter.
+Obstruction/occlusion fade state retained for one registered emitter.
 
 - Export: None
-- Source: `src/audio/trinity/audio/AudObstructionOcclusion.js`
+- Source: `src/audio/trinity/audio/AudObstructionOcclusion/EmitterState.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 
 <!-- class:FadingValue -->
 ## `FadingValue`
 
-Advances one normalized obstruction or occlusion value towards its target.
+One obstruction or occlusion value fading towards an authored target.
 
 - Export: None
-- Source: `src/audio/trinity/audio/AudObstructionOcclusion.js`
+- Source: `src/audio/trinity/audio/AudObstructionOcclusion/FadingValue.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 
@@ -314,12 +314,22 @@ Stores vertices, indices, and bounds for Carbon audio geometry data.
 - Source: `src/audio/generated/trinityAudioApi/Tr2AudGeometryData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
-<!-- class:ITr2AudEmitter -->
-## `ITr2AudEmitter`
-
-Contract audio2 uses to drive an audio emitter: initialisation, placement, naming and prefixing, event posting, switches, RTPCs, attenuation scaling, visibility, muting and forced culling state.
-
-- Export: `@carbonenginejs/runtime/audio/trinity`
-- Source: `src/audio/trinity/trinityAudioApi/ITr2AudEmitter.js`
-- Visibility: Public
-- Kind: Faithful Carbon port
+<!-- class:ITr2AudEmitter -->
+## `ITr2AudEmitter`
+
+Contract audio2 uses to drive an audio emitter: initialisation, placement, naming and prefixing, event posting, switches, RTPCs, attenuation scaling, visibility, muting and forced culling state.
+
+- Export: `@carbonenginejs/runtime/audio/trinity`
+- Source: `src/audio/trinity/trinityAudioApi/ITr2AudEmitter.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:IAudActionLog -->
+## `IAudActionLog`
+
+Required logging contract consumed by AudManager.
+
+- Export: `@carbonenginejs/runtime/audio/trinity`
+- Source: `src/audio/trinity/audio/AudActionLog/IAudActionLog.js`
+- Visibility: Public
+- Kind: Carbon

package/docs/character/architecture.md

@@ -153,3 +153,279 @@ character/interior schemas reference it.
 The removed schema-v1/v2 character graph is not a compatibility surface.
 Consumers migrate to the schema-v10 direct source library and separate
 schema-v4 plan, not speculative legacy models.
+### Incarna placeholders, and what a checker makes of them
+
+Found 2026-09-12 by running `carbon-class --check` across the runtime for the
+first time. Five classes under `src/character/incarna/` carry Carbon-shaped names
+that resolve to no Carbon declaration.
+
+These historical Incarna placeholders lack current donor declarations; that
+does not apply to all character classes. `Tr2SkinnedObject`,
+`Tr2SkinnedObjectLod` and `Tr2InteriorPlaceable` have donor declarations.
+Record the evidence for each placeholder separately; a name inferred from a
+comment or reference does not establish its fields or behavior as a port.
+The checkers cannot yet distinguish that provisional status from a missing port.
+
+#### `Tr2InteriorCell`: the smell it was built from
+
+`Tr2InteriorPlaceable.h:36` says placeables *"inhabit one or more
+Tr2InteriorCells, as determined by a ..."* - and that comment is the ONLY
+occurrence in the whole of Carbon. No header declares it, no source defines it.
+
+So the NAME is Carbon's and nothing else is. Our
+`src/character/incarna/interior/Tr2InteriorCell.js` is a placeholder built from
+that one line, which is correct practice for this lane - but its SHAPE is
+unevidenced, so nothing about its fields or methods should be trusted as ported.
+Cite the mention in the file so the next reader knows how thin the evidence is.
+
+#### The incarna curves invert Carbon's own naming
+
+`Tr2ColorCurve`, `Tr2ColorKey`, `Tr2ScalarCurve` and `Tr2ScalarKey` under
+`src/character/incarna/curves/` each say *"Adapted from CCPWGL Tw2ColorCurve2
+(MIT)"*. They are ccpwgl classes with a `Tr2` prefix swapped on.
+
+Two problems with that, neither about the code:
+
+- **Carbon has curve classes for both**, named the other way round:
+  `Tr2CurveColor.h` and `Tr2CurveScalar.h` (plus `Tr2CurveColorMixer`,
+  `Tr2CurveScalarExpression`, `Tr2ScalarExprKeyCurve`). Carbon puts the noun
+  first - `Tr2Curve` + kind - so `Tr2ColorCurve` reads as Carbon while using
+  ccpwgl's word order.
+- **A `Tr2` prefix asserts a Carbon donor.** These have a ccpwgl donor, which is
+  a different provenance with different rules: ccpwgl is a loose guide and is
+  polluted with concepts that came FROM us, so a ccpwgl adaptation needs its
+  origin established rather than assumed.
+
+Open question for this lane, not answered here: whether the incarna curves should
+BE `Tr2CurveColor`/`Tr2CurveScalar` - a real port of classes that exist - or
+whether Incarna genuinely needs its own curve types, in which case they should not
+wear a prefix that claims otherwise.
+### Skinned per-object data is character work, not Trinity work
+
+**Both skinned per-object classes live in a Trinity header and have no Trinity
+producer.** Every allocation site is a skinned or interior path, so they belong to
+this domain however their donor file is named. Verified against Carbon 2026-09-11.
+
+| class | donor | allocated by |
+|---|---|---|
+| `Tr2PerObjectDataSkinned` | `Tr2PerObjectData.h:100`, extends `Tr2PerObjectDataPSBuffer` | `Interior/Tr2IntSkinnedObject.cpp:322`; consumed at `:217` and `Tr2SkinnedModel.cpp:120,130` |
+| `Tr2PerAreaDataSkinned` | `Tr2PerObjectData.h:152`, extends `Tr2PerObjectData` | `Interior/Tr2IntSkinnedObject.cpp:255`, `Tr2SkinnedModel.cpp:59` |
+
+Neither exists here. A Trinity-side plan to "restore the four per-object classes"
+should therefore stop at `Tr2PerObjectDataPSBuffer` and
+`Tr2PerObjectDataStandard`; these two need the interior renderer, which is the
+part being reverse-engineered, so adding the classes alone completes nothing.
+
+#### The VS buffer layout, exactly
+
+`TR2_MAX_BONES_PER_MESHAREA` is **69**, and the allocation is
+`(69 * 3 + 5 + 4) * 16` = **3,456 bytes**, three registers per joint:
+
+| region | offset | size |
+|---|---|---|
+| joint palette | 0 | 3,312 bytes (69 x 3 registers) |
+| world matrix | 3,312 | 64 |
+| **unwritten** | 3,376 | 16 |
+| mirror matrix | 3,392 | 64 |
+
+Both skinned classes target the **per-object VS register, 3** (`Tr2Renderer.cpp:40`;
+per-object PS is 4 at `:41`). So this is the same binding `Tr2PerObjectDataStandard`
+uses with a 40-register buffer - same slot, far more in it.
+
+#### Two owners write one buffer, and that is the shape to preserve
+
+`Tr2PerAreaDataSkinned::SetPerObjectDataToDevice` creates the buffer, locks it,
+calls the OBJECT's `UpdateVertexShaderCBMirror` to place world and mirror, then
+memcpy's its own joints at offset 0 for `m_jointCount * 3 * 16` bytes. It then
+clears the VS family from the mask and delegates the remainder to the object:
+
+    constantTypeMask = constantTypeMask & ~perFrameVsMask;
+    if( constantTypeMask ) m_perObjectDataPtr->SetPerObjectDataToDevice( ... );
+
+So the per-AREA class owns the joint prefix, the per-OBJECT class owns the matrix
+tail, and the object also answers for the pixel half. A static helper over a plain
+`{ vs, ps }` record cannot express that; it needs the instance relationship
+(`m_perObjectDataPtr`). `CCP_ASSERT( m_jointCount <= TR2_MAX_BONES_PER_MESHAREA )`
+guards the prefix.
+
+The object-level upload copies **only** world and mirror - not the joint palette it
+borrows, and not `m_worldPos`, which it stores but never uploads.
+
+#### The transpose rule does NOT apply here, and that needs checking before use
+
+`EveSpaceObject2.cpp:667-668` writes `Transpose( m_worldTransform )` into the
+standard per-object VS data. The skinned path does a **raw byte copy** -
+`memcpy( VS + ..., &m_worldMat.m[0][0], 4 * 16 )` (`Tr2PerObjectData.cpp:102-103`,
+and again at `:117-118` for the indirect writer). No transpose.
+
+The only caller of `SetWorldMatrix` is `Tr2IntSkinnedObject.cpp:331`, passing a
+parameter its own comment calls "The world transform of the object", untouched;
+`:332` sets the mirror to `IdentityMatrix()`.
+
+So either the interior skinned shader reads the opposite orientation from the
+standard path, or the matrix is already transposed further upstream. **Read it off
+the shader.** Applying RawData's ordinary `SetAndTranspose` rule here would
+double-transpose, and per the math conventions skill this class of error passes
+every identity-matrix fixture. Test with rotation plus non-uniform scale.
+
+#### One constructor zeroes, the other does not
+
+`Tr2PerObjectDataPSBuffer()` explicitly `memset`s its 1,280-byte PS storage to
+zero. `Tr2PerObjectDataStandard()` sets only the active size and leaves its
+640-byte VS storage **uninitialised** - that is what its
+`cppcheck-suppress uninitMemberVar` is for.
+
+Since a short copy preserves the remaining storage, the PS tail is zeros in Carbon
+and zeros in JS, which is faithful and needs no note. The **VS tail is garbage in
+Carbon and zeros in JS**, which cannot be reproduced and is the only half that is a
+real divergence.
+
+#### Our current state: the fields exist, the mechanism does not
+
+`CjsPerObjectLayouts` now aggregates the split layout classes:
+`CjsEveSpaceObjectLayout` and `CjsEveSpacePerObjectLayout` declare `boneOffsets`
+(4 x UINT32); `CjsEveTurretSetLayout` declares `currentBoneOffset`,
+`prevBoneOffset` and two unused UINT32 lanes. These are live declarations under
+`src/trinity/core/rawData/layouts`, not only dropped references. The field
+declarations and the restored per-object wrapper classes do not implement a
+bone-buffer upload or ring; that realization remains separate work.
+
+#### ccpwgl already solves this, and differently from Carbon
+
+ccpwgl's Carbon path does **not** use Carbon's inline joint region. Bones ride a
+dedicated UBO and the per-object VS block carries only addressing: register 26 holds
+`boneOffsets` as **uint bit patterns**, and the translated shader computes
+`boneIndex = blendIndex + floatBitsToInt(cb3[26].xy)`. Because its bone UBO is
+per-object and base-0, `cur = prev = 0`, and zero's float bit pattern is exactly
+uint 0. Its legacy GLES layout keeps an inline `JointMat` instead, which the Carbon
+path explicitly does not copy.
+
+That gives the first skinned bring-up a choice worth making deliberately:
+
+- **per-object base-0 buffer**, as ccpwgl does - the zeros already sitting in our
+  layout are then correct and nothing needs writing; or
+- **a shared ring**, which is what `prevBoneOffset` implies and what Carbon's
+  `Tr2DynamicRingBuffer` family exists for. It is the only option that can carry
+  last frame's bones for temporal effects, and it is also the path whose indexed
+  fetch produced the `ld_structured` self-clobber fixed in `68c147f`.
+
+`Tr2DynamicRingBuffer`, `Tr2RingVertexBuffer` and `Tr2RingIndexBuffer` are all
+absent from our tree, so the ring option starts with three unported classes.
+
+### `Tr2SkinnedObjectLod` is missing its three detail-model accessors
+
+Surfaced 2026-09-11 by a Trinity-side naming cleanup, and recorded here because
+the class is ours: anything skinned belongs to this domain regardless of which
+donor directory the header sits in.
+
+`Tr2SkinnedObjectLod` declares three accessors that our port does not have
+(`trinity/trinity/Tr2SkinnedObjectLOD.h:65-67`):
+
+    Tr2SkinnedModel* GetHighDetailModel();
+    Tr2SkinnedModel* GetMediumDetailModel();
+    Tr2SkinnedModel* GetLowDetailModel();
+
+Our class holds the state they return - `highDetailProxy`, `mediumDetailProxy`
+and `lowDetailProxy` - and reads all three internally, so this is three
+accessors over existing fields, not a feature.
+
+**How they were found is the transferable part.** They had been invisible because
+the JS class was renamed `Tr2SkinnedObjectLod` to `Tr2SkinnedObjectLOD`, on
+evidence that turned out to be an `#include "Tr2SkinnedObjectLOD.h"` line rather
+than a declaration. Carbon's FILE is `Tr2SkinnedObjectLOD.h`; Carbon's CLASS is
+`Tr2SkinnedObjectLod`. The method-parity lint matches on exact class name, so the
+rename silently unmatched the class and took its gap report with it. Reverting
+the name (`runtime` commit `86b674a5`) made all three appear at once.
+
+So a parity checker reporting nothing for a character class is not evidence of
+parity - confirm the class name matches Carbon's DECLARATION, not its filename.
+
+### Interior and WoD knowledge scattered through Trinity, collected 2026-09-11
+
+**Every item below is a comment in a Trinity source file, not in the character
+domain, so none of it was findable from here.** Swept by searching `src` for
+interior / WoD / Incarna outside `src/character`. Each line is quoted with its
+file so a thread can be picked up at the site; the Carbon cites are the donor
+lines those comments name, not claims verified in this sweep.
+
+**Portal visibility exists as a concept.** `Tr2VisibilityEvent.js:10` says the
+events are what "Tr2VisibilityResults and the interior/portal visibility consumers
+read", and `Tr2VisibilityResults.js:9` that results are collected "for the
+interior". Our `Tr2VisibilityResults` folder cites donor `Tr2InteriorScene.h`, so
+the interior scene's visibility machinery is partly present under a Trinity path.
+
+**The interior scene owns a background cubemap, toggled by a render step.**
+`TriStepToggleCubemap.js` holds a "Carbon-private `Tr2InteriorScene` pointer;
+runtime-only and not serialized" (:11) and "Enables or disables the interior
+scene's background cubemap" (:28).
+
+**Interiors and WoD baking share a per-frame block.** `CjsPerFrameLayouts.js:24`
+describes a "block used by interiors, WoD baking, and primitives", and :106 records
+that a reduced block "binds in place of the full VS one
+(`Tr2InteriorScene.cpp:856`)". That is the only WoD-baking reference anywhere
+outside the character domain.
+
+**Interior placeables have their own per-object filler.**
+The former `CjsPerObjectLayouts.js:415-416` comment now lives in
+`src/trinity/core/rawData/layouts/CjsTr2PerObjectLayout.js:10-15`: its donor
+filler is `Tr2InteriorPlaceable::GetPerObjectData`
+(`Interior/Tr2InteriorPlaceable.cpp:555-585`). The class already exists at
+`src/character/trinity/interior/Tr2InteriorPlaceable.js`; its per-object filler
+is missing. Character consumes the shared Trinity layout rather than declaring
+a second one. "Not a Trinity-layer class" did not mean "absent from runtime".
+
+**Interior additive animation was reverse-engineered in ccpwgl.**
+`Tr2GrannyAnimation.js:1338-1339` cites a "proven reverse-engineered
+`composeInteriorAdditivePose`" at
+`ccpwgl/src/interior/character/Tr2InteriorAdditiveAnimation.js`. Given how little
+exists for this engine, an already-proven reverse-engineering of an interior
+animation compose is worth reading before redoing it.
+
+**The interior light count is a signed bit-cast.** `RawData.js:68` names it as the
+example of a "SIGNED integer bit-cast (two's complement)", so a consumer reading it
+as unsigned will be wrong for negative values.
+
+#### Deliberately excluded from the list
+
+`Tr2RenderUtils.js` ("interior-edge flip", "interior vertices"),
+`Tr2Blitter.js:295`, `Tr2RenderStateSetup.js:349` and
+`Tr2EffectStateManager.js:1365` all say "interior" about GEOMETRY - quad
+triangulation edges, and hulls drawing their own inside faces when the cull mode
+inverted. Nothing to do with the interior engine, and worth knowing so the same
+sweep does not keep re-finding them.
+
+### Undiscovered: three of Carbon's four interior interfaces
+
+**Found 2026-09-11 by comparing Carbon's declarations against ours. Not dropped,
+not deferred - simply never noticed, and nothing records a decision about them.**
+
+`trinity/trinity/Include/ITr2Interior.h` declares four interfaces, all
+`BLUE_INTERFACE`:
+
+| Carbon | line | here |
+|---|---|---|
+| `ITr2InteriorCullable` | :27 | **nothing at all** |
+| `ITr2Interior` | :33 | **nothing at all** |
+| `ITr2InteriorDynamic` | :44 | **nothing at all** |
+| `ITr2InteriorLight` | :69 | `src/character/trinity/interior/ITr2InteriorLight.js` |
+
+The one that exists is a **typedef contract** - a JSDoc `@typedef` with
+`export {}` and no class - and its own comment gives the reason: a
+`BLUE_INTERFACE` is not a constructible Blue model, so it must not be registered
+with `type.define`. That treatment looks right and is the precedent the other
+three should follow if they are represented the same way.
+
+**Why they were invisible.** Every check we have looks for a declared class.
+`ITr2InteriorLight` declares none, so it does not appear in a class catalog, a
+parity audit, or the naming lint - and the three that are absent look identical
+to the one that is present. They surfaced only from a donor-side sweep: reading
+what Carbon's headers declare and subtracting what we declare, which is the
+opposite direction from every existing checker.
+
+**These belong to the character library**, being the interior scene's
+cullable/dynamic/light contracts rather than anything in Trinity proper.
+
+Interior work that touches culling, dynamic interiors or interior lighting should
+decide their disposition first. The adjacent `Tr2InteriorPerLightPSData` and
+`Tr2InteriorPerObjectPSData` DO exist here, so the data structures arrived
+without the contracts that describe who produces them.

package/docs/character/reference/character-appearance-plans.md

@@ -35,11 +35,10 @@ Resource acquisition, decoded image bytes, GPU handles, render targets, cache
 leases, and live scene objects remain outside the plan. The plan may identify
 those inputs but must remain GPU-free and serializable.
 
-`CjsCharacterAppearancePlan` is an ordinary schema-backed model. Inherited
-`CjsModel.from(values)` and instance `SetValues(values)` consume the same
-`carbonenginejs.characterAppearancePlan` schema-v4 shape. Inherited
-`GetValues({ refs: true })` emits serializable `_id`/`_ref` graph metadata.
-There is no alternate wire format or retained document copy.
+`CjsCharacterAppearancePlan` uses inherited model hydration and serialization
+with the same `carbonenginejs.characterAppearancePlan` schema-v4 shape, not an
+alternate wire format or retained document copy. See
+[graph serialization](../guides/runtime-usage.md#serialize-a-model-graph).
 
 The complete resolver pipeline is responsible for selection, dependency, LOD,
 material, texture-role, placement, and bake-order decisions. Hydration applies
@@ -228,26 +227,11 @@ through extra static methods on the model.
 
 ## Offset and transform normalization
 
-Three different transforms must remain separate:
-
-- decoded PNG placement: image size, atlas offset, atlas extent, target size,
-  and whether placement metadata was present;
-- an authored sampler transform such as `TransformUV0`, which current evidence
-  treats as bounds rather than the PNG offset; and
-- projected-decal placement, whose spherical parameters and atlas placement
-  belong to the projection contract.
-
-An adapter may combine them into a final sampling transform, but the source
-records must not overwrite one with another. Cropped placement is applied once.
-The known double-application cause is closed at the policy and structural-test
-level and must remain a regression case; the complete visual fixture matrix is
-still open.
-
-Diffuse, normal, and specular inputs retain independent sample bounds. A
-material-global UV transform is insufficient because the three assets can have
-different placement metadata.
-
-The reviewed evidence establishes only renderer-neutral rules:
+Keep decoded PNG placement (size, offset, extent, target size and metadata
+presence), authored sampler bounds, and projected decals' spherical parameters
+and atlas placement distinct. An adapter may combine them for sampling without
+overwriting source values. The double-placement cause is structurally closed and must remain a
+regression case; the full visual matrix remains open.
 
 | Transform rule | Status |
 | --- | --- |
@@ -258,16 +242,14 @@ The reviewed evidence establishes only renderer-neutral rules:
 | Diffuse, normal, specular, and cut inputs retain independent placement and sampling bounds. | Proven contract requirement; complete consumer qualification remains open. |
 | Rebinding reconstructed textures requires an explicit consumer contract and atomic readiness. | Renderer-owned adoption gate. |
 
-The renderer must choose from the resource actually bound at that stage. It
-must not force identity globally, copy PNG placement into `TransformUV0`, bind
-a cropped channel as though it were a full atlas, or assume one transform
-covers every object and mask.
+Choose transforms from the resource actually bound at that stage: never force
+identity globally, copy PNG placement into `TransformUV0`, or treat a cropped
+channel as a full atlas. One transform cannot cover every object and mask.
 
-Decoded geometry may expose several materially distinct surfaces within one
-atlas region. Atlas bounds are placement evidence, not material ownership.
-An engine therefore needs an explicit typed consumer relationship before it
-rebinds a reconstructed channel; unqualified surfaces retain their authored
-bindings. This rule does not claim complete renderer or visual parity.
+Several materially distinct surfaces may share an atlas region; bounds prove
+placement, not ownership. Rebinding requires a typed consumer relationship;
+unqualified consumers retain authored bindings.
+These rules do not establish complete renderer or visual parity.
 
 ## Dependency ownership and garment coverage
 
@@ -316,35 +298,17 @@ by this data contract. Missing evidence produces diagnostics or an explicit
 
 ## Current contract tests
 
-The data-only contract and first-stage resolver tests prove:
-
-- equivalent hydration through inherited `from` and `SetValues`;
-- JSON graph round-trip through inherited `GetValues({ refs: true })`;
-- authoritative target pass-array order;
-- distinct owner and contributor references;
-- one diffuse-minus-cut coverage reused by normal clear/replacement/addition
-  and consumer alpha reconstruction;
-- replacement normal before independent additive normal detail;
-- independent diffuse, normal, and specular sample bounds;
-- native rejection of unresolved or duplicate graph identities; and
-- resolver-owned operation strings remaining ordinary model data;
-- exact paper-doll selection and source-record relationship traversal;
-- strict resource-version identity and unique configuration/geometry
-  resolution without filename parsing;
-- refusal to infer baseline candidate or metadata inheritance, or choose among
-  duplicate exact resource-version inventories;
-- explicit diagnostics for dangling effective version-metadata relationships;
-- exact preservation of raw dependency and occlusion strings beside typed
-  references, requester-owned projection of a unique exact dependency source,
-  and per-value diagnostics for unresolved references without fabricated
-  targets;
-- exact typed modifier-location and clothing-removal suppression without
-  deleting the retained selection, including explicit cyclic-conflict
-  diagnostics;
-- retention and diagnosis of categories absent from the native modifier order;
-- contribution relationships without inferred pass order;
-- deterministic diagnostics for dangling, ambiguous, and policy-dependent
-  inputs; and
-- source-library immutability and standalone plan graph round trips;
-- exact modifier sort keys, stable equal-key order, metadata endpoint swaps,
-  and caller-owned atlas-layout values.
+See the [plan fixtures](../../../test/character/runtime-character/character-appearance-plan.test.js),
+[resolver checks](../../../test/character/runtime-character/character-appearance-resolver.test.js)
+and [composition-policy checks](../../../test/character/runtime-character/character-composition-policy.test.js)
+for the contracts above. The fixtures retain:
+
+- shared diffuse-alpha-minus-cut-red coverage for normal clear, replacement,
+  addition and final consumer alpha;
+- replacement before additive normal detail, with independent diffuse, normal
+  and specular sample bounds; and
+- source-library immutability, standalone graph round trips and dangling or
+  ambiguous-input diagnostics.
+
+These tests import built output. The plan fixture still asserts schema v1;
+its policy-backed order is not fresh schema-v4 or visual qualification.

package/docs/character/reference/prepared-libraries.md

@@ -105,14 +105,11 @@ creating an unresolved `_ref` or placeholder object.
 
 ## Hydration and serialization
 
-`CjsCharacterLibrary.from(values)` and instance `SetValues(values)` hydrate
-the same public shape and direct object relationships. `Get(document, recordID)`
-and `GetDocument(document)` query those records. There is no alternate retained
-JSON document or identity-conversion wrapper.
-
-`GetValues({ refs: true })` serializes shared relationships. Tokens may change
-on export; equivalent relationships, not stable token numbers, define the
-round-trip contract. See [runtime usage](../guides/runtime-usage.md) for examples.
+Inherited hydration consumes the same public shape and direct relationships;
+there is no retained JSON document or identity-conversion wrapper.
+See [record lookup](../guides/runtime-usage.md#read-records-and-relationships)
+and [graph serialization](../guides/runtime-usage.md#serialize-a-model-graph)
+for methods and examples. Round trips preserve relationships, not token numbers.
 
 ## Builder boundary
 
@@ -183,14 +180,10 @@ while interpreting retained `oFFs`/`pHYs` millionths is character policy.
 Black/Red object graphs target registered native/historical classes separately;
 they are not replacements for this combined library or the appearance plan.
 
-Candidate arrays do not assert semantic selection. The combined library does
-not contain unlabelled model families, filename-derived texture roles, compiled
-recipe links, or material fallbacks. Optional model bundles retain decoded
-configuration/geometry relationships plus explicitly labelled terminal-LOD and
-paired-resource-family derivations; unpaired or ambiguous candidates remain
-unresolved.
-External configuration graphs, geometry data, images, animations, and effects
-remain resource-manager inputs rather than embedded library objects.
+Candidate inventories do not select semantic roles or supply unlabelled model
+families, filename-derived texture roles, compiled recipe links or material
+fallbacks. The table above defines qualified bundles and labelled derivations;
+unpaired or ambiguous candidates remain unresolved.
 
 One published character resource can use the same definition identity for
 more than one sex. The appearance resolver selects an exact source from
@@ -205,20 +198,11 @@ published definition files are producer inputs; their decoded values survive
 inside `characterDefinitions`, so a runtime frontend does not reconstruct the
 catalog from the publication files.
 
-An editor may hydrate and insert same-shaped values with
-`library.Create(documentName, values)`, or add an already-hydrated record with
-`library.Add(documentName, record)`. The latter preserves that exact instance.
-`Remove` detaches a record, `Delete` additionally runs an optional explicit
-domain teardown callback, and `Clear` empties one document without guessing
-record destruction.
-
-These operations apply the document property's normal flag/update contract.
-Each collection has a lazy private-index invalidation flag, consumed when that
-document is next queried. The library emits `recordadded`, `recordremoved`,
-`recorddeleted`, and `documentcleared` so an editor can react to incremental
-changes. Private indexes and flags are runtime state and are excluded from the
-JSON shape. Direct array mutation remains possible because the arrays are the
-model fields; call `Reindex()` after bypassing the named methods.
+Use the [editor mutation API](../guides/runtime-usage.md#mutate-editor-items)
+for insertion, removal, events and reindexing; `Clear` does not guess record
+destruction. Named methods apply the document property's normal flag/update
+contract. Lazy private-index flags are consumed on the next document query;
+indexes and flags are runtime state, excluded from JSON.
 
 `CjsCharacterLibraryManager` can install the combined model directly or obtain
 its decoded object through one injected loader. Plain schema-v10 values contain

package/docs/global/reference/api.md

@@ -37,7 +37,8 @@ package remains private until the atomic consumer and registry cutover.
 | [`./utils/arrays`](../../../src/global/utils/arrays.js) | Normalizes nullable values and mutates writable array-like targets. | `toArray`, `copyArrayLike`, `fillArrayLike` |
 | [`./utils/bytes`](../../../src/global/utils/bytes.js) | Creates byte views, owned copies, exact buffers, and prefix checks. | `asUint8Array`, `copyBytes`, `toArrayBuffer`, `hasBytePrefix` |
 | [`./utils/compression`](../../../src/global/utils/compression.js) | Detects and decompresses gzip through Web-standard streams. | `isGzip`, `decompressBytes`, `decompressGzip`, `decompressGzipIfNeeded` |
-| [`./contracts`](../../../src/global/contracts/index.js) | Declares dependency-floor nominal obligations whose required base methods throw. | `CjsBackendCandidate`, `CjsConstantPayload`, `CjsFrameLifecycle`, `CjsInstancedMeshManager`, `CjsScriptCallback`, `ITr2BoundingBox`, `withITr2BoundingBox`, `ITr2RenderNode`, `withITr2RenderNode` |
+| [`./contracts`](../../../src/global/contracts/index.js) | Declares dependency-floor nominal obligations whose required base methods throw. | `CjsBackendCandidate`, `CjsConstantPayload`, `CjsFrameLifecycle`, `CjsInstancedMeshManager`, `ITr2BoundingBox`, `withITr2BoundingBox`, `ITr2RenderNode`, `withITr2RenderNode` |
+| [`./blue`](../../../src/global/blue/index.js) | Ports of Carbon's blueexposure layer: facilities Blue provides to every subsystem rather than to one. | `CjsScriptCallback` |
 | [`./utils/errors`](../../../src/global/utils/errors/index.js) | Represents coded operational failures and Web-compatible cancellation without logging or transport policy. | `CjsError`, `CjsCancellationError`, `CJS_OPERATION_CANCELLED` |
 | [`./utils/is`](../../../src/global/utils/is.js) | Provides shared literal-boolean value predicates. | `isTypedArray`, `isArrayLike`, `isFunction`, `isNullish`, `isObject`, `isObjectLike`, `isPlainObject`, `isPromiseLike` |
 | [`./utils/json`](../../../src/global/utils/json.js) | Encodes and decodes JSON with explicit UTF-8 behavior. | `encodeJson`, `decodeJson` |