@carbonenginejs/runtime-resource 0.7.0 → 0.9.0

package/{FORMAT-PROVENANCE.md → docs/formats/provenance.md}

@@ -1,5 +1,10 @@
 # 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`. Their standalone repositories remain frozen with
 their existing APIs and names; they are not upstreams for the runtime copies.
@@ -35,6 +40,20 @@ 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 copied engine keeps its donor class name (`CjsFormatGr2`, re-exported)
+under `formats/gr2/core/`; `CjsGr2Format` is the runtime-authored contract
+wrapper. 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
@@ -64,6 +83,17 @@ format attribution rather than fork provenance.
 
 ## 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
@@ -78,7 +108,7 @@ format attribution rather than fork provenance.
   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; `E:\carbonengine\mesh\{include,src}\cmf` was the behavioral
+  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 —
@@ -120,10 +150,9 @@ snapshot must record its new source and digest here.
 
 ## Deliberately not copied
 
-- `format-gr2` is the intended runtime-resource owner target, but its current
-  BitKnit-derived implementation is EUPL-1.2. It remains separate and active
-  until that code is replaced or an explicit distribution-license decision is
-  made. It has not been deprecated or relabeled as MIT.
+- `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` remains the schema emitter/generator and build-time schema
   authority. Black consumes its published definitions; Red exposes the copied
   catalog but does not yet enforce it while reading YAML fields.

package/docs/formats/stl.md

@@ -0,0 +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)

package/docs/formats/wwise.md

@@ -0,0 +1,44 @@
+# Wwise soundbanks and media
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/bnk`, `@carbonenginejs/runtime-resource/formats/wem`  
+Audience: Users and integrators  
+Summary: Defines the Wwise container inspection, event/media graph extraction, and WEM conversion contracts.
+
+## Scope
+
+`formats/bnk` and `formats/wem` cover Wwise container inspection, event/media
+graph extraction, embedded-member access, and the currently supported WEM
+conversion routes. They do not own AudioBuffer construction, playback, audio
+manager behavior, or decoded-backend retention.
+
+## Soundbank inspection
+
+`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, and event to media resolution:
+
+```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 { 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 ogg = CjsWemFormat.toOgg(wemBytes);   // Wwise Vorbis -> Ogg (lossless)
+const pcm = CjsWemFormat.toPcm(wemBytes);   // PTADPCM / 16-bit PCM -> float32
+```
+
+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.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Format ownership and fork provenance](provenance.md)

package/docs/reference/events.md

@@ -0,0 +1,92 @@
+# Event emitter contract
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the `CjsEventEmitter` API surface used by resource managers and the memory rules that keep listeners from leaking graphs.
+
+## Purpose
+
+`CjsEventEmitter` (from `core-types/model`) is a separate base class so
+non-model runtime services can emit events without extending `CjsModel`;
+`CjsResMan` uses that path. CarbonEngineJS exposes one small event-emitter API
+and avoids short generic names such as `On`, `Once`, `Off`, and `Emit` on
+Carbon-shaped classes. There is no separate resource notification/callback
+compatibility layer beside events, and no listener scopes, subscription
+handles, or owner-side `ListenTo()` helpers.
+
+## API
+
+- `AddEvents(events)`
+- `OnEvent(eventName, listener, source?)`
+- `OnceEvent(eventName, listener, source?)`
+- `OffEvent(eventName = "*", listener?, source?)`
+- `EmitEvent(eventName, ...args)`
+- `HasEvent(eventName = "*", listener?, source?)`
+- `ClearEvent(eventName = "*")`
+- `GetEventNames()` and `GetEventListenerCount(eventName = "*")`
+
+The optional `source` is the callback's `this` value and an explicit matching
+identity for removal. Mutating event methods return the emitter for chaining.
+Event names are normalized to lowercase and dispatched by exact match.
+Wildcard names are accepted only by lookup and cleanup methods; there is no
+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.
+
+## Memory rules
+
+Event storage is the optional `events` member of the emitter's non-enumerable
+`__state` object:
+
+```text
+emitter.__state (non-enumerable, allocated only when some subsystem needs it)
+  events -> eventName -> Set<listenerRecord>
+
+listenerRecord
+  emitter
+  eventName
+  listener
+  source
+  once
+```
+
+The event map is created only when the first listener is registered and
+deleted when the last record is removed. That does not make listeners weak:
+as long as an emitter is reachable, its event map strongly references
+listener functions and sources, and those listeners can keep whole
+scene/resource graphs alive. The contract is therefore:
+
+- `OnceEvent()` removes the listener on first dispatch, even if the callback
+  throws.
+- `OffEvent(eventName, listener, source)` removes the exact listener/source
+  entry; `target.OffEvent("*", null, source)` removes all of a source's
+  records. An external party that no longer observes a target must call
+  `OffEvent()`.
+- `Unload()` and `Purge()` are resource state/cache operations, not an
+  implied listener-destruction lifecycle.
+- `OnEvent()` returns the emitter; it does not return unsubscribe closures,
+  because those closures create another reference path.
+- Deterministic cleanup is the contract; `WeakRef`/`FinalizationRegistry` may
+  help diagnostics but are not a lifecycle mechanism.
+
+Multiple listeners on the same event are allowed because each event bucket is
+a set of records. A raw `CjsEventEmitter` does not gain model-owned `dirty`
+or `rebuild` state. The target is "easy to debug, hard to leak": clear
+ownership of who subscribed, who unsubscribes, and which cleanup phase clears
+remaining listeners.
+
+## Relationship to model dirty state
+
+`CjsModel` has dirty-state helpers (`MarkDirty`, `ClearDirty`, `ConsumeDirty`,
+`GetDirtyNotifications`) for model invalidation. `SetValues()` compares
+incoming values with the current field values and only marks dirty when a
+value actually changes. A plain `MarkDirty()` means broad dirty invalidation;
+it does not request a rebuild, and deferred rebuild reasons belong to the
+independent `model.__state.rebuild` set. That model machinery is not a
+resource lifecycle event system; resource lifecycle events remain a
+resource/resman concern.
+
+## Related documentation
+
+- [MotherLode identity, cache, and retention](motherlode-cache.md)

package/docs/reference/motherlode-cache.md

@@ -0,0 +1,244 @@
+# MotherLode identity, cache, and retention
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines canonical resource identity, ownership and replacement, the recorded-byte cache, payload retention, read-cache provenance, and purge contracts.
+
+## Canonical identity
+
+Canonical resource identity is the normalized source path plus its promised
+output tag. `variant` is the explicit tag; otherwise `emit`, `requirement`, or
+`payload` supplies it. Human-readable identities are written as
+`res:/ship.gr2@cmf`, although MotherLode uses an internal delimiter. Reader,
+constructor, and format-option implementations never enter the key. CjsLibrary
+chooses the promised output and ResMan executes the current setup-time format
+registration for it.
+
+Output selection is case-insensitive for identity and matching, but format
+readers receive the canonical declared spelling (for example `cmfJson`). A
+legacy direct object loader exposes only its unforced default; named output
+variants belong on a format class. Unsupported `@output` requests fail before
+cache lookup, so a resident handle cannot bypass the declaration.
+
+The selected constructor, reader, and format defaults/options are setup-time
+execution details, not MotherLode identity. A changed registration does not
+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`.
+
+## Ownership and replacement
+
+`CjsResMan` resolves each normalized path and promised output to one canonical
+MotherLode key. `Insert(key, resource, options)` reports `{ inserted,
+replaced, displaced }`; replacement, deletion, clearing, and shutdown destroy
+attached adapter allocations and release the complete CPU payload by default.
+Callers that deliberately retain ownership may pass `{ cleanup: false }` and
+keep the returned displaced resource. If replacement cleanup fails, insertion
+throws a contextual error and leaves the existing owner registered. These
+ordinary ownership removals preserve the handle's last resource state;
+`PURGED` is reserved for successful policy eviction through inactivity or
+byte pressure.
+
+`Startup()` and `Shutdown()` are idempotent. `HasKey`, `Lookup`, `Delete`,
+`GetKeys`, `GetValues`, `GetSize`, `SetCacheSize`, `GetCacheSize`, `GetStats`,
+`TrimCache`, `ReplaceExpected`, `Clear`, and `ClearCached` provide the
+Carbon-shaped cache vocabulary plus the exact-owner compare-and-swap required
+by staged JavaScript reload. The old `Has`, `GetCount`, and `DeleteAll` names
+remain temporary compatibility aliases.
+
+## Recorded-byte cache
+
+Carbon can infer when only its cache retains a resource through
+weak-reference and refcount transitions. JavaScript cannot reproduce that
+ownership test reliably, so `CjsMotherLode` budgets only entries that a caller
+explicitly classifies with `{ cached: true, bytes }`; JavaScript reachability
+is never inferred. The byte value is an exact caller-supplied safe-integer
+eviction weight, not a heuristic walk of the resource graph; runtime-resource
+does not walk arbitrary cyclic/shared object graphs or invoke payload getters
+to guess size.
+
+Explicit cached entries receive a monotonic admission sequence. With default
+cleanup, `TrimCache(options)` destroys adapters, releases payloads, detaches
+lifecycle callbacks, marks compatible handles `PURGED`, and removes
+positive-byte cached identities in oldest-admission order until
+`cacheBytes <= cacheSize`. Live, locked, `cacheable: false`, and zero-byte
+entries do not create pressure. `KeepAlive()` and `Lock()` promote a cached
+record to live; `Unlock()` does not silently re-admit it.
+
+`SetCacheSize(bytes, options)` installs and immediately enforces the new
+budget. `CjsResMan.Update()` and `Tick()` retry cache housekeeping after
+pumping queues; `{ cache: false }` skips it for one update without changing
+policy. Cleanup is transactional per identity: a failed candidate remains
+canonical, later candidates are still attempted, and the aggregate
+`CJS_MOTHERLODE_CACHE_TRIM_FAILED` error carries successful evictions and any
+remaining over-budget state. Trimming never reads, prepares, or reloads data.
+
+## Payload retention
+
+Reader and converter outputs are plain transient payload objects, not resource
+classes or DTO models. A payload may contain more decoded data than a
+particular resource or engine adapter needs. Each concrete resource validates
+the fields it requires before publishing the payload and retains the scalars
+and references it needs. An adapter may retain additional references in
+adapter-owned state. Referencing payload-owned typed arrays is valid and
+preferable to copying them merely to change ownership.
+
+The lifecycle treats resource residency and payload residency independently:
+
+```text
+resource.KeepAlive()
+    -> renew resource/cache residency
+
+resource.KeepPayloadAlive()
+    -> renew the attached payload lease
+
+resource.ReleasePayload()
+    -> explicitly release the full payload reference
+```
+
+`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.
+
+A released CPU payload retains only the small request needed to reconstruct
+that same path/output from its source and `sourceRevision`. The retained
+promised-output fields and source provenance win over later
+`Ready()`/`GetObject()` overrides, while cache/reload policy remains per-call.
+Payload leases protect active consumers; an engine may release its own backend
+adapter without destroying shared CPU data.
+
+Both semantic and generic/base resource results use the payload slot: the
+manager stores the complete result through `SetPayload()` and mirrors it on
+the compatibility `object` property for base resources. Payload release clears
+that alias only while it still identifies the released value. Semantic
+resources continue to expose `object === resource` while holding their
+validated plain payload privately.
+
+Object-operation promises are retained only while in flight. Concurrent
+`GetObject()`/`Ready()` calls share one operation; a resident result is
+returned without source work and renews the explicit payload lease.
+Settlement removes the operation record so its result graph can be reclaimed
+and a failure can be retried. After payload release, only a new explicit
+object/readiness call reconstructs it; queries, lease calls, and purge sweeps
+do not.
+
+The processor preparing a resource decides when the full payload can be
+released:
+
+```text
+format reader -> plain payload -> resource validation + adapter prepare
+                                   |
+                                   +-> resource retains required values/references
+                                   +-> adapter retains adapter-specific state/references
+                                   +-> release payload after successful preparation
+                                   `-> or renew its lease for deferred/further work
+```
+
+A time- or frame-based lease is a fallback against abandoned payloads. An
+owner performing deferred work can renew the lease. If an expired payload is
+required again, the caller must explicitly request reconstruction; lease
+renewal and purging never fetch or reload source data. Dynamic or
+non-reloadable resources must remain locked, retain the required payload, or
+be able to recreate it.
+
+Payload references are shared read-only by default. Preparing WebGL and
+WebGPU adapters side by side should normally pass the same payload to both
+consumers and retain it until both have finished. Copying is an explicit
+consumer operation, justified when a consumer must mutate data, transfer and
+detach an `ArrayBuffer`, or retain an independently writable snapshot. The
+consumer should copy only the fields it requires; runtime-resource does not
+automatically deep-clone payload or typed-array bundles.
+
+## Read-cache provenance
+
+Source and parsed-format caches use explicit provenance, separate from
+path/output resource identity. `sourceRevision` is an opaque caller/source-
+supplied string or finite number identifying source content for one source
+object and normalized path. It scopes read caches only; it does not alter
+MotherLode resource identity, and changing it does not replace a resident
+payload without `reload: true`. Source and format records do not share across
+revisions.
+
+`cacheSource` and `cacheFormat` are tri-state per-call policies:
+
+- omitted: share in-flight or explicitly retained work, then drop a newly
+  completed record;
+- `true`: share and retain success; a joining caller upgrades the record;
+- `false`: bypass sharing and retention.
+
+Failures are never retained. Format records are additionally isolated by
+selected source object, frozen registration descriptor, revision, and
+effective format options, so another source or a re-registered default cannot
+reuse a stale parse. Re-registering a format with new defaults therefore
+cannot reuse an old descriptor's parse. Registered defaults are copied into
+deeply frozen plain-object/array snapshots. Material format options that
+cannot be represented safely (for example class instances with hidden mutable
+state) bypass format-cache sharing instead of risking a false match;
+functions and byte views use cache-local identity plus visible byte content
+where applicable.
+
+A resource loader retains the effective selected source and `sourceRevision`
+for reconstruction, including the manager default selected at creation, but
+not cache flags or one-shot reload.
+
+## Explicit and automatic purging
+
+`PurgeInactive(options)` performs an explicit deterministic sweep using
+independent identity and payload frame/time limits. Locks skip both forms of
+eviction. Identity expiry destroys adapter resources, releases the payload,
+detaches lifecycle callbacks, marks compatible handles `PURGED`, and removes
+the canonical key; payload expiry calls `ReleasePayload()` while retaining
+identity and adapter allocations. Candidate failures are aggregated after the
+sweep has continued over other entries. A sweep never fetches, prepares, or
+reloads a resource.
+
+Automatic scheduling is available only when a caller supplies
+`autoPurgePolicy` to the constructor/`Register()` or calls
+`SetAutoPurgePolicy()`. It is disabled by default and deliberately accepts
+only millisecond limits: MotherLode activity frames count explicit
+observations and are not renderer frames. A policy must set at least one of
+`maxIdleMilliseconds` or `payloadMaxIdleMilliseconds`;
+`intervalMilliseconds` defaults to 1000. The first
+`PumpAutoPurge()`/`Update()` after configuration sweeps immediately, then the
+interval sets the minimum cadence. `Update({ purge: false })` suppresses a
+sweep for one update without changing cadence. A regressing clock rebases and
+skips one pump; custom deterministic clocks should be shared with MotherLode.
+Recorded-byte cache trimming is separate from this opt-in inactivity policy
+and runs on ordinary updates unless `{ cache: false }` is supplied.
+
+```js
+const resMan = new CjsResMan({
+  source,
+  autoPurgePolicy: {
+    intervalMilliseconds: 1000,
+    maxIdleMilliseconds: 60_000,
+    payloadMaxIdleMilliseconds: 10_000
+  }
+});
+
+resMan.Update();
+```
+
+Both queued `QueueResourceObject()` work and direct `LoadResourceObject()`
+work hold one manager-owned lock from request/loading publication through
+success or failure. The lock is balanced independently of caller locks, so
+automatic or manual sweeps cannot detach a handle while its read/prepare
+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).
+
+## Related documentation
+
+- [Resource lifecycle concepts](../concepts/resource-lifecycle.md)
+- [Candidate-first atomic reload](../reference/reload.md)
+- [Queues and the Wait fence](../reference/queues.md)

package/docs/reference/queues.md

@@ -0,0 +1,102 @@
+# Queues, publication, and the Wait fence
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the two manager-owned queues, publication budgeting, registration, and the `Wait()` fence semantics.
+
+## Queued CPU load and publication
+
+`GetObject()`, `LoadObject()`, and resource `Ready()` use two manager-owned
+queues:
+
+```text
+BACKGROUND: deduplicated source load, limited by maxConcurrentLoads
+MAIN:       reader/format conversion -> resource publication
+```
+
+The main reader/format operation and publication are separate queue items.
+`maxPrepareTime` is a per-pump budget in seconds limiting synchronous
+main-queue work started in one pump, and `maxPrepareItemsPerTick` can add an
+item-count limit. Promise-returning format work remains in flight without
+blocking the JavaScript event loop. The default scheduler keeps promise-based
+calls working; a `CjsLibrary` or direct caller can provide its frame
+scheduler:
+
+```js
+const resMan = new CjsResMan({
+  source,
+  maxConcurrentLoads: 8,
+  maxPrepareTime: 0.005,
+  queueScheduler: callback => requestAnimationFrame(callback)
+});
+
+await resMan.FetchResource("res:/model/ship.gr2", {
+  requirement: "geometry",
+  emit: "cmf"
+});
+```
+
+The selected format class owns conversion to the promised CPU output.
+`CjsResMan` does not inspect WebGL, WebGPU, texture, geometry, or codec
+support, and it does not run backend realization. An engine consumes the
+published CPU resource afterward through its own explicit operation.
+
+## Queue controls
+
+Blue-compatible queue controls are exposed directly on `CjsResMan`:
+`AddToQueue`, `CancelFromQueue`, `GetNextIdForQueue`, `PumpMainThreadQueue`,
+`PauseQueue`, `ResumeQueue`, `GetPendingLoads`, and `GetPendingPrepares`.
+`Update()`/`Tick()` pump work.
+
+## The Wait fence
+
+`Wait()` synchronously captures queued resource-operation roots and low-level
+queue tasks that already exist when it is called. Captured resource roots
+include publication work enqueued after an asynchronous read; unrelated later
+roots/tasks do not postpone the fence. Failure and queued cancellation count
+as settlement, remain observable through their original operation promises,
+and cross the fence without making `Wait()` reject.
+
+By default `Wait()` pumps the two queues directly within their ordinary
+budgets and never runs automatic purge housekeeping. It preserves pause
+state; `{ pump: false }` leaves all progress to an external driver. A
+standalone canonical `PrepareResourceObjectQueued()` call is a queued root.
+Direct `LoadResourceObject()`, direct `PrepareResourceObject()`, standalone
+`ReadResource()`, and standalone `ReadFormatOnce()` calls bypass both queues
+and are outside this fence unless they own a captured queue task, although
+direct resource mutations are still tracked for safe MotherLode replacement.
+`WaitUrgent()` remains deferred until the queue has real per-item priority
+and urgent-membership semantics.
+
+## Registration
+
+Format classes own input extensions. Resource classes are registered by a
+semantic requirement, never by file extension:
+
+```js
+const resMan = new CjsResMan().Register({
+  source,
+  formats: [ CjsDdsFormat, CjsPngFormat ],
+  resourceTypes: [ TriTextureRes, Tr2ImageRes ]
+});
+
+const texture = resMan.GetResource("res:/image/ship.png", {
+  requirement: "texture",
+  emit: "image"
+});
+const image = resMan.GetResource("res:/image/ship.png", {
+  requirement: "image",
+  emit: "image"
+});
+```
+
+Those are distinct resource identities but share the normalized source-byte
+operation. The manager does not expose an extension-to-resource compatibility
+registry.
+
+## Related documentation
+
+- [Resource lifecycle concepts](../concepts/resource-lifecycle.md)
+- [MotherLode identity, cache, and retention](motherlode-cache.md)
+- [Format subpaths](../formats/README.md)