@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

package/docs/reference/motherlode-cache.md

@@ -1,275 +1,275 @@
-# 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`.
-
-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
-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.
-
-`PURGED` is not terminal for the handle. Purge deletes the payload, but the
-handle revives itself: `IsGood()` renews activity through `KeepAlive()`, and
-`KeepAlive()` reloads a purged resource along the ordinary first-load path. A
-consumer therefore never learns that a purge happened and never manages
-retention itself - it asks whether the resource is good, and that question is
-what keeps it, or brings it back.
-
-Liveness follows visibility. Something being drawn is asked about every frame
-and stays live; something that stops being drawn stops being renewed, ages out,
-and has its memory reclaimed; when it is drawn again the next `IsGood()`
-restores it. `Reload()` is bounded by `maxReloadAttempts` precisely because the
-render path calls this every frame, so one permanently missing resource cannot
-become a retry storm. A reload refills the exact handle the consumer holds
-rather than resolving whatever the manager currently caches for that path,
-because a consumer holding a purged handle has no way to discover a
-replacement.
-
-`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()`, `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
-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 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
-
-- [Resource lifecycle concepts](../concepts/resource-lifecycle.md)
-- [Candidate-first atomic reload](../reference/reload.md)
-- [Queues and the Wait fence](../reference/queues.md)
+# 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`.
+
+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
+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.
+
+`PURGED` is not terminal for the handle. Purge deletes the payload, but the
+handle revives itself: `IsGood()` renews activity through `KeepAlive()`, and
+`KeepAlive()` reloads a purged resource along the ordinary first-load path. A
+consumer therefore never learns that a purge happened and never manages
+retention itself - it asks whether the resource is good, and that question is
+what keeps it, or brings it back.
+
+Liveness follows visibility. Something being drawn is asked about every frame
+and stays live; something that stops being drawn stops being renewed, ages out,
+and has its memory reclaimed; when it is drawn again the next `IsGood()`
+restores it. `Reload()` is bounded by `maxReloadAttempts` precisely because the
+render path calls this every frame, so one permanently missing resource cannot
+become a retry storm. A reload refills the exact handle the consumer holds
+rather than resolving whatever the manager currently caches for that path,
+because a consumer holding a purged handle has no way to discover a
+replacement.
+
+`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()`, `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
+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 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
+
+- [Resource lifecycle concepts](../concepts/resource-lifecycle.md)
+- [Candidate-first atomic reload](../reference/reload.md)
+- [Queues and the Wait fence](../reference/queues.md)