@carbonenginejs/runtime 0.1.0-alpha.3 → 0.1.0-alpha.4

package/docs/resource/architecture.md

@@ -1,116 +1,156 @@
-# Architecture and boundaries
-
-Status: Evolving  
+# Architecture and boundaries
+
+Status: Evolving  
 Scope: `@carbonenginejs/runtime/resource`
-Audience: Users and integrators  
-Summary: Defines the GPU-free boundary this package owns and how engine and runtime packages relate to it.
-
-## The GPU-free split
-
-The `resource` layer owns the GPU-free half of the Carbon resource lifecycle:
-
-```text
-EMPTY -> REQUESTED/LOADING -> LOADED
-```
-
-Engine adapters own device realization:
-
-```text
-LOADED -> PREPARING -> PREPARED
-```
-
-The package selects and runs registered readers, hydrates or returns the
-promised CPU outcome, and stores lifecycle state, cache entries, and loaded
-payloads. For compiled effects it independently validates complete permutation
-topology and the Carbon v15 container records it read itself, selects a
-permutation, and hydrates a canonical device-free `Tr2Shader` graph. It never
-creates WebGL/WebGPU textures, buffers, shader modules, pipelines, or bind
-groups, and it never inspects backend capability.
-A realization failure destroys its candidate and returns the resource to
-`LOADED` without discarding the valid CPU payload.
-
-This deliberately differs from Carbon and ccpwgl, whose resource classes live
-inside an engine that can prepare GPU objects directly. Keeping the
-format/resource layer reusable means stopping before GPU work; see
-[resource lifecycle concepts](concepts/resource-lifecycle.md) for the
-historical mapping.
-
-## What the package owns
-
-- `CjsResource` state and Carbon-style resource methods.
-- `CjsMotherLode` canonical identity, explicit replacement results, activity
-  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
-- `CjsResMan` extension-selected resource/object handlers, semantic resource
-  overrides, ordered and legacy registered-format selection,
-  concurrency-limited source loading, staged prepare queues, layered
-  source/read/resource deduplication, object loader dispatch, and prefetch.
-- Main-thread and browser-worker resource execution strategies, including
-  transferable fetch results and declared worker-safe CPU readers.
-- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
-  frame-coalesced texture-array inputs.
-- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
-  complete or windowed individually addressable audio files.
+Audience: Users and integrators  
+Summary: Defines the resource lifecycle this package owns and how it reaches the graphics abstraction layer.
+
+## The resource lifecycle
+
+The `resource` layer owns the whole Carbon resource lifecycle, load and
+prepare both:
+
+```text
+EMPTY -> REQUESTED/LOADING -> LOADED -> PREPARING -> PREPARED
+```
+
+Carbon does the same. A resource prepares itself: `BlueAsyncRes` carries the
+`m_isPrepared` flag (`blue/include/BlueAsyncRes.h:87-166`) and the concrete
+resource implements `OnPrepareResources` (`TriTextureRes.h:124`,
+`TriGeometryRes.h:353`, `Tr2EffectRes.h:53`). There is no layer between the
+resource and the device in Carbon, and there is none here.
+
+The package selects and runs registered readers, hydrates or returns the
+promised CPU outcome, and stores lifecycle state, cache entries, and loaded
+payloads. For compiled effects it independently validates complete permutation
+topology and the Carbon v15 container records it read itself, selects a
+permutation, and hydrates a canonical `Tr2Shader` graph.
+A prepare failure destroys its candidate and returns the resource to
+`LOADED` without discarding the valid CPU payload.
+
+GPU work goes through the abstraction layer in `src/trinityal`, exactly as
+Carbon's resources call its AL. Headlessness is what the stub backend is for:
+running without a device means selecting the stub, never hollowing a resource
+class out. A resource method left empty so that something else can do its work
+is a gap to be closed, not a boundary.
+
+The divergences that remain are the ones the browser forces: adapter
+acquisition, `mapAsync`, shader-module and pipeline creation, `fetch`, and
+image and video decode are asynchronous where Carbon's are not. Each carries
+its own `@impl.reason` at the site. "An engine owns this" is not one of them.
+
+## What the package owns
+
+- `CjsResource` state and Carbon-style resource methods.
+- `CjsMotherLode` canonical identity, explicit replacement results, activity
+  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
+- `CjsResMan` extension-selected resource/object handlers, semantic resource
+  overrides, ordered and legacy registered-format selection,
+  concurrency-limited source loading, staged prepare queues, layered
+  source/read/resource deduplication, object loader dispatch, and prefetch.
+- Main-thread and browser-worker resource execution strategies, including
+  transferable fetch results and declared worker-safe CPU readers.
+- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
+  frame-coalesced texture-array inputs.
+- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
+  complete or windowed individually addressable audio files.
 - Raw `CjsEventEmitter` (from `global/model`) for manager/runtime events
-  without requiring `CjsModel` inheritance.
-- Resource-path normalization and URL resolution, including prefix bases and
-  an injectable complete resolver, with fetch execution delegated to a
-  URL-only provider.
-- Resource-specific geometry traversal and payload adaptation, composed with
-  shared vector, matrix, bounds, sphere, ray, and mesh math from
+  without requiring `CjsModel` inheritance.
+- Resource-path normalization and URL resolution, including prefix bases and
+  an injectable complete resolver, with fetch execution delegated to a
+  URL-only provider.
+- Resource-specific geometry traversal and payload adaptation, composed with
+  shared vector, matrix, bounds, sphere, ray, and mesh math from
   the shared `global` layer rather than maintaining another math implementation here.
-- Plain reader/converter payload objects with focused shared validators.
-- Canonical Carbon resource classes that validate and hold CPU payloads
-  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
-  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
-- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
-  technique, pass, stage, constant, resource, sampler, annotation, and library
-  records; Carbon-binary hydration; permutation selection; and per-index caching.
-- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
-  membership.
-- Opaque engine-owned subobject slots for backend adapters.
-- Format implementations as explicit tree-shakeable subpaths under
-  `@carbonenginejs/runtime/resource/formats/<name>`.
-- Acquisition-free FSD byte validation, schema decoding, and approved dataset
-  readers under `formats/fsd`. The format keeps separate `32` and `64`
-  implementation directories: legacy headerless FSD is identified explicitly
-  but is not yet decoded, while modern cFSD uses the 64-bit implementation.
-
-## What the package does not own
-
-- WebGL/WebGPU realization, allocations, upload accounting, device budgets,
-  capability limits, and device-loss recovery (engine packages).
-- Shader binary decoding, backend translation, and package serialization live
+- Plain reader/converter payload objects with focused shared validators.
+- Canonical Carbon resource classes that validate and hold CPU payloads
+  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
+  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
+- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
+  technique, pass, stage, constant, resource, sampler, annotation, and library
+  records; Carbon-binary hydration; permutation selection; and per-index caching.
+- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
+  membership.
+- Opaque engine-owned subobject slots for backend adapters.
+- Format implementations as explicit tree-shakeable subpaths under
+  `@carbonenginejs/runtime/resource/formats/<name>`.
+- Acquisition-free FSD byte validation, schema decoding, and approved dataset
+  readers under `formats/fsd`. The format keeps separate `32` and `64`
+  implementation directories: legacy headerless FSD is identified explicitly
+  but is not yet decoded, while modern cFSD uses the 64-bit implementation.
+
+## What the package does not own
+
+- Backend allocation, upload accounting, device budgets, capability limits,
+  and device-loss recovery. These belong to the abstraction layer in
+  `src/trinityal/<backend>`, which resource classes call; Carbon's resources
+  call its AL the same way.
+- Shader binary decoding, backend translation, and package serialization live
   in the explicit `@carbonenginejs/runtime/resource/formats/{hlsl,dxbc,webgl,webgpu}` subpaths.
-  Backend shader objects remain in engine packages.
-- AudioBuffer construction, playback, or audio manager behavior.
-- Audio-library document construction, enrichment, media-ID interpretation,
-  and delivery-route selection.
-
-## Package relationships
-
+  Backend shader objects are allocated by the abstraction layer.
+- AudioBuffer construction, playback, or audio manager behavior.
+- Audio-library document construction, enrichment, media-ID interpretation,
+  and delivery-route selection.
+
+## Package relationships
+
 - The `core` layer may configure and expose a `CjsResMan`, but does not own its
-  implementation.
-- The `trinity` and `sof` layers may request GPU-free objects and
-  resources without selecting an engine. Trinity owns the mutable
-  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
-  it consumes the resource-owned shader graph.
-- The `trinityal/webgpu` layer and any future WebGL engine layer consume loaded resources and own
-  all backend allocations, preparation, replacement, and destruction.
-
+  implementation.
+- The `trinity` and `sof` layers may request resources directly, as Carbon's
+  do. With the stub backend selected they run headless. Trinity owns the mutable
+  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
+  it consumes the resource-owned shader graph.
+
+### What Trinity needs from this layer
+
+One thing: somewhere to ask for a res file. Not an adapter, not an injected
+seam.
+
+Carbon settles this across a repository boundary, which is a stronger test than
+ours. `blue` and `trinity` are separate repositories, and `trinity` takes
+exactly one header from the manager's: `IBlueResMan.h`, through `StdAfx.h:54`.
+It then calls the global `BeResMan` (`IBlueResMan.h:135`) at 94 sites, for
+example `BeResMan->GetResource( profilePath, L"lp", lightProfile )`
+(`EveBannerSet.cpp:63`, `EveHazeSet.cpp:52`, `EvePlaneSet.cpp:40`), and holds
+the result as an ordinary member. No indirection is introduced for the
+crossing.
+
+The resource CLASSES are not what crosses. In Carbon they live with their
+consumer - `TriGeometryRes`, `TriTextureRes`, `Tr2EffectRes` and
+`Tr2LightProfileRes` are all in `trinity/trinity/Resources/`, while `blue` owns
+only the manager and the async base (`BlueResMan`, `BlueAsyncRes`,
+`IBlueResource`). Carbon's audio repository goes further and never involves the
+manager at all, reading its own bytes through a Wwise IO hook.
+
+We arrange this differently: the manager and the resource classes are one layer
+here, below `trinity`. `layers.json` lets `trinity` import `resource`, so a
+Trinity class may hold a `TriGeometryRes` exactly as Carbon's does - these are
+small records, and holding one is not a layering event. `Tr2Mesh` and
+`Tr2TexturedPointLight` already work this way, through `CjsResMan.GetGlobal()`,
+which is the `BeResMan` pattern.
+
+So a Trinity class that needs a resource asks the manager for it. "An adapter
+supplies it" and "the seam is injected" describe neither Carbon nor this
+package, and where they appear they mark work that was never done rather than a
+boundary being kept.
+- The `trinityal/<backend>` layers own backend allocation, replacement, and
+  destruction. Preparation is the resource's own, through `OnPrepareResources`;
+  the backend supplies the objects it allocates.
+
 Concrete formats require [explicit imports and registration](formats/README.md).
 [Worker-safe formats](reference/workers.md) also declare their exact module;
 the package root imports and registers neither.
-
-Extension routes are manager-local configuration. They bind an extension to a
-handler plus one format or an ordered format chain. The handler's
-`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
-returns the stable resource or the constructed object. The route snapshot is
-captured by the canonical handle, so later registration changes affect only a
-new identity after explicit deletion or clearing. Target construction and
-dynamic identification run after any worker decode on the main thread.
-
-## Source layout
-
+
+Extension routes are manager-local configuration. They bind an extension to a
+handler plus one format or an ordered format chain. The handler's
+`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
+returns the stable resource or the constructed object. The route snapshot is
+captured by the canonical handle, so later registration changes affect only a
+new identity after explicit deletion or clearing. Target construction and
+dynamic identification run after any worker decode on the main thread.
+
+## Source layout
+
 Resource source is directly importable ESM without decorator syntax. Classes
 that need schema metadata install it through `CjsSchema.define`; removing the
 syntax does not remove their identity, fields or model behavior. Source-focused
@@ -120,10 +160,10 @@ This does not change other layers' decorator/build requirements. Published
 output remains built ESM in `npm/dist`.
 
 Resource owners and their direct Carbon data records live under
-`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
-and `texture`; worker execution and its message protocol live under `src/resource/worker`.
-Reviewed, unresolved active ports live under `src/resource/generated` and are exposed
-only through the explicit `./generated` package subpath until promotion. Native
-shapes that JavaScript replaces or does not use are retained only under
-`src/resource/dropped`, with their disposition documented there, and are never exported
-or bundled.
+`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
+and `texture`; worker execution and its message protocol live under `src/resource/worker`.
+Reviewed, unresolved active ports live under `src/resource/generated` and are exposed
+only through the explicit `./generated` package subpath until promotion. Native
+shapes that JavaScript replaces or does not use are retained only under
+`src/resource/dropped`, with their disposition documented there, and are never exported
+or bundled.

package/docs/resource/concepts/resource-lifecycle.md

@@ -28,21 +28,26 @@ Additional terminal or cleanup states include `ERROR`, `UNLOADED`, and
 - 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).
+Carbon's do the same, through `OnPrepareResources` (`TriTextureRes.h:124`,
+`TriGeometryRes.h:353`, `Tr2EffectRes.h:53`), and so may ours; see
+[architecture](../architecture.md).
 
 ## CarbonEngineJS states
 
 ```text
-EMPTY -> REQUESTED/LOADING -> LOADED          (resource layer)
-LOADED -> PREPARING -> PREPARED               (engine adapters)
+EMPTY -> REQUESTED/LOADING -> LOADED -> PREPARING -> PREPARED
 ```
 
+The whole line belongs to the resource layer. Backend allocation inside
+`PREPARING` is delegated to the abstraction layer, as Carbon delegates it to
+its own AL.
+
 - `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.
+- `PREPARING`: the resource is preparing itself, allocating whatever backend
+  objects it needs through the abstraction layer.
 - `PREPARED`: preparation completed successfully and the resource is usable.
 - `FAILED`: CPU loading, conversion, validation, or publication failed before
   a valid payload was published.
@@ -57,8 +62,7 @@ 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 `PREPARED`: the published value is already the reader or
-converter outcome, so no CPU preparation remains. ResMan never performs backend
-realization. A route that hydrates a `Target` builds a new object for each
+converter outcome, so no CPU preparation remains. A route that hydrates a `Target` builds a new object for each
 caller from the retained decoded values, as Carbon's `LoadObject` does. See
 [reference/queues.md](../reference/queues.md) for the queue contract and
 [reference/motherlode-cache.md](../reference/motherlode-cache.md) for
@@ -164,14 +168,14 @@ Application / runtime object
              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
+Preparation is a separate phase from loading, as it is in Carbon, and it can
+run again after eviction or device loss while the CPU payload remains
 resident:
 
 ```text
 CjsResource LOADED
         |
-        | selected engine adapter
+        | OnPrepareResources
         v
 PREPARING
         |

package/docs/resource/formats/pickle.md

@@ -1,20 +1,23 @@
-# Data-only pickle protocol 0
-
-Status: Experimental
-Scope: `@carbonenginejs/runtime/resource/formats/pickle`
-Audience: Resource integrators handling inert legacy data caches
-Summary: Defines safe protocol-0 pickle decoding without Python object reconstruction.
-
-## Boundary
-
-`CjsPickleFormat` reads `.pickle` bytes through an internal protocol-0 reader.
-It is a data decoder, not a general Python unpickler. It never imports a
-module, resolves a global, calls a reducer, follows a persistent ID, or
-constructs a Python object. Every executable, object-bearing, newer-protocol,
-or unknown opcode fails at its exact byte offset.
-
-## One global is rebuilt, and it is a closed set
-
+# Data-only pickle
+
+Status: Experimental
+Scope: `@carbonenginejs/runtime/resource/formats/pickle`
+Audience: Resource integrators handling inert legacy data caches
+Summary: Defines safe pickle decoding, protocols 0 through 4, without Python object reconstruction.
+
+## Boundary
+
+`CjsPickleFormat` reads `.pickle` bytes through one of two internal readers,
+chosen from the bytes themselves. Protocol 0 is printable text with no header;
+every binary protocol opens with `PROTO`, which the text protocol cannot begin
+with, so the first byte decides and the caller passes nothing.
+It is a data decoder, not a general Python unpickler. It never imports a
+module, resolves a global, calls a reducer, follows a persistent ID, or
+constructs a Python object. Every executable, object-bearing, newer-protocol,
+or unknown opcode fails at its exact byte offset.
+
+## One global is rebuilt, and it is a closed set
+
 `GLOBAL` names a module and attribute to import; `REDUCE` calls it. This
 remote-execution path is refused: `os.system` fails at `GLOBAL`, before its
 argument is read.
@@ -23,91 +26,114 @@ argument is read.
 builds a plain JavaScript object preserving insertion order. Nothing is imported,
 resolved or invoked. `REDUCE` independently refuses every other target, so it
 cannot bypass the `GLOBAL` check.
-
+
 Integer-like keys are rejected because JavaScript objects sort them ahead of
 other keys, breaking insertion order.
 
 Any additional allowed name must represent pure data without behavior and be
 rebuilt directly, never through a callable.
-
-Why it matters: every one of the 25 embedded-schema static-data containers in one
-client build was scanned for the `GLOBAL` opcode's module and attribute lines,
-and this is the **only** name any of them uses — once per file, 25 occurrences,
-no second name. They use it because a schema's attribute order is its field order, which
-an ordinary dictionary would lose. Refusing it left 25 containers unreadable,
-including one of 88 MB holding roughly 477,000 records.
-
-Two limits exist because of this opcode and are worth knowing before raising
-either: `REDUCE` is the only path that builds many properties for a constant
-number of opcodes, so rebuilt properties are budgeted **across the whole decode**
-rather than per container, and a global may only ever be consumed by a `REDUCE` —
-appending one to a list or leaving it as the result is refused, because it would
-reach the caller as an empty object indistinguishable from an empty dictionary.
-
-The initial reader accepts the protocol-0 scalar, string, list, tuple,
-dictionary, memo, append, and set-item operations required by inert data
-graphs. Lists and tuples become JavaScript arrays. Integers outside the safe
-JavaScript range become lossless decimal strings. Dictionary keys must be
-strings or safe integers; collisions introduced by JSON key normalization are
-rejected.
-
-## Outputs
-
-The default `json` output returns a plain JSON-compatible graph and rejects
-cycles. `payload` and debug `raw` output preserve memo aliases and may contain
-cycles:
-
-```js
-import { CjsPickleFormat } from
-  "@carbonenginejs/runtime/resource/formats/pickle";
-
-const values = CjsPickleFormat.read(bytes);
-const exactGraph = CjsPickleFormat.read(bytes, { emit: "payload" });
-```
-
-`CjsPickleFormat.supportedProtocols` currently contains only protocol `0`.
-The public format name follows the `.pickle` extension so future protocol
-dispatch can be added without changing resource registration. Unsupported
-protocols continue to fail closed until their data-only semantics are
-implemented and tested.
-
-## Resource registration
-
-The format contains no domain target policy. A caller registers the extension
-and decides whether an exact resource path returns raw decoded data or hydrates
-a target:
-
-```js
-import {
-  CjsLoadingObject,
-  CjsResMan
-} from "@carbonenginejs/runtime/resource";
-import { CjsPickleFormat } from
-  "@carbonenginejs/runtime/resource/formats/pickle";
-
-const resMan = new CjsResMan({ source });
-
-resMan.RegisterExtension("pickle", CjsLoadingObject, {
-  Format: CjsPickleFormat,
-  Identify(_values, context) {
-    return context.resFilePath === "res:/data/profile.pickle";
-  }
-});
-```
-
-Resource paths, extensions, and filenames in the context are normalized to
-lowercase. URL-backed sources additionally expose the exact translated URL.
-
-## Limits
-
-Every read is bounded by configurable positive safe-integer limits for input
-bytes, operations, stack depth, memo size and IDs, container items, and string
-bytes. Defaults are conservative for ordinary resource files. Callers may
-lower limits per profile or read; raising them remains an explicit trust and
-memory decision.
-
-## Related documentation
-
-- [Format subpaths](README.md)
-- [Queues, publication, and registration](../reference/queues.md)
-- [Browser worker execution](../reference/workers.md)
+
+Why it matters: every one of the 25 embedded-schema static-data containers in one
+client build was scanned for the `GLOBAL` opcode's module and attribute lines,
+and this is the **only** name any of them uses — once per file, 25 occurrences,
+no second name. They use it because a schema's attribute order is its field order, which
+an ordinary dictionary would lose. Refusing it left 25 containers unreadable,
+including one of 88 MB holding roughly 477,000 records.
+
+Two limits exist because of this opcode and are worth knowing before raising
+either: `REDUCE` is the only path that builds many properties for a constant
+number of opcodes, so rebuilt properties are budgeted **across the whole decode**
+rather than per container, and a global may only ever be consumed by a `REDUCE` —
+appending one to a list or leaving it as the result is refused, because it would
+reach the caller as an empty object indistinguishable from an empty dictionary.
+
+Both readers accept the scalar, string, list, tuple, dictionary, memo, append,
+and set-item operations required by inert data graphs. Lists and tuples become
+JavaScript arrays. Integers outside the safe JavaScript range become lossless
+decimal strings. Dictionary keys must be strings or safe integers; collisions
+introduced by JSON key normalization are rejected.
+
+## Two readers, one set of rules
+
+The binary protocols differ from the text one in how a value is written down,
+not in what a decoded value is allowed to be. So the limits, the memo, the
+container bookkeeping, the dictionary-key rules, the JSON boundary and the
+closed set above live in a shared module and the readers own only their opcode
+spellings. Duplicating the refusal rules per protocol was the alternative, and a
+second reader that refuses slightly less is indistinguishable from one that
+refuses correctly until the day it matters.
+
+Two decoded shapes exist only in the binary protocols, because the text protocol
+has no way to write them:
+
+- `BINBYTES` produces a `Uint8Array`. Bytes have no JSON spelling, and inventing
+  one - an array of numbers, a base64 string - would be indistinguishable in the
+  output from data that really was that. The `payload` emit carries it; the
+  `json` emit refuses it.
+- `BINSTRING` produces latin-1 text, matching protocol 0's `STRING`. It is
+  Python 2's `str`, a byte string with no declared encoding, and latin-1 is the
+  mapping that loses nothing.
+
+## Outputs
+
+The default `json` output returns a plain JSON-compatible graph and rejects
+cycles. `payload` and debug `raw` output preserve memo aliases and may contain
+cycles:
+
+```js
+import { CjsPickleFormat } from
+  "@carbonenginejs/runtime/resource/formats/pickle";
+
+const values = CjsPickleFormat.read(bytes);
+const exactGraph = CjsPickleFormat.read(bytes, { emit: "payload" });
+```
+
+`CjsPickleFormat.supportedProtocols` contains `0` through `4`. The public format
+name follows the `.pickle` extension, and dispatch happens inside the format, so
+a caller registering it never chooses a protocol. A `PROTO` opcode declaring a
+protocol above 4 fails closed, as does any opcode outside the data subset,
+at its own byte offset.
+
+Protocol 4 is not academic: EVE Frontier's localisation containers ship in it,
+and no type in that client could be named without it.
+
+## Resource registration
+
+The format contains no domain target policy. A caller registers the extension
+and decides whether an exact resource path returns raw decoded data or hydrates
+a target:
+
+```js
+import {
+  CjsLoadingObject,
+  CjsResMan
+} from "@carbonenginejs/runtime/resource";
+import { CjsPickleFormat } from
+  "@carbonenginejs/runtime/resource/formats/pickle";
+
+const resMan = new CjsResMan({ source });
+
+resMan.RegisterExtension("pickle", CjsLoadingObject, {
+  Format: CjsPickleFormat,
+  Identify(_values, context) {
+    return context.resFilePath === "res:/data/profile.pickle";
+  }
+});
+```
+
+Resource paths, extensions, and filenames in the context are normalized to
+lowercase. URL-backed sources additionally expose the exact translated URL.
+
+## Limits
+
+Every read is bounded by configurable positive safe-integer limits for input
+bytes, operations, stack depth, memo size and IDs, container items, and string
+bytes. Defaults are conservative for ordinary resource files. Callers may
+lower limits per profile or read; raising them remains an explicit trust and
+memory decision.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Queues, publication, and registration](../reference/queues.md)
+- [Browser worker execution](../reference/workers.md)

package/docs/resource/formats/provenance.md

@@ -1,7 +1,7 @@
 # Format ownership and fork provenance
 
 Status: Stable  
-Scope: `@carbonenginejs/runtime/resource/formats`
+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.
 
@@ -80,14 +80,20 @@ formats, not aliases. Donor MIT license and notice files are retained under
 
 ## Black definition snapshot
 
-The Black reader uses the package-owned generated definition snapshot at
-`src/resource/formats/black/core/black-schema-v1-2026-07-23.json`. The Red format exposes
-the same catalog for discovery, but its YAML reader currently accepts named
-fields without registry enforcement. The refreshed consumer snapshot landed
-in runtime-resource revision `6beda70` with SHA-256
-`9234DD86DBB5EB3676EF060E383ADBCE8F073941E76A32865D3528DD5DA7B737`.
-Its exact tools-core generator revision was not recorded and remains unknown;
-this page does not infer one from the consumer commit.
+The Black reader uses the package-owned generated definition snapshot that
+`src/resource/formats/black/core/blackDefinitions.js` imports, currently
+`black-schema-v1-2026-09-19.json`. The Red format exposes the same catalog for
+discovery, but its YAML reader currently accepts named fields without registry
+enforcement. That snapshot was generated by tools-core revision `d8c20bb` from
+the 2026-09-19 Carbon scan and landed in runtime revision `2c2b8c9f`, SHA-256
+`0A4EBE699C9055C6132A41F6F709C2CC4BF80E928DC958DE13C1AF1F45F19A19`.
+
+Dated snapshots are never edited in place; a new one is generated, and
+tools-core's `--black-module` points `blackDefinitions.js` at the newest. The
+previous snapshot, `black-schema-v1-2026-07-23.json` (runtime-resource revision
+`6beda70`, SHA-256
+`9234DD86DBB5EB3676EF060E383ADBCE8F073941E76A32865D3528DD5DA7B737`, generator
+revision unrecorded), stays in the package and is no longer imported.
 
 This retained generated artifact keeps the published readers deterministic and
 browser-safe without a runtime dependency on a sibling checkout or an