@carbonenginejs/runtime-resource 0.12.0 → 0.12.1

package/docs/formats/webgpu/reference/wgsl-compatibility.md

@@ -36,7 +36,7 @@ operations (a previous compiler boundary for higher-quality shader profiles):
   crack/z-fight artifact `precise` protects against;
 - precise-mask metadata is still validated structurally (well-formed mask,
   lanes covered by a destination write) in
-  `src/core/wgsl/precisionControls.js`.
+  `src/formats/webgpu/core/wgsl/precisionControls.js`.
 
 NOT promised: bit-exact arithmetic parity with native D3D11; differential
 tests against native output may differ in final ulps. Globally-non-refactorable
@@ -64,10 +64,10 @@ projections, and per-lane `movc` selects — in BOTH stages.
 
 SSA may resolve a post-join read to one arm's definition (the other path
 diverges via return/discard); structured WGSL scoping cannot express that
-directly. `src/core/wgsl/hoistEscapingValues.js` hoists escaping declarations
-to uninitialized function-top `var`s (WGSL zero-initializes) plus in-place
-assignments. The zero is unobservable — SSA proves the value is only read on
-assigning paths.
+directly. `src/formats/webgpu/core/wgsl/hoistEscapingValues.js` hoists
+escaping declarations to uninitialized function-top `var`s (WGSL
+zero-initializes) plus in-place assignments. The zero is unobservable — SSA
+proves the value is only read on assigning paths.
 
 ### Switch clauses without a `default` → empty WGSL `default`
 
@@ -1054,11 +1054,12 @@ sample form and in both stages.
   495 qualified packages are byte-identical. Every changed package carries
   exactly one two- or three-layer Detail transform.
 
-  This closes the compiler-side sampled-texture binding limit only. WGSL-set
-  version 3 is not yet accepted by the committed engine reader, and raw module
-  compilation does not prove resource realization or rendering. Runtime
-  support must consume the recipe explicitly before these packages are
-  render-ready.
+  This closes the compiler-side sampled-texture binding limit. Raw module
+  compilation alone does not prove resource realization or rendering, but the
+  current engine accepts WGSL-set version 3 and realizes the documented
+  `texture-2d-array` transform recipe. The Detail and HeatDetail families have
+  exact draw evidence; the Environment family remains unverified. See
+  [Consumer boundary: resource transforms](#consumer-boundary-resource-transforms).
 - **Immediate 2D sample offsets** — `sample`, `sample_b`, `sample_d`, and
   `sample_l` lower their signed `_aoffimmi(u,v,w)` record to WGSL's final
   constant `vec2<i32>(u, v)` sampling argument. Both APIs apply that
@@ -1221,13 +1222,14 @@ WGSL forbids screen-space derivatives — the `dpdx*`/`dpdy*` family and the
 implicit-LOD samples that derive internally (`textureSample` /
 `textureSampleBias`) — inside **non-uniform** control flow (a branch whose
 condition can differ between the pixels of a 2x2 quad), because the derivative
-compares neighbor pixels that may not all be present. `src/core/wgsl/
-uniformity.js` tags each SSA value uniform or varying; when the fragment lowerer
-finds one of these operations under a varying-conditioned branch it records
-`requiresDerivativeUniformityOptOut` on the program, and `emitWgsl` prepends the
-module-level filter `diagnostic(off, derivative_uniformity);` (a standard WGSL
-opt-out that Dawn/Tint and Naga both honor — browser-gate confirmed) rather than
-rejecting the shader.
+compares neighbor pixels that may not all be present.
+`src/formats/webgpu/core/wgsl/uniformity.js` tags each SSA value uniform or
+varying; when the fragment lowerer finds one of these operations under a
+varying-conditioned branch it records `requiresDerivativeUniformityOptOut` on
+the program, and `emitWgsl` prepends the module-level filter
+`diagnostic(off, derivative_uniformity);` (a standard WGSL opt-out that
+Dawn/Tint and Naga both honor — browser-gate confirmed) rather than rejecting
+the shader.
 
 Why the directive and not gradient hoisting: the DXBC came from HLSL that relied
 on **D3D11's permissive divergent-derivative behavior** (non-participating quad
@@ -1266,8 +1268,16 @@ is not emitted unnecessarily.
 
 ## Selected-effect package provenance
 
-`BuildEffect` emits selected-effect INFO schema version 2 while the binary
-CEWGPU container remains version 1. INFO v2 records the WebGPU target,
+The versioned checkpoints in this section describe the retired flat-chunk wire
+used before the Carbon-container switchover. Their corpus counts remain
+compiler and provenance evidence; `INFO`, `META`, `PGRF`, `RFLX`, `RBLB`,
+`ANLS`, and `WGSL` are no longer stored chunks. Current bytes are Carbon
+version-15 records with derived compatibility views. See
+[CEWGPU effect container](../formats/cewgpu.md).
+
+At the 0.4.2 checkpoint, `BuildEffect` emitted selected-effect INFO schema
+version 2 while the binary CEWGPU container remained version 1. INFO v2
+recorded the WebGPU target,
 backend-package and translator semantic versions, and a lower-case SHA-256
 digest computed over the exact compiled-effect input byte view. A conflicting
 caller digest fails closed. The reader retains legacy selected-effect INFO v1
@@ -1370,36 +1380,44 @@ gates compile with zero WGSL warnings.
 
 ## All-body backend packaging
 
-`mode: "all"` translates every unique source body and stores the result in a
-`WGSB` `CJS_WGSL_BODY_SET` chunk. Selected mode remains the default and is
-unchanged.
+`mode: "all"` attempts every unique source body after the resolved selection
+passes its initial translation gate. In the retired chunk wire, the result was
+stored as a `WGSB` `CJS_WGSL_BODY_SET` document. The current Carbon wire stores
+WGSL in stage program slots and bind-group/transform data in per-pass backend
+blocks; `backendBodySet` is now a derived compatibility view. Selected mode
+remains the default.
 
 The translation unit is deliberately one pass of one body rather than one
 stage. A pass owns its binding plan and resource-transform plan, so identical
 stage bytecode can legitimately translate differently when its pass-mates
-differ; sharing at stage granularity would be unsound. Bodies whose pass
-carries byte-identical stage bytecode, semantic bindings, and render states
-therefore share exactly one stored unit. On real uber-shader ship families this
-is the difference between storing every body's programs and storing a small
-fraction of them, because most permutation axes change only one stage of one
-pass.
-
-A body the compiler cannot lower is retained as an explicitly unsupported
-record carrying its reason, and coverage degrades to `partial`. Its complete
-source reflection is untouched, so a partial backend never silently reduces
-source truth. This is the fail-closed alternative to dropping a body or
-shrinking the reported shader count.
+differ; sharing at stage granularity would be unsound. The Carbon wire has no
+unit table. Exact emitted program and backend-block bytes share storage through
+the arena's bytewise deduplication.
+
+All mode first requires the resolved selection to lower successfully. After
+that gate, a later body the compiler cannot lower is retained with empty
+program slots and coverage degrades to `partial`. The in-memory build result
+retains its specific reason; the wire does not. A reread can say only that the
+body carries no translated programs. Permutation topology and representable
+non-program description fields remain present, but source-stage programs are
+not stored. Non-dynamic sampler names are unrecoverable and stage order is
+canonicalized.
 
 Translating every body is deliberately **not** treated as backend completeness.
 `backendComplete` and `runtimeComplete` remain false, matching the sibling
-WebGL package, because neither the engine's realization of these layouts and
-resource transforms nor an exact draw of them has been gated. `INFO` carries
-the honest scope in `backendBodyCoverage` instead.
-
-Evidence for the introducing change: the every-permutation reader join resolves
+WebGL package. The engine now realizes the documented layouts and
+`texture-2d-array` transforms and has exact draw evidence for representative
+Detail and HeatDetail families. That proof does not cover every required
+translated program, layout, and transform, and complete resource hydration and
+selection also remain open. The `BuildEffect` result carries the
+translated-body scope in `info.backendBodyCoverage`; the bytes express it
+structurally through which bodies carry programs.
+
+Historical evidence for the retired WGSB implementation: its
+every-permutation reader join resolved
 every permutation of a real Quad family package to translated programs and
-reaches every unique body; the selected body's shared units are byte-identical
-to that package's own `WGSL` chunk; a full corpus rebuild leaves every
+reached every unique body; the selected body's shared units were byte-identical
+to that package's derived `WGSL` view; a full corpus rebuild leaves every
 selected-mode package byte-identical with unchanged statuses; every effect in
 the corpus builds in all-body mode with no build failures, the small number of
 partial results losing bodies only to already-documented compiler boundaries;
@@ -1418,16 +1436,99 @@ preflight. The synthetic fixtures cannot express either condition, so an
 all-body corpus sweep is part of this feature's verification, not an optional
 extra.
 
+## Consumer boundary: resource transforms
+
+`engine-webgpu` accepts `CJS_WGSL_SET` versions 1, 2 and 3, and realizes
+`texture-2d-array` resource transforms. The discriminator is the **feature**,
+never the document version and never `texture.viewDimension`:
+
+- a **source-declared** `texture_2d_array` keeps every one of its bindings and
+  needs no assembly. Gating on `viewDimension` would reject the very packages
+  the exact draw gate renders — the selected Quad V5 body binds a plain
+  `texture_2d_array<f32>` with no transform, and both Quad families carry
+  `cube` bindings.
+- a **transformed** binding carries `transformId` and `arrayLayerCount`, and its
+  merged-away inputs are absent from the layout. It cannot be fed from one
+  source texture, so the consumer assembles the layers.
+
+Only `kind: texture-2d-array`, `version: 1`,
+`representation: native-or-rgba8`, and `missingLayer: reject` are realized.
+Anything else throws a diagnostic naming the offending field, because the
+failure mode of guessing is WGSL a device accepts and pixels that are quietly
+wrong.
+
+Both halves of the claim are validated, not just the record: exactly one binding
+must carry each declared transform, at the declared output identity, with a
+matching `arrayLayerCount`, a `texture_2d_array<f32>` type, visibility to the
+transform's stage, and **no surviving binding for any merged-away input**. A
+survivor would still be bindable and would silently receive a texture the shader
+never reads. Symmetrically, a binding claiming an undeclared transform, or
+declaring array layers without one, is rejected.
+
+### The analysis is pre-transform; the layout is post-transform
+
+This asymmetry is the one thing a consumer must not get wrong. The reflection
+still lists every declared resource under its own register, including inputs the
+producer merged away; the layout is shorter by exactly those inputs. Checking
+one against the other reports the merge as drift. The merged array occupies the
+**layer-0 input's slot**, which is required rather than assumed, so the binding a
+consumer must fill is unambiguous.
+
+Layers are written in declared order, layer *i* from `inputs[i]`, and must agree
+on size and format because one texture cannot hold layers that do not. A missing
+input is rejected rather than substituted: any stand-in layer would change the
+rendered result while still validating.
+
+Realized and drawn, all with zero WGSL warnings:
+
+| Family | Layers | Merged into | Evidence |
+| --- | --- | --- | --- |
+| `unpackedskinned_quadheatdetailv5` | 2 | `Detail1Map` slot | 22 over 22 bindings, 3 cases, detail changed 570/635 covered pixels |
+| `unpacked_quaddetailv5` | 3 | `Detail1Map` slot | both detail controls changed 1116/1116 covered pixels |
+| `unpackedskinned_quaddetailv5` | 3 | `Detail1Map` slot | 634/635 and 635/635, indexed non-identity bones observed |
+
+The `Detail1` and `Detail2` delta maps were **distinct** in every case. That is
+the assertion that matters: a collapsed or misordered assembly would produce
+identical deltas while still rendering and still validating.
+
+Source-declared array textures are now realized rather than merely accepted:
+the engine creates a layered 2D texture with a `2d-array` view and binds it
+through the same adapter, gated by a synthetic two-layer draw that asserts each
+layer's pixels exactly. A single-layer array view is legal and distinct from a
+plain 2D view, because a shader declaring `texture_2d_array<f32>` needs the
+array view whatever its layer count. A layout asking for the dimension the view
+was not created with fails closed, since a view's dimension is fixed at
+creation and cannot be reinterpreted.
+
+This matters beyond the transform case: the High `.sm_depth` Quad V5 `Main`
+pass binds `LightProfileArray` as a plain `texture_2d_array<f32>` with no
+transform at all, so array-texture realization is a prerequisite for any
+High-tier draw gate, not a detail of transform support.
+
+Array-texture realization is what made transform support possible: the engine
+allocates the array itself and fills layer *i* from `inputs[i]`, which is the
+only way a binding whose other inputs were removed can be filled at all. The
+Detail and HeatDetail family gates draw under this contract. The Environment
+family has not been exercised and should be treated as unverified rather than
+working.
+
+Accepting version 3 also tightened three structural checks that were written
+`=== 2` and would otherwise have silently downgraded every version-3 package to
+version-1 semantics: shared binding identities must span at least two stages,
+and explicit D3D and scope identities are both required. That downgrade would
+have been invisible to the exact draw gate, because DX11 and DX12 downgrade
+identically and the bit-exact comparison would have stayed green.
+
 ## Verification contract
 
 Every shader-emission, layout, or transform compatibility change requires the
 package suite and a representative `engine-webgpu` browser gate on a real
 WebGPU device with zero WGSL warnings. Format-level qualification cannot detect
 every WGSL scoping or validator failure, so browser validation remains part of
-the compiler contract. A reviewed envelope-only schema change may omit a new
-browser run when corpus comparison proves unchanged status/errors and
-byte-identical runtime-consumed shader chunks, and downstream reader tolerance
-is separately confirmed.
+the compiler contract. A reviewed record-layout or derived-view-only change
+may omit a new browser run when corpus comparison proves unchanged
+status/errors and byte-identical runtime-consumed programs/backend blocks, and
+downstream reader tolerance is separately confirmed.
 
 The browser gate proves the emitted WGSL is *valid and runs*; it does not by
 itself prove the translation is *semantically equivalent to D3D*. Semantic

package/docs/formats/wwise.md

@@ -16,22 +16,31 @@ manager behavior, or decoded-backend retention.
 
 `CjsBnkFormat.inspect()` decodes the chunk map, embedded media index, bank
 names, and the HIRC listing with version-stable typed fields (event action
-lists, action type/target, sound and music-track source ids; pinned against
-bank generator version 150). The Wwise-domain toolkit is grouped under the
-`CjsBnkFormat.wwise` static: the SoundbanksInfo catalog helpers, the FNV-1
-id hash, event-to-media resolution, and typed authored-SFX nodes:
+lists, action type/target, sound and music-track source ids). For bank
+generator version 150, recognized Event Actions additionally expose exact
+scope/mode, property and range bundles, delay/transition/probability values,
+fade and action flags, exceptions, and Play bank identities. The
+Wwise-domain toolkit is grouped under the `CjsBnkFormat.wwise` static: the
+SoundbanksInfo catalog helpers, the FNV-1 id hash, event-to-media resolution,
+typed Event Actions, and typed authored-SFX nodes:
 
 ```js
 import { CjsBnkFormat } from "@carbonenginejs/runtime-resource/formats/bnk";
 import { CjsWemFormat } from "@carbonenginejs/runtime-resource/formats/wem";
 
 const inspections = bankByteArrays.map(bytes => CjsBnkFormat.inspect(bytes));
+const action = CjsBnkFormat.wwise.parseEventAction(actionPayload, {
+    bankVersion: 150
+});
 const { eventMedia } = CjsBnkFormat.wwise.eventMediaFromBanks(inspections);
 // eventMedia: Map<eventObjectId, Set<wemId>> - banks may split events from
 // their target sounds, so pass every related bank to one call.
 
 const {
     nodes,
+    nodeBases,
+    actorMixers,
+    attenuations,
     events,
     actions,
     diagnostics
@@ -45,11 +54,28 @@ The read/inspect path stays a pure container reader;
 `wwise.eventMediaFromBanks` is graph interpretation offered for consumers
 with their own engines — the resource lifecycle never calls it.
 
+The undecoded-container ID scan used by `eventMediaFromBanks` is diagnostic
+reachability, not an authoritative playback program. Consumers requiring
+audible correctness should use the typed `sfxNodesFromBanks` graph and fail
+closed for unsupported events.
+
 Typed authored-SFX tail decoding is deliberately pinned to bank generator
-version 150. It preserves Random/Sequence, Switch/State, and Layer fields
-without deciding how an audio runtime should lower them. Unsupported versions,
-failed exact-end anchors, ambiguities, and duplicate object identities are
-reported through `diagnostics` instead of being guessed. Like
+version 150. Recognized Event Actions are accepted only when the whole body
+is consumed; unknown, truncated, other-version, or trailing-byte bodies retain
+their shallow action type/target and raw payload, with `action: null`.
+`nodes` contains playable Sound, Random/Sequence, Switch/State, and Layer
+objects. The separate `nodeBases` map preserves common authored properties
+and positioning facts for playable nodes and Actor-Mixers.
+`actorMixers` contains HIRC type 7 hierarchy objects; they are inheritance
+parents, not playable parallel containers. `attenuations` contains raw HIRC
+type 14 cone data, signed curve-slot assignments, graph points, and RTPCs
+without assigning application meaning to a curve.
+
+Unsupported versions, failed exact-end anchors, ambiguities, NodeBase
+failures, and duplicate object identities are reported through `diagnostics`
+instead of being guessed. Consumers may resolve hierarchy and project
+runtime-specific metadata from these raw facts. In particular, this format
+layer does not infer a numeric maximum radius from an attenuation curve. Like
 `eventMediaFromBanks`, `sfxNodesFromBanks` is consumer-facing graph
 interpretation; the resource lifecycle never calls it.
 

package/docs/reference/classes/core.md

@@ -115,6 +115,86 @@ Internal base for construction-bound readers that are created for one source and
 - Visibility: Internal
 - Kind: Internal implementation class
 
+<!-- class:CjsFormatReadError -->
+## `CjsFormatReadError`
+
+Error raised when shared binary format bytes cannot be decoded safely.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsFormatError.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsFormatWriteError -->
+## `CjsFormatWriteError`
+
+Error raised when shared binary format bytes cannot be encoded safely.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsFormatError.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsByteReader -->
+## `CjsByteReader`
+
+Little-endian cursor over resource bytes, with optional string-table arena resolution.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsByteReader.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsByteWriter -->
+## `CjsByteWriter`
+
+Growable little-endian append cursor with reserve-and-patch support.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsByteWriter.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsStringTable -->
+## `CjsStringTable`
+
+Carbon's compiled-effect string table: a deduplicated blob arena whose offsets are assigned by a bytewise sort rather than by insertion order.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsStringTable.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectBodyReader -->
+## `CjsCarbonEffectBodyReader`
+
+Plain byte cursor over one description blob, carrying the Carbon effect error class and message.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectReader.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectReader -->
+## `CjsCarbonEffectReader`
+
+Reader for Carbon's compiled-effect container at version 15.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectReader.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectWriter -->
+## `CjsCarbonEffectWriter`
+
+Builder for a Carbon compiled-effect container.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectWriter.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
 <!-- class:CjsResourceProbe -->
 ## `CjsResourceProbe`
 

package/docs/reference/classes/formats.md

@@ -79,13 +79,23 @@ Little-endian byte cursor over HIRC payload bytes used to decode Wwise interacti
 - Visibility: Internal
 - Kind: Internal implementation class
 
-<!-- class:SfxCursor -->
-## `SfxCursor`
+<!-- class:WwiseCursor -->
+## `WwiseCursor`
 
-Bounds-aware little-endian cursor used for exact-end Wwise SFX-tail validation.
+Bounds-aware little-endian cursor used for exact Wwise v150 NodeBase, authored-SFX, and attenuation decoding.
 
 - Export: `None`
-- Source: `src/formats/bnk/core/sfxNodes.js`
+- Source: `src/formats/bnk/core/nodeBase.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
+<!-- class:ActionCursor -->
+## `ActionCursor`
+
+Bounds-aware byte cursor used for exact Wwise v150 Event Action decoding.
+
+- Export: `None`
+- Source: `src/formats/bnk/core/eventAction.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 
@@ -843,33 +853,13 @@ WebGPU shader format profile that translates compiled Carbon effects into CEWGPU
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
 
-<!-- class:CewgpuPackage -->
-## `CewgpuPackage`
-
-Reader for the flat CEWGPU container: chunk lookup, cached JSON decoding, and gated portable reflection and backend program access.
-
-- Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/CewgpuPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation class
-
-<!-- class:CewgpuPackageBuilder -->
-## `CewgpuPackageBuilder`
-
-Builds a CEWGPU container from ordered, uniquely tagged chunks.
-
-- Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/CewgpuPackageBuilder.js`
-- Visibility: Internal
-- Kind: Internal implementation class
-
-<!-- class:WebgpuReader -->
-## `WebgpuReader`
+<!-- class:CewgpuContainer -->
+## `CewgpuContainer`
 
-Bounded little-endian byte cursor over CEWGPU container bytes.
+Reader over one WebGPU effect container.
 
 - Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/binary.js`
+- Source: `src/formats/webgpu/core/cewgpu/CewgpuContainer.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 

package/docs/reference/events.md

@@ -34,6 +34,31 @@ wildcard listener dispatch, no `family.event` or ancestor routing, and no
 event payload history. Resource classes may emit their own state or domain
 events, but the emitter does not invent a resource lifecycle contract.
 
+## Resource lifecycle events
+
+`CjsResource.SetState()` supplies the resource-specific lifecycle contract. A
+state transition emits, in order:
+
+1. the lowercase state name with `(resource, ...details)`;
+2. `statechange` with `(resource, nextState, previousState)`; and
+3. `completed` with `(resource, ...details)` when the new state is
+   `prepared` or `failed`.
+
+`purged` is deliberately not completion. A purged handle may re-register and
+reload itself into the same identity, and listeners are not cleared by purge.
+A listener that remains registered for `completed` can therefore observe the
+initial outcome and a later purge/reload outcome.
+
+Raw `OnEvent()` and `OnceEvent()` never replay event history. The one
+state-aware registration helper is `CjsResource.OnCompleted(listener,
+source?)`: it calls the listener synchronously and stores nothing when the
+resource is already complete; otherwise it registers a persistent
+`completed` listener. This is the canonical check-then-subscribe operation for
+late consumers. A listener satisfied synchronously will not observe a later
+reload unless it explicitly subscribes again. Use `Ready()`/`GetObject()` when
+the caller needs a promise for the current load operation rather than a
+re-enterable lifecycle observer.
+
 ## Memory rules
 
 Event storage is the optional `events` member of the emitter's non-enumerable

package/docs/reference/motherlode-cache.md

@@ -27,6 +27,12 @@ create a hidden second resource; reset the affected identity
 (`Delete`/`Clear`) or create a new manager. A changed output contract must use
 a new tag such as `@cmf2`.
 
+Do not restore a hidden execution-plan identity through function fingerprints,
+arbitrary option serialization, `buildKey`, or `buildVersion`. Those details
+cannot create a second canonical resource behind the same public path/output
+promise. A materially different promised result requires an explicit output
+tag.
+
 ## Ownership and replacement
 
 `CjsResMan` resolves each normalized path and promised output to one canonical
@@ -117,10 +123,16 @@ resource.ReleasePayload()
 `CjsResMan` binds resource-facing `KeepAlive()`, `KeepPayloadAlive()`,
 `Lock()`, and `Unlock()` to the resource's canonical MotherLode key.
 `SetPayload()` renews both identity and payload activity when it publishes a
-non-null payload. `GetPayload()`, `HasPayload()`, `IsGood()`, and other
-queries are pure; reading the payload does not implicitly renew its lease.
-Detached and purged handles retain deterministic no-op liveness methods rather
-than silently starting work.
+non-null payload. `GetPayload()`, `HasPayload()`, `IsPrepared()`, and other
+state/payload queries are pure; reading the payload does not implicitly renew
+its lease. `IsGood()` is the deliberate exception: it calls `KeepAlive()`,
+renewing this handle and starting its bounded reload path when it is `PURGED`.
+It does not recursively traverse or renew child resources.
+
+A handle detached by ordinary ownership removal has no live MotherLode
+controller. A purged handle retains the reload hook needed to re-register and
+refill that exact handle, so `IsGood()`/`KeepAlive()` can recover it as
+described under [Ownership and replacement](#ownership-and-replacement).
 
 A released CPU payload retains only the small request needed to reconstruct
 that same path/output from its source and `sourceRevision`. The retained
@@ -249,10 +261,12 @@ operation is still active. Lock release is conditional on the same captured
 ownership generation, so stale work cannot decrement a newly rebound handle's
 lock. Scheduling and active-work protection do not fetch or reload data.
 
-Cache trimming and automatic inactivity sweeps retain the strict no-reload
-rule. Application retention defaults, automatic resource/payload byte
-estimation, separate CPU/adapter budgets, and purged-resource/device-loss
-recovery policy are future work; see the [roadmap](../roadmap.md).
+Cache trimming and automatic inactivity sweeps never fetch or reload as part
+of the sweep itself. A later `IsGood()`/`KeepAlive()` call may recover the
+purged handle through its bounded reload path. Application retention defaults,
+automatic resource/payload byte estimation, and separate CPU/adapter budgets
+remain future work; backend device-loss recovery belongs to the engine
+realization contract. See the [roadmap](../roadmap.md).
 
 ## Related documentation
 

package/docs/reference/workers.md

@@ -82,10 +82,10 @@ invent offset semantics.
 A clone-safe format opts in with a static worker declaration:
 
 ```js
-static worker = Object.freeze({
+static worker = {
   module: import.meta.url,
   exportName: "CjsExampleFormat"
-});
+};
 ```
 
 The worker dynamically imports that exact module and invokes its static
@@ -98,12 +98,12 @@ their class identity.
 A declaration may restrict clone-safe outputs:
 
 ```js
-static worker = Object.freeze({
+static worker = {
   module: import.meta.url,
   exportName: "CjsExampleFormat",
-  outputTypes: Object.freeze([ "json", "payload" ]),
+  outputTypes: [ "json", "payload" ],
   defaultOutput: "json"
-});
+};
 ```
 
 Format options containing functions, symbols, non-plain instances, cycles, or