@carbonenginejs/runtime-resource 0.8.0 → 0.9.0

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)

package/docs/reference/reload.md

@@ -0,0 +1,107 @@
+# Candidate-first atomic reload
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the reload contract that keeps the last published good handle canonical until a distinct candidate has fully succeeded.
+
+## Contract
+
+Reload is candidate-first. When an owner already exists,
+`GetResource(path, { reload: true })` constructs and initializes a distinct
+off-registry candidate without changing ordinary lookup. Calling `Ready()` on
+that candidate, using `GetObject()` / `FetchResource()` with `reload: true`,
+or calling the explicit `ReloadObject()` / `ReloadResource()` helpers starts
+one shared candidate operation that runs the same queued contract:
+
+1. purge-lock the exact former owner and invalidate reusable reads once;
+2. read, convert through the selected format, and publish payload state only
+   on the detached candidate;
+3. require the newest per-key reload token and exact former ownership;
+4. compare-and-swap the fully loaded CPU candidate into MotherLode;
+5. invalidate and clean the displaced handle after the lookup switch.
+
+The manager captures the exact MotherLode, key, former handle, former
+ownership generation, and a newest-request token. Reader, prepare, and
+publication stages mutate only the detached candidate and validate candidate
+authority before and after asynchronous boundaries. A fully loaded CPU
+candidate commits through `CjsMotherLode.ReplaceExpected()` only if the exact
+former owner and newest token still match. The final authority callback and
+exact-record check run immediately before the synchronous map switch, with no
+user cleanup or `await` between the comparison and publication.
+
+After the switch, the displaced ownership generation is invalidated, the
+candidate receives ordinary lifecycle/reconstruction callbacks, and the former
+handle is cleaned exactly once. Existing JavaScript references are not
+retargeted; they keep the displaced handle, while fresh lookup sees the
+committed candidate.
+
+## Failure behavior
+
+Source, format, or publication failure leaves the former handle, state,
+payload, and adapters canonical; the failed candidate's attached payload and
+adapters are cleaned and its original error is retained. An otherwise-
+successful candidate that was superseded, deleted, cleared, or replaced
+rejects with `CJS_RESMAN_STALE_RELOAD_CANDIDATE` and cannot resurrect the
+key. Constructors that return the former singleton are rejected before
+`Initialize()` can mutate it because staging requires a distinct handle.
+
+Failed freshness attempts still invalidate reusable source/format records
+when their work begins; the already-published canonical payload is not
+dependent on those records.
+
+Cleanup errors have explicit sides. Candidate cleanup failure aggregates with
+the original preparation/stale error as
+`CJS_RESMAN_RELOAD_CANDIDATE_CLEANUP_FAILED` while the former owner remains
+canonical. A displaced-owner cleanup failure occurs after publication and
+rejects as `CJS_MOTHERLODE_REPLACE_CLEANUP_FAILED`, whose result explicitly
+reports `committed: true`; the already-good candidate remains canonical.
+
+## Read-cache interaction
+
+`reload: true` synchronously detaches every queued/source/format read record
+for the selected source/path before fresh work starts. Existing consumers
+keep their detached promises; reload does not abort them. Fresh success
+repopulates only caches explicitly requested with `cacheSource: true` or
+`cacheFormat: true`. `InvalidateReadCache(path, { source, sourceRevision })`
+provides the same no-abort invalidation explicitly; omitting
+`sourceRevision` removes all revisions for that source/path. `Delete()`
+remains canonical resource-identity-only, while `Clear()` resets all read
+ledgers. A failed reload preserves the former payload but does not restore
+reusable read-cache entries detached by its explicit freshness request.
+
+## Publication authority and staleness
+
+Every queued, direct, standalone, and candidate resource preparation captures
+an immutable publication authority: the exact MotherLode, canonical key,
+resource handle, and a manager-local ownership generation. The manager
+validates that authority before and after state changes, asynchronous
+reader/format work, and publication. Delete, Clear, successful reload commit,
+or exact-handle reinsertion therefore makes older work reject with
+`CJS_RESMAN_STALE_RESOURCE_OPERATION` before it can enter another state or
+publish. If stale work independently rejects, its original source/format
+error is preserved and `SetError()` is suppressed on the detached handle.
+
+Candidate work is a normal `Wait()` root and blocks synchronous MotherLode
+replacement while active. `Register({ motherLode })` rejects with
+`CJS_RESMAN_ACTIVE_RESOURCE_OPERATIONS` while queued or direct mutations are
+active, including a reload candidate. Normal `Wait()` drains queued roots and
+candidate lineages; a direct caller must await its own load/prepare promise
+before retrying replacement. Canonical and candidate authority prevent late
+publication, but started source or format work is not yet aborted;
+deterministic cleanup applies to the staged candidate resource itself.
+
+## Divergence from Carbon
+
+This availability contract intentionally differs from Carbon.
+`BlueAsyncRes::Reload` cancels/joins work, releases dependent cached data, and
+reloads the same canonical object in place; failure can therefore leave that
+stable handle bad. Carbon MotherLode replacement also switches immediately and
+has no prepare-success gate or rollback. Runtime-resource instead preserves
+the last published good handle until a distinct candidate has succeeded, and
+never silently retargets existing JavaScript references.
+
+## Related documentation
+
+- [MotherLode identity, cache, and retention](motherlode-cache.md)
+- [Queues and the Wait fence](queues.md)

package/docs/reference/texture-arrays.md

@@ -0,0 +1,113 @@
+# Texture arrays and update generations
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the texture-array proxy surface, the requested/prepared revision boundary, and the adapter commit contract.
+
+## Layer proxies
+
+Texture-array resources expose one ordinary-looking proxy per ordered layer:
+
+```js
+const textureArray = new CjsTextureArrayRes({
+  paths: [
+    "res:/detail1.dds",
+    "res:/detail2.dds",
+    "res:/detail3.dds"
+  ],
+  layerNames: [ "Detail1Map", "Detail2Map", "Detail3Map" ],
+  updateScheduler: resource => frameQueue.add(resource)
+});
+
+const detail2 = textureArray.GetLayerParameter(1);
+detail2.SetValue("res:/replacement.dds");
+
+detail2.textureRes === textureArray; // true
+```
+
+Proxy setters only update their source path and invalidate the parent. The
+parent is scheduled once even if several proxies change in the same frame.
+The next-frame consumer calls `Update()` or `ConsumeUpdateRequest()` to
+obtain one immutable ordered snapshot. Runtime-resource does not know which
+shader metadata caused the aggregate request; shader packages and engine
+adapters map public parameter names to layer indices.
+
+Public effect parameters remain separate from these internal proxies. Their
+authored paths and individual 2D source resources are not replaced by the
+aggregate. An engine-owned, non-persisted bridge mirrors public changes into
+the fixed internal layers.
+
+## Update generations
+
+`CjsTextureArrayRes` is a derived multi-source resource with an explicit
+requested/prepared revision boundary:
+
+```text
+proxy/source change
+    -> requested revision + dirty layer
+    -> one scheduled next-frame snapshot
+    -> consumed/in-flight request
+    -> adapter candidate preparation
+    -> guarded adapter + prepared-revision publication
+```
+
+`ConsumeUpdateRequest()` produces an immutable snapshot and marks that
+revision in flight. A current consumed revision may be completed through
+`CommitPreparedAdapterRevision()`, failed through `FailUpdateRequest()`, or
+returned to the queue through `RetryUpdateRequest()`. Commit-before-consume
+and stale commits are rejected; rejected candidate allocations are destroyed
+by default.
+
+Publication installs the adapter allocation and prepared revision before
+completion events run. The result returns the displaced allocation to the
+adapter owner for post-publication destruction. A reentrant source change may
+therefore request a newer revision without allowing stale completion to
+replace it. The previous prepared allocation and `IsGood()` remain usable
+while a replacement is pending or if replacement preparation fails.
+
+`Ready()` is specialized for this derived resource: it resolves when the
+generation requested at call time has been published, rather than delegating
+to a single-source object loader. Initial preparation failure rejects it.
+
+## Adapter commit example
+
+Consumed snapshots are explicit in-flight generations. An adapter either
+publishes the current candidate atomically, requeues retryable work, or
+records failure:
+
+```js
+const request = textureArray.ConsumeUpdateRequest();
+
+try {
+  const candidate = await adapter.PrepareTextureArray(request);
+  const result = textureArray.CommitPreparedAdapterRevision(
+    request.revision,
+    "webgpu",
+    candidate
+  );
+
+  // A rejected/stale candidate is destroyed by the commit method by default.
+  // The adapter owns disposal of a successfully displaced allocation.
+  result.displaced?.destroy();
+} catch (error) {
+  textureArray.FailUpdateRequest(request.revision, error, { retry: true });
+}
+
+await textureArray.Ready(); // the generation requested at call time
+```
+
+## Sources and topology
+
+Logical paths and resolved sources are independent. `SetLayerResource()`
+attaches a resolved or LOD-specific source without rewriting the logical
+requested path or persistence. `TouchLayer()` invalidates an in-place source
+revision. `HandleAdapterLoss()` drops an unusable adapter allocation and
+schedules a complete topology rebuild. Topology-changing snapshots set
+`topologyChanged: true` and report only valid current layer indices in
+`dirtyLayers`.
+
+## Related documentation
+
+- [Architecture and boundaries](../architecture.md)
+- [Texture CPU pipeline and LOD membership](texture-pipeline.md)