@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

package/docs/concepts/resource-lifecycle.md

@@ -1,225 +1,226 @@
-# Resource lifecycle
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Explains resource states, the load/prepare split, and how a resource request flows from path to published CPU payload.
-
-## Carbon and ccpwgl background
-
-Carbon's resource model separates load from prepare. The source schemas expose
-resource classes through `BlueAsyncRes`, and Carbon notes distinguish
-background load work from main-thread/device prepare work.
-
-ccpwgl makes that split visible in `Tw2Resource`:
-
-```text
-NO_INIT -> REQUESTED -> LOADED -> PREPARED
-```
-
-Additional terminal or cleanup states include `ERROR`, `UNLOADED`, and
-`PURGED`. The important behavior is:
-
-- `Tw2ResMan.LoadResource()` requests a resource.
-- The raw fetch resolves.
-- `Tw2Resource.OnLoaded()` marks bytes or source data as loaded.
-- The resource is queued for prepare.
-- The manager tick later calls `res.Prepare(data)`.
-- The concrete resource calls `OnPrepared()` after prepare work succeeds.
-
-Some ccpwgl concrete `Prepare()` implementations also create WebGL objects.
-That is a historical engine/runtime coupling, not the boundary CarbonEngineJS
-keeps; see [architecture](../architecture.md).
-
-## CarbonEngineJS states
-
-```text
-EMPTY -> REQUESTED/LOADING -> LOADED          (runtime-resource)
-LOADED -> PREPARING -> PREPARED               (engine adapters)
-```
-
-- `EMPTY`: resource identity exists, but no payload has been read.
-- `REQUESTED`: the resource is waiting on a queued or shared source load.
-- `LOADING`: source bytes are available and CPU reader/format work is active.
-- `LOADED`: CPU payload or hydrated object graph exists.
-- `PREPARING`: an engine adapter is realizing backend-owned resources.
-- `PREPARED`: preparation completed successfully and the resource is usable.
-- `FAILED`: CPU loading, conversion, validation, or publication failed before
-  a valid payload was published.
-- `UNLOADED`: resource payload was released.
-- `PURGED`: an inactivity or recorded-byte cache policy evicted the resource
-  from active ownership. Ordinary replacement, `Delete()`, `Clear()`,
-  `ClearCached()`, and shutdown clean owned payloads/adapters but preserve the
-  detached handle's last valid state.
-
-`CjsResMan.LoadObject()` queues one deduplicated background source operation
-per source/path and limits active source operations with
-`maxConcurrentLoads`. After bytes arrive, object construction is split into
-separate main-queue items (`reader/format conversion -> publish`). Publication
-moves the resource to `LOADED`, then stops. ResMan never performs backend
-realization or marks the resource `PREPARED`/`GOOD`. See
-[reference/queues.md](../reference/queues.md) for the queue contract and
-[reference/motherlode-cache.md](../reference/motherlode-cache.md) for
-identity, retention, and release behavior.
-
-## Request workflow
-
-The normal direct resource-path flow is:
-
-```text
-Application / runtime object
-        |
-        | requests "res:/model/ship.gr2"
-        | with optional per-request overrides
-        v
-+-----------------------------------------------+
-| CjsLibrary                                    |
-|                                               |
-| - starts from registered default behavior     |
-| - considers registered capability reports     |
-| - chooses requirement / emit / format         |
-| - applies explicit request overrides          |
-+-----------------------------------------------+
-        |
-        | path + resolved request options
-        v
-+-----------------------------------------------+
-| CjsResMan.GetResource(path, options)          |
-|                                               |
-| - normalize source path and extension         |
-| - resolve the promised output tag             |
-+-----------------------------------------------+
-        |
-        v
-+-----------------------------------------------+
-| CjsMotherLode.Lookup(resolved key)             |
-+-----------------------------------------------+
-        |
-        +--- cache hit ------------------------------+
-        |                                             |
-        |    reuse the CjsResource and any active     |
-        |    load/build operation                     |
-        |                                             |
-        `--- cache miss -----------------------------+
-              |                                       |
-              | resolve class from requirement        |
-              | construct + Initialize()              |
-              | insert into CjsMotherLode              |
-              v                                       |
-        new CjsResource -------------------------------+
-        |
-        | Ready() / GetObject()
-        v
-+===============================================+
-| BACKGROUND LOAD QUEUE                         |
-|                                               |
-| - mark resource REQUESTED                     |
-| - share one source operation per source/path  |
-| - obey maxConcurrentLoads                     |
-| - CjsResMan builds URL when provider needs it |
-| - provider.Read(sourcePath)                   |
-+===============================================+
-        |
-        | source bytes
-        v
-+===============================================+
-| MAIN PREPARE QUEUE                            |
-|                                               |
-| every box below is a separately budgeted item |
-+===============================================+
-        |
-        v
-+-----------------------------------------------+
-| Read stage                                    |
-|                                               |
-| current object loader for extension?          |
-|   yes -> call it                              |
-|   no  -> resolve registered formats by        |
-|          bytes + request options               |
-+-----------------------------------------------+
-        |
-        | plain payload / hydrated object
-        v
-+-----------------------------------------------+
-| Publish stage                                 |
-|                                               |
-| semantic resource -> SetPayload(payload)      |
-| generic resource  -> SetPayload(value)        |
-|                      object aliases payload   |
-+-----------------------------------------------+
-        |
-        +--- validation failure --------------------+
-        |                                            |
-        |    resource -> FAILED                      |
-        |    Ready() rejects                         |
-        |                                            |
-        `--- publication succeeds -----------------+
-                    |
-                    | resource -> LOADED
-                    v
-             CjsLibrary returns
-             the built CjsResource/object
-```
-
-Device realization is a separate continuation selected outside ResMan. It can
-run again after adapter eviction or device loss while the CPU payload remains
-resident:
-
-```text
-CjsResource LOADED
-        |
-        | selected engine adapter
-        v
-PREPARING
-        |
-        | create candidate -> verify current target -> synchronous attach
-        v
-PREPARED
-
-failure: destroy candidate -> LOADED (CPU payload retained)
-```
-
-## Retention model
-
-ccpwgl keeps every resource in `Tw2MotherLode` until it is explicitly cleared
-or auto-purged, and its `IsGood()` implicitly calls `KeepAlive()`, so many
-read/check paths keep resources resident. CarbonEngineJS retains that behavior
-for the resource being queried, while keeping payload retention and hard locks
-explicit:
-
-- `IsGood()` calls `KeepAlive()` before checking preparation. It renews this
-  handle and starts its bounded reload path when the handle is `PURGED`.
-- `IsPrepared()` and `HasLoaded()` remain pure state checks.
-- `KeepAlive()` and `KeepPayloadAlive()` are the explicit liveness operations.
-- `Lock()` / `Unlock()` maintain a non-underflowing count and prevent identity
-  and payload eviction during a sweep.
-- MotherLode tracks separate identity and CPU-payload frame/time observations.
-- `CjsMotherLode.PurgeInactive()` scans only when explicitly requested and
-  never infers JavaScript reachability. `CjsResMan.Update()` may request it
-  only under an explicitly configured automatic policy.
-
-Generic liveness never walks arbitrary child fields. `IsGood()` renews only the
-handle on which it is called; an aggregate consumer that owns child resources
-must query or retain those children explicitly.
-
-The CPU/GPU split adds an axis that ccpwgl blurs: CPU payload memory and
-device memory are different budgets. Retention therefore distinguishes:
-
-- resource identity: path, extension, state, error summary, lightweight
-  metadata;
-- CPU payload: plain reader/converter objects, hydrated object graphs, decoded
-  typed arrays;
-- adapter payload: WebGL/WebGPU textures, buffers, shader modules, pipelines.
-
-Identity and lightweight metadata stay resident while CPU payloads and adapter
-payloads release independently. Engine adapters own adapter-resource
-destruction; runtime-resource provides lifecycle hooks and opaque adapter
-slots so cleanup has a consistent place to run. The exact contracts live in
-[reference/motherlode-cache.md](../reference/motherlode-cache.md).
-
-## Related documentation
-
-- [Architecture and boundaries](../architecture.md)
-- [MotherLode identity, cache, and retention](../reference/motherlode-cache.md)
-- [Candidate-first atomic reload](../reference/reload.md)
-- [Queues and the Wait fence](../reference/queues.md)
+# Resource lifecycle
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Explains resource states, the load/prepare split, and how a resource request flows from path to published CPU payload.
+
+## Carbon and ccpwgl background
+
+Carbon's resource model separates load from prepare. The source schemas expose
+resource classes through `BlueAsyncRes`, and Carbon notes distinguish
+background load work from main-thread/device prepare work.
+
+ccpwgl makes that split visible in `Tw2Resource`:
+
+```text
+NO_INIT -> REQUESTED -> LOADED -> PREPARED
+```
+
+Additional terminal or cleanup states include `ERROR`, `UNLOADED`, and
+`PURGED`. The important behavior is:
+
+- `Tw2ResMan.LoadResource()` requests a resource.
+- The raw fetch resolves.
+- `Tw2Resource.OnLoaded()` marks bytes or source data as loaded.
+- The resource is queued for prepare.
+- The manager tick later calls `res.Prepare(data)`.
+- The concrete resource calls `OnPrepared()` after prepare work succeeds.
+
+Some ccpwgl concrete `Prepare()` implementations also create WebGL objects.
+That is a historical engine/runtime coupling, not the boundary CarbonEngineJS
+keeps; see [architecture](../architecture.md).
+
+## CarbonEngineJS states
+
+```text
+EMPTY -> REQUESTED/LOADING -> LOADED          (runtime-resource)
+LOADED -> PREPARING -> PREPARED               (engine adapters)
+```
+
+- `EMPTY`: resource identity exists, but no payload has been read.
+- `REQUESTED`: the resource is waiting on a queued or shared source load.
+- `LOADING`: source bytes are available and CPU reader/format work is active.
+- `LOADED`: CPU payload or hydrated object graph exists.
+- `PREPARING`: an engine adapter is realizing backend-owned resources.
+- `PREPARED`: preparation completed successfully and the resource is usable.
+- `FAILED`: CPU loading, conversion, validation, or publication failed before
+  a valid payload was published.
+- `UNLOADED`: resource payload was released.
+- `PURGED`: an inactivity or recorded-byte cache policy evicted the resource
+  from active ownership. Ordinary replacement, `Delete()`, `Clear()`,
+  `ClearCached()`, and shutdown clean owned payloads/adapters but preserve the
+  detached handle's last valid state.
+
+`CjsResMan.LoadObject()` queues one deduplicated background source operation
+per source/path and limits active source operations with
+`maxConcurrentLoads`. After bytes arrive, object construction is split into
+separate main-queue items (`reader/format conversion -> publish`). Publication
+moves the resource to `LOADED`, then stops. ResMan never performs backend
+realization or marks the resource `PREPARED`/`GOOD`. See
+[reference/queues.md](../reference/queues.md) for the queue contract and
+[reference/motherlode-cache.md](../reference/motherlode-cache.md) for
+identity, retention, and release behavior.
+
+## Request workflow
+
+The normal direct resource-path flow is:
+
+```text
+Application / runtime object
+        |
+        | requests "res:/model/ship.gr2"
+        | with optional per-request overrides
+        v
++-----------------------------------------------+
+| CjsLibrary                                    |
+|                                               |
+| - starts from registered default behavior     |
+| - considers registered capability reports     |
+| - chooses requirement / emit / format         |
+| - applies explicit request overrides          |
++-----------------------------------------------+
+        |
+        | path + resolved request options
+        v
++-----------------------------------------------+
+| CjsResMan.GetResource(path, options)          |
+|                                               |
+| - normalize source path and extension         |
+| - resolve the promised output tag             |
+| - capture the registered extension route      |
++-----------------------------------------------+
+        |
+        v
++-----------------------------------------------+
+| CjsMotherLode.Lookup(resolved key)             |
++-----------------------------------------------+
+        |
+        +--- cache hit ------------------------------+
+        |                                             |
+        |    reuse the CjsResource and any active     |
+        |    load/build operation                     |
+        |                                             |
+        `--- cache miss -----------------------------+
+              |                                       |
+              | semantic class or extension Handler   |
+              | construct + Initialize()              |
+              | insert into CjsMotherLode              |
+              v                                       |
+        new CjsResource -------------------------------+
+        |
+        | Ready() / GetObject()
+        v
++===============================================+
+| BACKGROUND LOAD QUEUE                         |
+|                                               |
+| - mark resource REQUESTED                     |
+| - share one source operation per source/path  |
+| - obey maxConcurrentLoads                     |
+| - CjsResMan builds URL when provider needs it |
+| - provider.Read(sourcePath)                   |
++===============================================+
+        |
+        | source bytes
+        v
++===============================================+
+| MAIN PREPARE QUEUE                            |
+|                                               |
+| every box below is a separately budgeted item |
++===============================================+
+        |
+        v
++-----------------------------------------------+
+| Read stage                                    |
+|                                               |
+| explicit extension route?                     |
+|   yes -> ordered Formats/content probes        |
+|   no  -> direct loader or legacy formats       |
+| target/identify -> hydrate on caller thread   |
++-----------------------------------------------+
+        |
+        | plain payload / hydrated object
+        v
++-----------------------------------------------+
+| Publish stage                                 |
+|                                               |
+| RESOURCE handler -> SetPayload + return handle|
+| OBJECT handler   -> SetPayload + return object|
+| legacy path      -> preserve current behavior |
++-----------------------------------------------+
+        |
+        +--- validation failure --------------------+
+        |                                            |
+        |    resource -> FAILED                      |
+        |    Ready() rejects                         |
+        |                                            |
+        `--- publication succeeds -----------------+
+                    |
+                    | resource -> LOADED
+                    v
+             CjsLibrary returns
+             the built CjsResource/object
+```
+
+Device realization is a separate continuation selected outside ResMan. It can
+run again after adapter eviction or device loss while the CPU payload remains
+resident:
+
+```text
+CjsResource LOADED
+        |
+        | selected engine adapter
+        v
+PREPARING
+        |
+        | create candidate -> verify current target -> synchronous attach
+        v
+PREPARED
+
+failure: destroy candidate -> LOADED (CPU payload retained)
+```
+
+## Retention model
+
+ccpwgl keeps every resource in `Tw2MotherLode` until it is explicitly cleared
+or auto-purged, and its `IsGood()` implicitly calls `KeepAlive()`, so many
+read/check paths keep resources resident. CarbonEngineJS retains that behavior
+for the resource being queried, while keeping payload retention and hard locks
+explicit:
+
+- `IsGood()` calls `KeepAlive()` before checking preparation. It renews this
+  handle and starts its bounded reload path when the handle is `PURGED`.
+- `IsPrepared()` and `HasLoaded()` remain pure state checks.
+- `KeepAlive()` and `KeepPayloadAlive()` are the explicit liveness operations.
+- `Lock()` / `Unlock()` maintain a non-underflowing count and prevent identity
+  and payload eviction during a sweep.
+- MotherLode tracks separate identity and CPU-payload frame/time observations.
+- `CjsMotherLode.PurgeInactive()` scans only when explicitly requested and
+  never infers JavaScript reachability. `CjsResMan.Update()` may request it
+  only under an explicitly configured automatic policy.
+
+Generic liveness never walks arbitrary child fields. `IsGood()` renews only the
+handle on which it is called; an aggregate consumer that owns child resources
+must query or retain those children explicitly.
+
+The CPU/GPU split adds an axis that ccpwgl blurs: CPU payload memory and
+device memory are different budgets. Retention therefore distinguishes:
+
+- resource identity: path, extension, state, error summary, lightweight
+  metadata;
+- CPU payload: plain reader/converter objects, hydrated object graphs, decoded
+  typed arrays;
+- adapter payload: WebGL/WebGPU textures, buffers, shader modules, pipelines.
+
+Identity and lightweight metadata stay resident while CPU payloads and adapter
+payloads release independently. Engine adapters own adapter-resource
+destruction; runtime-resource provides lifecycle hooks and opaque adapter
+slots so cleanup has a consistent place to run. The exact contracts live in
+[reference/motherlode-cache.md](../reference/motherlode-cache.md).
+
+## Related documentation
+
+- [Architecture and boundaries](../architecture.md)
+- [MotherLode identity, cache, and retention](../reference/motherlode-cache.md)
+- [Candidate-first atomic reload](../reference/reload.md)
+- [Queues and the Wait fence](../reference/queues.md)