@carbonenginejs/runtime-resource 0.12.0 → 0.12.1

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

@@ -3,11 +3,9 @@
 Status: Evolving
 Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
 Audience: Shader-tool authors and engine integrators
-Summary: Lists the public `CjsWebgpuFormat` profile, one-shot helpers, options, and output contracts.
+Summary: Lists the public WebGPU format profile, byte-oriented helpers, options, and output contracts.
 
-## Export
-
-The package root exports `CjsWebgpuFormat` as both a named and default export:
+## Import
 
 ```js
 import CjsWebgpuFormat, {
@@ -15,15 +13,19 @@ import CjsWebgpuFormat, {
 } from "@carbonenginejs/runtime-resource/formats/webgpu";
 ```
 
+The default and named exports refer to the same class.
+
 ## Reusable profile
 
-Construct a profile when several operations share output, source, permutation,
-schema, or class-registration options:
+Construct a profile when several operations share output, source, schema, or
+class-registration options. `permutation` is also reusable by `AnalyzeEffect`
+and `BuildEffect`; current `Read` and `Inspect` derive the translated body or
+Carbon defaults and do not consume that profile field:
 
 ```js
 const reader = new WebgpuFormat({
     emit: "json",
-    source: "example.cewgpu",
+    source: "res:/graphics/effect.webgpu/example.sm_hi",
     decodeInstructions: true,
     permutation: null
 });
@@ -32,166 +34,164 @@ const reader = new WebgpuFormat({
 | Instance method | Purpose |
 | --- | --- |
 | `SetValues(options)` | Merges reusable profile defaults. |
-| `GetValues(options?)` | Returns effective values with optional per-call overrides. |
+| `GetValues(options?)` | Returns effective values with optional overrides. |
 | `SetClasses(classes)` | Registers several package-shape constructors. |
 | `SetClass(type, Class)` | Registers or removes one constructor. |
 | `GetClass(type)` | Returns one registered constructor. |
 | `HasClass(type)` | Reports whether a constructor is registered. |
-| `Read(bytes, options?)` | Reads CEWGPU bytes as JSON or a raw package. |
-| `Inspect(bytes, options?)` | Returns a package summary. |
-| `Build(chunks)` | Builds CEWGPU bytes from ordered chunks. |
-| `AnalyzeEffect(bytes, options?)` | Builds normalized analysis from compiled effect bytes. |
-| `BuildEffect(bytes, options?)` | Converts one selected effect body/pass scope into CEWGPU data. |
-| `BuildShaderIr(input, options?)` | Builds validated shader IR from DXBC bytes or decoded input. |
-| `BuildWgsl(input, options?)` | Emits a supported typed shader as WGSL. |
-| `BuildWgslBindingPlan(programs, options?)` | Allocates one binding layout across a complete pass. |
+| `Read(bytes, options?)` | Reads Carbon-record CEWGPU bytes. |
+| `Inspect(bytes, options?)` | Returns a compact container summary. |
+| `AnalyzeEffect(bytes, options?)` | Analyzes compiled-effect bytes without packaging. |
+| `BuildEffect(bytes, options?)` | Translates a version-15 effect to CEWGPU bytes. |
+| `BuildShaderIr(input, options?)` | Builds validated shader IR from DXBC or decoded input. |
+| `BuildWgsl(input, options?)` | Emits supported shader IR as WGSL. |
+| `BuildWgslBindingPlan(programs, options?)` | Allocates one binding layout across a pass. |
 | `BuildWgslSet(entries)` | Assembles emitted shaders and pass layouts. |
 | `ToJSON(value)` | Converts format output to JSON-compatible data. |
 
-`Read` currently returns plain data. Class registrations are validated and
-stored for forward compatibility but do not hydrate the returned package.
-Raw output is an internal zero-copy package view; callers must treat its chunk
-bytes as immutable and reread/rebuild after any byte change.
+There is no `Build(chunks)` method. The current wire is a Carbon record tree,
+not a generic chunk container.
 
-## One-shot static helpers
-
-The static helpers use lower camel case and share the implementation of the
-instance methods:
+## Static helpers
 
 | Static helper | Purpose |
 | --- | --- |
-| `isCewgpu(bytes)` | Checks the `CWGP` package magic. |
-| `read(bytes, options?)` | Reads one package. |
-| `inspect(bytes, options?)` | Inspects one package. |
-| `build(chunks)` | Builds one package. |
+| `isCewgpu(bytes)` | Reports whether bytes have the Carbon-v15 shape. |
+| `read(bytes, options?)` | Reads one container. |
+| `inspect(bytes, options?)` | Inspects one container. |
 | `analyzeEffect(bytes, options?)` | Analyzes one compiled effect. |
-| `buildEffect(bytes, options?)` | Builds one selected effect body/pass scope. |
+| `buildEffect(bytes, options?)` | Builds CEWGPU bytes from a version-15 effect. |
 | `buildShaderIr(input, options?)` | Builds shader IR. |
 | `buildWgsl(input, options?)` | Emits WGSL. |
 | `buildWgslBindingPlan(programs, options?)` | Allocates a pass binding plan. |
-| `buildWgslSet(entries)` | Builds a portable shader set. |
+| `buildWgslSet(entries)` | Builds a portable WGSL set. |
 | `toJSON(value)` | Converts output to JSON-compatible data. |
 
+`isCewgpu` checks the first dword for Carbon version 15. CEWGPU has no private
+magic or payload tag, so this is a shape check rather than backend identity.
+Callers establish identity through the resource path that supplied the bytes.
+
 ## Profile options
 
 | Option | Meaning |
 | --- | --- |
-| `emit` | `"json"` by default or `"raw"` for the internal package object. |
+| `emit` | `"json"` by default or `"raw"` for the internal container reader. |
 | `source` | Caller-owned diagnostic label; it is never opened. |
-| `decodeInstructions` | Includes decoded instruction and shader IR detail during analysis. |
-| `permutation` | Exact NAME=VALUE assertions as an array or `Map`. |
+| `decodeInstructions` | Includes decoded instruction and IR detail during analysis. |
+| `permutation` | Exact `NAME=VALUE` assertions for `AnalyzeEffect` and `BuildEffect`; ignored by current `Read` and `Inspect`. |
 | `schema` | Optional caller schema record retained by the profile. |
 | `classes` | Optional constructor registrations keyed by `CLASS_KEYS`. |
 
-`AnalyzeEffect` decodes real selected-body stage bytes for return-only
-diagnostics. `decodeInstructions: false` retains compact DXBC program metadata
-without instruction or IR trees. `BuildEffect` keeps those bytes transient for
-WGSL compilation and writes compact selected-body `ANLS` diagnostics instead.
-Both `AnalyzeEffect` and `BuildEffect` reject malformed, duplicate, unknown, or
-unresolved permutation assertions rather than silently selecting a default.
+Class registrations are validated and stored for forward compatibility.
+Current JSON reads return plain data rather than hydrated package classes.
+
+Raw output is an internal reader over the same bytes. It is not a second wire
+format and should not be persisted.
+
+## Read result
+
+JSON `Read` returns:
+
+- `format`, Carbon `version`, and `sourcePath`;
+- derived `info` and `metadata`;
+- the complete derived `permutationGraph`;
+- derived `analysis`, `wgsl`, and `backendBodySet`;
+- convenience `stages`, `shaders`, and `layouts` arrays.
+
+These records are computed from the Carbon header, descriptions, WGSL program
+slots, and backend blocks. They are not stored chunks. The old `chunks` field
+is intentionally absent.
+
+`Inspect` reports the source label, Carbon version, compiler-version bytes,
+permutation count, distinct-body count, and resolved stage/shader/layout
+counts.
+
+## Effect analysis
+
+`AnalyzeEffect` accepts supported compiled-effect versions for diagnostic
+analysis. It resolves exact permutation assertions and may include decoded
+DXBC instructions and compiler IR.
+
+`BuildEffect` is narrower: current packaging requires the version-15 record
+layout. The wire retains every permutation row and non-program description
+field that the mapping can represent; non-dynamic sampler names are
+unrecoverable and stage order is canonicalized. Source-stage DXBC and the
+caller's source hash are not retained in the wire. The build result retains
+full portable source reflection, including source program bytes. Compiler IR
+is transient and is neither stored in the wire nor returned by `BuildEffect`.
+
+Unknown, duplicate, or unresolved permutation assertions fail closed.
 
 ## Effect-package options
 
-`BuildEffect` and `buildEffect` accept `mode: "selected"`, which remains the
-default. They resolve one permutation body and emit complete passes within the
-requested stage selection.
-
-`mode: "all"` additionally translates every unique source body into a `WGSB`
-chunk and reports `backendBodyCoverage: "all-unique"`, or `"partial"` when some
-body could not be lowered. It requires complete version-15 source reflection and
-fails closed on versions 8-14, which carry no validated body inventory. The
-orchestration compatibility option `allPermutations: true` selects the same
-mode, and `allPermutations: false` means selected mode.
-
-`CewgpuPackage.GetBackendBodyPrograms(permutationIndex)` resolves any
-permutation to its translated passes, defaulting to `META.bodyIndex`. It returns
-null when the package carries no all-body graph, and an explicitly unsupported
-record when that body could not be lowered.
-
-Both `GetBackendBodyPrograms` and `GetPortableEffectReflection` return null
-until the package has passed canonical envelope validation. Every documented
-read entry point validates, so this is transparent to normal consumers; it
-prevents a hand-assembled or tampered container from being hydrated as though
-it had been checked.
-
-`source` remains a caller-owned diagnostic label. An optional
-`sourceIdentity.logicalPath` records the canonical resource identity
-independently and may differ from that label. The builder records the exact
-source byte length and computes a lower-case SHA-256 digest over the active
-input byte view. A caller-supplied `sourceIdentity.sha256` is accepted only
-when it matches that digest.
-
-For version-15 input, `BuildEffect` emits INFO schema version 3 with explicit
-WebGPU target, backend-package name/version, translator provenance, and
-source/backend body coverage. Versions 8-14 emit INFO v2 without reflection.
-The CEWGPU binary container remains version 1. The reader retains legacy INFO
-v1, pre-PGRF INFO v2, and selected-body INFO v2/RFLX v1 support.
-
-New packages also emit a `PGRF` permutation graph and expose it as
-`result.permutationGraph`, JSON-read `permutationGraph`, and raw
-`CewgpuPackage.permutationGraph`. The graph contains every ordered axis,
-Cartesian permutation index, option-index tuple, source record, and
-package-local unique-body key/digest. `Inspect` reports `permutationCount` and
-`uniqueBodyCount`. This is complete source topology with identity-only bodies;
-it does not provide backend translation by itself.
-
-For version-15 input, new packages emit complete all-unique source reflection
-in RFLX v2 and exact referenced byte payloads in one shared `RBLB`. Build
-results expose
-these as `result.reflection` and `result.reflectionBlobs`. JSON reads expose
-`reflection` plus `reflectionBlobByteLength`; raw reads expose
-`CewgpuPackage.reflection`, `reflectionBlobBytes`, and
-`GetReflectionBlob(referenceOrKey)`. Raw reads also expose
-`GetPortableEffectReflection(permutationIndex)`: it performs the PGRF/RFLX
-join, expands every referenced payload to fresh owned `Uint8Array` values, and
-reruns the format-hlsl portable validator. Its optional index defaults to
-`META.bodyIndex`; legacy selected-body RFLX v1 accepts only its selected
-permutation. `GetReflectionBlob` remains the lower-level accessor and requires
-an object reference to match its stored key, offset, byte length, and digest
-exactly. `Inspect` reports reflection body/source-program/blob counts and blob
-byte length. The body count covers every PGRF unique body. The selector joins
-`META.bodyIndex -> PGRF.variants[index].bodyKey -> RFLX.bodies[].bodyKey`.
-Earlier source versions omit both chunks.
-
-The returned structural qualification separates preservation from execution.
-`packageValid` reports successful container construction. Version-15 INFO v3
-reports `sourceComplete: true` for the exact input's portable semantic graph
-while `backendComplete` and `runtimeComplete` remain false. Versions 8-14
-report all three completeness flags false. Source completeness does not embed
-raw body records, translate every body, construct a live `Tr2EffectRes`, or
-prove prepared pipelines/rendering. `GetPortableEffectReflection` reconstructs
-and validates fresh owned plain portable data; `runtime-resource`
-`Tr2EffectRes` performs canonical runtime-class hydration and selection. The
-accessor does not construct renderer-owned handles, layouts, resource sets, or
-stage programs.
+`mode: "selected"` is the default. It translates the resolved body's
+requested complete passes while keeping every permutation row and
+representable non-program description fields in the container.
+
+`mode: "all"` first lowers the resolved selection, so an unsupported resolved
+body aborts the build. After that gate succeeds, unsupported later bodies
+remain in the container with empty program slots and appear as unsupported in
+the in-memory body-set view. `allPermutations: true` is a compatibility
+spelling for all mode.
+
+`selection` can name a technique, pass index, and complete stage list.
+`bindingPolicy.sharedIdentities` may name compatible cross-stage resources
+that are allowed to share one physical binding.
+
+`source` remains a diagnostic label. `sourceIdentity` and `outputPath` are
+returned build provenance; the wire's backend identity still comes from the
+consumer's resource path.
+
+## Build result and qualification
+
+`BuildEffect` returns:
+
+- `bytes`;
+- build-time `info` and `metadata`;
+- `permutationGraph`, portable `reflection`, and `reflectionBlobs`;
+- selected `analysis` and `wgsl`;
+- `backendBodySet` for all mode;
+- an `inspection` obtained by rereading the emitted bytes; and
+- `qualification`.
+
+The richer fields are caller evidence and are not separately stored in the
+container.
+
+`qualification.packageValid` reports structural construction. It does not
+claim that every body translated, that a pipeline was prepared, or that a
+draw succeeded. `backendComplete` and `runtimeComplete` retain those broader
+boundaries.
+
+## Binding-plan and WGSL-set helpers
+
+`BuildWgslBindingPlan` takes the complete program set for one pass.
+Unshared D3D tuples receive stage-qualified `scopeIdentity` values. A tuple is
+shared only when its base identity appears in `sharedIdentities` and the
+declarations are compatible.
+
+`BuildWgslSet` validates shader keys, layouts, numeric slots, and resource
+transforms. Ordinary sets use version 2. A proven physical-resource
+coalescing uses version 3 and carries an explicit transform recipe.
 
 ## Static metadata
 
-The class exposes output-mode constants, accepted class keys, media and input
-type metadata, implementation status, the CEWGPU format label, analysis format,
-and package version.
+The class exposes `OUTPUT_JSON`, `OUTPUT_RAW`, `CLASS_KEYS`, `type`,
+`mediaTypes`, `inputTypes`, `outputTypes`, `debugOutputTypes`,
+`implementationStatus`, `format`, `analysisFormat`, and `packageVersion`.
 
 ## Errors
 
-Malformed package input and unsafe analysis paths throw or report a
-`CjsWebgpuReadError` internally. Unsupported WGSL semantics fail closed with
-the operation, stage, and source context needed to identify the boundary.
-Duplicate/non-ASCII chunk tags are rejected. A declared
-`tr2-effect-webgpu` package also fails closed on missing or malformed JSON
-chunks, unsupported document versions, or inconsistent INFO/META/ANLS/WGSL
-identity, counts, keys, layouts, selection, and completeness fields. Declared
-PGRF pointers, exact INFO-v3 chunk digests, schemas, counts, variant tuples,
-body references, and the selected index/options are reconciled as part of the
-same gate. Optional
-INFO/RFLX/RBLB reflection units additionally reconcile the exact RFLX digest,
-every PGRF body and representative, portable closed schemas, exact blob
-references/digests, and the selected body's ANLS pass/stage source identities.
-Strict effect validation is activated by the `INFO.packageKind` marker;
-effect-only consumers must require that marker because unmarked CEWGPU
-containers intentionally remain generic.
+Reads fail closed on malformed Carbon records, sparse or misordered
+permutation tables, out-of-range arena references, trailing record bytes, or a
+program-bearing stage WebGPU cannot express.
+
+Builds additionally fail on unsupported source versions, invalid selection,
+unsupported compiler semantics, ambiguous binding plans, non-`main` entry
+points, and malformed backend blocks.
 
 ## Related documentation
 
 - [Effect packaging guide](../guides/effect-packaging.md)
-- [CEWGPU package format](../formats/cewgpu.md)
+- [CEWGPU effect container](../formats/cewgpu.md)
+- [WGSL compatibility](wgsl-compatibility.md)
 - [Class-purpose catalog](classes/README.md)

package/docs/formats/webgpu/reference/classes/README.md

@@ -1,66 +1,9 @@
-# Class catalog
+# WebGPU class catalog
 
-Status: Evolving
+Status: Deprecated
 Scope: `@carbonenginejs/runtime-resource/formats/webgpu` maintained classes
 Audience: Users, maintainers, and automated readers
-Summary: Provides one-sentence purpose descriptors for every maintained class in the WebGPU format package.
+Summary: Points to the canonical package-wide class catalog after format-package consolidation.
 
-<!-- class:CjsWebgpuFormat -->
-## `CjsWebgpuFormat`
-
-CarbonEngineJS-facing format surface for `.cewgpu` WebGPU packages, plus an offline effect-analysis helper built on `format-hlsl` and `format-dxbc`.
-
-- Export: `@carbonenginejs/runtime-resource/formats/webgpu`
-- Source: `src/CjsWebgpuFormat.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CjsWebgpuReadError -->
-## `CjsWebgpuReadError`
-
-Error raised when a CEWGPU package or WebGPU analysis pass cannot be completed safely.
-
-- Export: None
-- Source: `src/core/errors.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CjsBinaryReader -->
-## `CjsBinaryReader`
-
-Minimal little-endian binary reader for the flat CEWGPU chunk container.
-
-- Export: None
-- Source: `src/core/cewgpu/binary.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CewgpuPackage -->
-## `CewgpuPackage`
-
-Reader for CarbonEngineJS CEWGPU shader packages.
-
-- Export: None
-- Source: `src/core/cewgpu/CewgpuPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CewgpuPackageBuilder -->
-## `CewgpuPackageBuilder`
-
-Builds CarbonEngineJS CEWGPU package bytes.
-
-- Export: None
-- Source: `src/core/cewgpu/CewgpuPackageBuilder.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:ReflectionBlobStore -->
-## `ReflectionBlobStore`
-
-Builds the deterministic deduplicated byte arena for complete source reflection.
-
-- Export: None
-- Source: `src/core/effectReflectionPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation
+The maintained WebGPU entries now live in the
+[package-wide formats class catalog](../../../../reference/classes/formats.md#webgpu).