@carbonenginejs/runtime-resource 0.12.2 → 0.14.0

package/docs/formats/carbon-effect-container.md

@@ -3,7 +3,7 @@
 Status: Stable
 Visibility: Public
 Scope: `@carbonenginejs/runtime-resource` — `src/format/carbonEffect/`, `src/format/CjsByteReader.js`, `src/format/CjsByteWriter.js`, `src/format/CjsStringTable.js`
-Audience: Anyone reading or writing compiled shader effect bytes, or extending `.cewgpu`
+Audience: Anyone reading or writing compiled shader effect bytes, or extending `.carbonwebgpu`
 Summary: The v15 binary layout of Carbon's compiled effect files, the shared byte reader and writer that implement it, and the arena offset policy a byte-exact re-emit depends on.
 
 ## What this is
@@ -14,8 +14,10 @@ a deduplicated blob arena ("string table"), one dense offset-table row per
 permutation, and one stored description blob per distinct encoded body.
 
 This package implements it as a shared reader and writer, verified byte-exact against
-CCP's own shipped files. It is the wire foundation for `.cewgpu`. The `.cewg`
-WebGL package retains its separate `CEWG` magic and chunk layout.
+CCP's own shipped files. It is the wire foundation for **both** browser backends:
+`.carbonwebgpu` and `.carbonwebgl` are the same Carbon v15 container, differing
+only in the program text occupying each stage's slot and in the optional
+per-pass backend block. Neither carries a private magic or chunk layout.
 
 | module | role |
 |---|---|
@@ -26,16 +28,77 @@ WebGL package retains its separate `CEWG` magic and chunk layout.
 | `src/format/carbonEffect/CjsCarbonEffectReader.js` | container reader and structural checks |
 | `src/format/carbonEffect/CjsCarbonEffectWriter.js` | container writer, offset arithmetic and alias dedupe |
 
-## Why v15 only
-
-The reader and writer accept and emit version 15 and nothing else.
-
-Carbon's own reader accepts versions 2 through 15, but its v13/v14 branches mark
-the field-order boundaries as uncertain. Version 15 is the version with an
-authoritative writer to check against, and the entire audited shipped corpus at
-build 3444265 is v15 — 3222 files across `effect.dx11` and `effect.dx12`, plus
-the same 537 shaders again under `effect.metal`. Nothing older appears in that
-audited corpus.
+## Versioning: how Carbon does it, and what this reader does instead
+
+### Carbon validates the version, then threads it through parsing
+
+Carbon reads the version dword once, in `Tr2EffectRes`, and rejects anything
+outside 2..15 (`Tr2EffectRes.cpp:209`). Inside that range it never branches to
+accept or refuse again — the version becomes a *parsing input*. It is first used
+by the container reader itself, then **passed as a parameter** into the effect
+description's read call (`Tr2EffectRes.cpp:128`), alongside the buffer, its
+size, and the string table.
+
+From there it is threaded through every record reader in
+`Tr2EffectDescription.cpp` — `ReadConstant`, `ReadResource`,
+`ReadPipelineInputs`, `ReadRegisters`, `ReadInput`, and the pass/technique loop
+— which branch on it at 22 conditional sites using 16 distinct comparisons:
+
+| Threshold | What it decides |
+| --- | --- |
+| `> 8` | Whether a stage carries a register signature **at all** |
+| `< 14` | Where pipeline inputs are read, and whether registers are read beside them |
+| `< 11` | How a constant's type byte is decoded — older files remap a legacy enum, so the byte count is unchanged but its meaning is not |
+| `>= 13` | Whether a resource carries `arrayElements` at all; below 13 it is absent and defaults to 1 |
+| `< 5`, `< 4`, `>= 3`, `>= 4` | Stage-input presence and ordering |
+| `> 6`, `> 9`, `> 10`, `> 12`, `>= 8` | Per-record field presence |
+| `> 13`, `>= 14` | Library and pipeline-input placement |
+
+The consequence worth internalising: **the version determines the byte layout at
+nearly every level of the reflection graph**, not just the header. A v8 file and
+a v15 file are not the same records with a different preamble.
+
+Note where the version does *not* reach: `Tr2Shader` itself has no version field
+and no version-dependent branch. Container/header parsing and description
+parsing between them absorb every version difference before the graph reaches
+`Tr2Shader` — the container reader has its own branches (`Tr2EffectRes.cpp`
+handles `< 5` for the legacy header size, `>= 15` for the compiler version and
+source hash, and `> 5` for the permutation type), and the description reader
+handles the rest. What emerges carries no version, so consumers above that
+boundary are version-free. A port that preserves the same separation stays
+consistent with Carbon.
+
+### What this reader does: constant-folded to 15
+
+`readEffectDescription` takes no version parameter. This reader is
+constant-folded to version 15 and rejects everything else outright.
+
+That is a deliberate narrowing, and it is the missing piece if an older version
+is ever needed. Supporting v8 does **not** mean writing a second reader; it
+means restoring the parameter Carbon always had and implementing the branches
+above. The writer is unaffected — reading an old version does not imply emitting
+one, and this package emits v15 only.
+
+Rejecting is the correct failure mode rather than a limitation to route around.
+Applying v15 rules to an older layout can misalign fields — the comparisons
+above change which fields are present and how their bytes are interpreted — and
+must not be attempted. How such a read would fail in practice is not documented
+here, because no legacy container has been examined to establish it.
+
+The reader rejects with the version it read, and does not classify it further.
+A leading dword of 2..14 is a *recognized legacy version number*, not evidence
+that the bytes are an effect container: arbitrary data can begin with a small
+integer, and the version dword alone carries no magic or checksum to confirm it.
+Anything that reaches this rejection needs identifying by other means before it
+is treated as a porting question rather than a wrong file.
+
+### Why 15 is the version that got implemented
+
+Version 15 is the one with an authoritative writer to check against, and the
+entire audited shipped corpus at build 3444265 is v15 — 3222 files across
+`effect.dx11` and `effect.dx12`, plus the same 537 shaders again under
+`effect.metal`. Nothing older appears in that audited corpus. Carbon's own
+v13/v14 branches additionally mark their field-order boundaries as uncertain.
 
 The v15 body is byte-identical to v14. Version 15 differs from 14 only by the 36
 extra header bytes: the compiler version and the source hash.
@@ -61,10 +124,7 @@ compares only the first three. A shipped v15 header reads `01 02 06 00` —
 compiler 1.2.6.0, matching the ShaderCompiler project version. As a `u32` those
 bytes are `0x00060201`, which means nothing. `HlslEffectRes` historically read
 the field as a dword; it now also exposes `m_compilerVersionBytes`, which is the
-truthful reading and what new code should use. The dword form survives only
-because it is republished as `source.compilerVersion` in the portable
-reflection, where it is asserted to be an unsigned integer and covered by a
-package digest.
+truthful reading and what new code should use.
 
 The compiler's rebuild check reads the 32-byte hash, while the runtime skips it.
 It is provenance, not integrity.
@@ -318,6 +378,19 @@ surviving twin. The row is **kept**, so the offset table stays dense while the
 file stores each distinct body once. Across the shipped corpus 22% of files
 alias, at roughly 2.1 rows per distinct body.
 
+`enumerateUniqueEffectBodies` recovers that grouping without decoding a single
+body. It inspects source records and bytes only, and returns
+first-occurrence-ordered groups, each holding one canonical
+`permutationIndex`/`sourceRecord` plus every byte-identical alias. Exact range
+aliases are the fast path; distinct ranges are fingerprinted and then compared
+byte for byte. It caps the Cartesian body table at 65,536 records
+(`EFFECT_BODY_COUNT_MAX`) and rejects partial overlaps, because a partial
+overlap means two bodies claim the same bytes. It decodes nothing: it reads
+`m_offsets` and slices `m_data` directly, so a backend packager can inventory an
+effect without disturbing anything a later read depends on. It is internal
+(`src/format/effect/`), not a published export; the backend body set is its one
+consumer.
+
 ## Offset-table density
 
 Carbon indexes the offset table **positionally** and never reads each row's
@@ -360,15 +433,16 @@ close.
 layout. Current packaging emits no such prefix and the former helper is no
 longer part of the package.
 
-**Current WebGPU wire.** CEWGPU bytes have no envelope, magic, `payloadKind`,
+**Current WebGPU wire.** Carbon WebGPU bytes have no envelope, magic, `payloadKind`,
 or independent container version. They are bare Carbon v15 records resolved
-from `effect.webgpu/`, with one optional per-pass backend block. `.cewg`
-remains a separate CEWG chunk format rather than this Carbon-record wire.
+from `effect.webgpu/`, with one optional per-pass backend block. `.carbonwebgl`
+remains a separate Carbon WebGL chunk format rather than this Carbon-record wire.
 
-`CewgpuContainer` reads the optional blocks, and the shared record reader can
-auto-detect them from a description's declared size. Direct conversion from
-those descriptions into the portable reflection envelope consumed by
-`Tr2EffectRes` remains an adapter boundary.
+`CarbonWebgpuContainer` reads the optional blocks, and the shared record reader can
+auto-detect them from a description's declared size. There is no adapter
+boundary left between them and the runtime: `Tr2EffectRes.DoLoad` retains a
+`CjsCarbonEffectReader` over the same bytes and `Tr2Shader.fromCarbonBinary`
+builds the device-free graph from one description record.
 
 Versioning remains local to what it versions: Carbon's version dword governs
 the Carbon region, while `blobVersion` governs the optional backend block. An
@@ -394,8 +468,23 @@ disjointness.
 
 **Env-gated real-file proof.** `test/format/carbon-effect-corpus.test.js`, enabled
 with `CARBON_EFFECT_CORPUS_DIR`. Game bytes are never committed. Supply a
-separately acquired corpus at pinned build 3444265. The test re-emits each file
-three ways:
+separately acquired corpus at pinned build 3444265.
+
+`CARBON_EFFECT_CORPUS_DIR` must point at a **materialised tree of source
+effects** — real `.sm_hi` / `.sm_lo` / `.sm_depth` filenames under
+`effect.dx11`, `effect.dx12`, or `effect.gles2`, which is what the walker
+filters on. Two nearby directories look like corpora and are not:
+
+- a content-addressed resource store (hash-named files, no extensions) matches
+  nothing and fails as `no compiled effect files found` — the walker is
+  extension-driven, so an unextracted cache silently yields zero files;
+- a directory of **our own translated output** keeps the `.sm_*` names but
+  holds `Carbon WebGL`/`Carbon WebGPU` containers, and fails with
+  `Unsupported Carbon effect version 1196901699` — that number is the ASCII
+  `Carbon WebGL` magic read as a version dword.
+
+Both failures are loud, which is the intended behaviour; neither is a defect.
+The test re-emits each file three ways:
 
 1. every description blob through the file's own arena — proves the field order;
 2. the whole container from raw bodies and the source arena — proves the header
@@ -417,6 +506,18 @@ arena blob, so the sorted-offset policy reproduces CCP's arena exactly.
 Supply a separately acquired corpus and set `CARBON_EFFECT_CORPUS_DIR`; no
 corpus data ships with the package.
 
+**The same proof, one level up.** `test/resource/effect-res-corpus.test.js`
+closes the loop through the resource classes rather than the records: bytes →
+`Tr2EffectRes.DoLoad` → `Tr2Shader.fromCarbonBinary` → the device-free graph →
+`toCarbonBinary()` → records → bytes. Running the record-level round trip on the
+same files with no classes involved is the negative control; when the two
+disagree, the difference is the class layer's, and that is how the three
+fidelity losses it once had were found and closed — non-dynamic sampler names
+(1,631 files), authored pass-stage order (21 files), and the offset word of a
+zero-size blob (150 files), which is not always the `0xffffffff` sentinel.
+Carbon's *runtime* discards the first two; the file does not, so re-emitting the
+file it came from means keeping them.
+
 That result is the container port's central evidence. The same reader and the same
 writer reproduce, byte for byte, files whose program payloads are DXBC in two
 dialects and AIR — with no language field anywhere in the format. The metadata

package/docs/formats/dxbc/architecture.md

@@ -46,7 +46,7 @@ them.
   belong to `format-hlsl`.
 - GLSL ES generation and WebGL-specific register/storage policy belong to
   `format-webgl`.
-- WGSL generation, pass-global WebGPU binding allocation, and CEWGPU assembly
+- WGSL generation, pass-global WebGPU binding allocation, and Carbon WebGPU assembly
   belong to `format-webgpu`.
 - GPU shader-module and pipeline realization belongs to engine packages.
 

package/docs/formats/dxbc/reference/api.md

@@ -45,6 +45,7 @@ const summary = reader.Inspect(shaderBytes);
 | `isDxbc(bytes)` | Returns `true` when input starts with the DXBC magic; invalid input returns `false`. |
 | `read(bytes, options?)` | Reads one DXBC payload. |
 | `inspect(bytes, options?)` | Inspects one payload without instruction decoding. |
+| `disassemble(input, options?)` | Returns an assembly listing of the decoded instruction stream. |
 | `toJSON(value)` | Deep-converts supported values to JSON-compatible data. |
 
 The class also exposes `OUTPUT_JSON`, `OUTPUT_RAW`, input/output media metadata,
@@ -61,6 +62,33 @@ and the format's supported input type.
 Inputs may be `Uint8Array`, `ArrayBuffer`, Node `Buffer`, `DataView`, or another
 array-buffer view.
 
+## Disassembly
+
+`disassemble` renders decoded instructions as assembly text. It exists so a
+translated shader can be checked against the bytecode it was translated from:
+comparing emitted GLSL or WGSL against the original HLSL proves nothing, because
+the compiler that produced the bytecode already rewrote the program, and an
+emitter cannot be its own oracle.
+
+```js
+const listing = CjsDxbcFormat.disassemble(stageBytes);
+```
+
+Bytes, a previous `read` result, and a decoder record are all accepted, so a
+caller that already decoded the payload does not decode it twice.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `declarations` | `true` | Include declaration instructions. |
+| `numbers` | `true` | Prefix executable instructions with their index. Declarations are not numbered, so the numbering matches the order a backend walks. |
+| `indent` | `true` | Indent control-flow bodies. |
+
+Component selection prints exactly as encoded rather than normalized. A
+destination mask selects source components by position, so `mad r[2].xyw,
+r[2].xxxx, v[3].xyxz, r[5].xyxz` writes `x`, `y`, and `w` from source components
+0, 1, and 3. Normalizing that away would hide the most common class of
+translation mistake.
+
 ## Errors
 
 Invalid options and unsupported input types throw `TypeError`. Malformed DXBC

package/docs/formats/hlsl/README.md

@@ -27,8 +27,9 @@ const metadata = CjsHlslFormat.read(bytes, {
   shader bytecode.
 - Translation backends such as `@carbonenginejs/runtime-resource/formats/webgpu` can consume
   the metadata and bytecode through their own integration layers.
-- `@carbonenginejs/runtime-resource` consumes packaged portable reflection and
-  owns canonical `Tr2EffectRes`/`Tr2Shader` hydration, selection, and caching.
+- `@carbonenginejs/runtime-resource` reads the compiled container directly and
+  owns canonical `Tr2EffectRes`/`Tr2Shader` construction, selection, and
+  caching.
 - `@carbonenginejs/runtime-trinity` consumes that shader graph through its
   mutable effect/material facade, parameters, options, and sampler overrides.
 
@@ -43,7 +44,6 @@ construct canonical runtime model instances, or provide a rendering runtime.
 - [API reference](reference/api.md)
 - [Advanced analysis exports](reference/advanced-analysis.md)
 - [JSON graph reference](reference/json-graph.md)
-- [Portable body reflection](reference/portable-reflection.md)
 - [Class catalog](reference/classes/README.md)
 
 ## Compatibility

package/docs/formats/hlsl/architecture.md

@@ -27,8 +27,9 @@ caller bytes
     -> json | metadata | raw output
 ```
 
-`src/CjsHlslFormat.js` is the supported reader boundary. Binary utilities and
-format-shaped compatibility models live below `src/core` and `src/carbon`.
+`src/formats/hlsl/CjsHlslFormat.js` is the supported reader boundary. Binary
+utilities and format-shaped compatibility models live below
+`src/formats/hlsl/core` and `src/formats/hlsl/core/tr2`.
 Their same-named `Tr2*` classes are internal parser DTOs, not canonical runtime
 model identity, and are not independent package entry points.
 
@@ -40,12 +41,9 @@ model identity, and are not independent package entry points.
   planning.
 - `raw` exposes internal effect-model instances for advanced tooling and is
   not a stable schema.
-- `@carbonenginejs/runtime-resource/formats/hlsl/portable` copies one exact body into a versioned,
-  runtime-neutral source-reflection contract. Authored defaults and programs stay
-  separate from mutable renderer realization.
 
-`runtime-resource` owns canonical `Tr2EffectRes`/`Tr2Shader` hydration,
-permutation selection, and caching. `runtime-trinity` owns the mutable
+`runtime-resource` owns canonical `Tr2EffectRes`/`Tr2Shader` construction,
+permutation selection, and caching, reading the compiled container directly. `runtime-trinity` owns the mutable
 effect/material facade, parameters, authored options, and sampler overrides.
 Engines own GPU realization.
 
@@ -55,8 +53,9 @@ The graph shapes are documented in
 ## Platform boundary
 
 `read`, `inspect`, and `toJSON` operate on caller-provided bytes and work
-without filesystem access. `readFile` and the CLI are Node-specific adapters.
-The package has no runtime dependencies.
+without filesystem access; the published package is browser-only and never
+imports Node modules. Node callers read bytes themselves (`node:fs`) and pass
+them to `read`. The package has no runtime dependencies.
 
 ## Error boundary
 

package/docs/formats/hlsl/guides/hydrating-json-output.md

@@ -55,8 +55,6 @@ records without a class key remain plain JSON-compatible data. Depending on
 the caller's constructors as a serialization schema is discouraged; persist
 the documented graph fields instead.
 
-This feature is caller-selected JSON projection only. It does not consume the
-versioned portable-reflection contract and does not construct canonical
-runtime `Tr2EffectRes` or `Tr2Shader` instances. Canonical
-`CJS_EFFECT_BODY_REFLECTION` hydration belongs to
-`@carbonenginejs/runtime-resource`.
+This feature is caller-selected JSON projection only. It does not construct
+canonical runtime `Tr2EffectRes` or `Tr2Shader` instances. Those are built
+from the compiled container bytes by `@carbonenginejs/runtime-resource`.

package/docs/formats/hlsl/guides/reading-effects.md

@@ -53,8 +53,12 @@ render-state records needed for inspection and pipeline planning.
 
 ## Read a file in Node
 
+The package itself is browser-only; Node callers supply the bytes:
+
 ```js
-const effect = await CjsHlslFormat.readFile("effect.sm_hi");
+import { readFile } from "node:fs/promises";
+
+const effect = CjsHlslFormat.read(await readFile("effect.sm_hi"), { source: "effect.sm_hi" });
 ```
 
 The CLI provides the same metadata workflow:

package/docs/formats/hlsl/reference/advanced-analysis.md

@@ -31,36 +31,31 @@ an effect description is available.
 
 The returned internal parser-DTO effect resource also has
 `GetShaderByIndex(index)`. It decodes one exact permutation-table slot without
-applying global or local option overrides; it is distinct from the canonical
-runtime-resource method that hydrates and caches `Tr2Shader`. Use the versioned
-portable subpath when the result must cross a package or serialization
-boundary. Its `enumerateUniqueEffectBodies(effectRes)` helper inventories
-first-seen raw body identities without populating the parser's mutable shader
-cache.
+applying global or local option overrides, so a body-table index stays stable
+even when an application has set global effect options. It is distinct from the
+canonical `Tr2EffectRes.GetShaderByIndex`, which resolves options, hydrates a
+`Tr2Shader`, and caches it per index.
 
-## `Tr2EffectBindingManifest`
+## Binding manifest
 
-`Tr2EffectBindingManifest` is an exported advanced class that derives
-register-named constant, resource, sampler, and UAV bindings from an internal
-effect description.
+`analysis.bindingManifest` derives register-named constant, resource, sampler,
+and UAV bindings from an internal effect description. Its class is internal to
+the format and is not a published export; treat the manifest as data.
 
-```js
-import {
-    readEffectAnalysis,
-    Tr2EffectBindingManifest
-} from "@carbonenginejs/runtime-resource/formats/hlsl";
-
-const analysis = readEffectAnalysis(bytes);
-analysis.bindingManifest instanceof Tr2EffectBindingManifest;
-```
+## Source truth and realization
 
-## Render-context helpers
+Nothing this subpath returns carries a renderer handle: no shader, program,
+render-state, sampler, or library handles, and no resource sets, heap-view
+arrays, backend layouts, masks, sort values, or caches. Engines own all of
+that. Two consequences are easy to trip over:
 
-`Tr2RenderContextEnum` contains the format's stage and render-context numeric
-constants. `tr2ShaderStageName(value)` maps a known stage value to its
-readable name. Both are advanced compatibility helpers rather than a stable
-cross-package enumeration contract.
+- Register dynamic classification is not persisted. It follows per-frame
+  reader and engine policy, and is not an authored binary field.
+- Authored constant defaults are separate from the raw model's mutable
+  `constantValues`. Carbon-compatible sampler-heap realization may zero-extend
+  the latter; it cannot change the authored source prefix.
 
 ## Related documentation
 
-- [Portable body reflection](portable-reflection.md)
+- [JSON and metadata graphs](json-graph.md)
+- [Carbon compiled-effect container](../../carbon-effect-container.md)

package/docs/formats/hlsl/reference/api.md

@@ -18,11 +18,6 @@ import { CjsHlslFormat as NamedReader } from "@carbonenginejs/runtime-resource/f
 Additional named exports intended for advanced tooling are documented
 separately in [advanced-analysis.md](advanced-analysis.md).
 
-The versioned `@carbonenginejs/runtime-resource/formats/hlsl/portable` subpath exposes exact
-version-15 body-index reflection plus first-seen exact-byte unique-body
-enumeration for backend packagers. See
-[portable-reflection.md](portable-reflection.md).
-
 ## Constructor
 
 ```js
@@ -58,7 +53,6 @@ Options are reusable on an instance and can be overridden per call:
 - `CjsHlslFormat.read(input, options)` performs a one-shot read.
 - `CjsHlslFormat.inspect(input, options)` performs a one-shot inspection.
 - `CjsHlslFormat.toJSON(value)` converts output to JSON-compatible data.
-- `CjsHlslFormat.readFile(path, options)` reads and parses a file in Node.
 
 Inputs may be `Uint8Array`, `ArrayBuffer`, `Buffer`, or `DataView` values.
 Supported container versions are 8 through 15.
@@ -94,5 +88,4 @@ current working directory.
 - [Reading effects](../guides/reading-effects.md)
 - [Hydrating JSON output](../guides/hydrating-json-output.md)
 - [Advanced analysis exports](advanced-analysis.md)
-- [Portable body reflection](portable-reflection.md)
 - [Class catalog](classes/README.md)

package/docs/formats/hlsl/reference/json-graph.md

@@ -81,9 +81,7 @@ serialization-safe schema.
 
 Raw stage and library inputs retain authored `sourceConstantValueSize` /
 `sourceConstantValues` separately from Carbon-compatible mutable constant
-buffers. Libraries retain their source `cjsShaderBytecode` directly. Use
-`@carbonenginejs/runtime-resource/formats/hlsl/portable` to copy those facts into a validated
-handle-free contract.
+buffers. Libraries retain their source `cjsShaderBytecode` directly.
 
 ## Compatibility and failures
 
@@ -96,5 +94,4 @@ rather than being filled with guessed values.
 
 - [API reference](api.md)
 - [Advanced analysis exports](advanced-analysis.md)
-- [Portable body reflection](portable-reflection.md)
 - [Reading effects](../guides/reading-effects.md)

package/docs/formats/pickle.md

@@ -0,0 +1,82 @@
+# 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.
+
+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)