@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.1

package/docs/resource/formats/webgpu/formats/carbon-webgpu.md

@@ -34,24 +34,12 @@ that arbitrary version-15 bytes contain WGSL.
 
 ## Wire layout
 
-The shared Carbon container contract is documented in
-[Carbon compiled-effect container](../../carbon-effect-container.md). In
-outline, the file contains:
-
-- Carbon's version-15 header, compiler version, source-hash slot (zero-filled
-  by the current builder), string table, and permutation axes;
-- one dense offset-table row for every permutation;
-- one stored description tree for every distinct emitted body, with exact
-  emitted-description-byte aliases sharing that body; and
-- one optional backend block after each pass's render states.
-
-The Carbon region is backend-invariant. Carbon WebGPU substitutes:
-
-- UTF-8 WGSL in each translated stage's `shaderData`;
-- the fixed entry point `main`, which is omitted from the wire because every
-  current lowerer must emit it; and
-- a versioned backend block for bind-group layouts and resource transforms
-  that Carbon reflection cannot derive.
+The [shared Carbon container contract](../../carbon-effect-container.md)
+owns the header, arena, dense permutation rows, emitted-body aliases, and
+optional per-pass block placement. The current builder zero-fills the source hash.
+WebGPU substitutes UTF-8 WGSL in each translated stage's `shaderData` and adds
+backend layouts and resource transforms that Carbon reflection cannot derive.
+Every current lowerer emits entry point `main`, so it is omitted from the wire.
 
 A stage with zero program bytes is reflection-only. This is how selected-mode
 packages retain untranslated bodies and how unsupported Carbon stage types
@@ -83,22 +71,18 @@ Like WebGL, the sole emit returns a complete document, including
 shared translation units). The retired `raw` emit exposed the internal
 `CarbonWebgpuContainer` because the former chunk package could not express the
 body set in JSON. Consumers now read the document, not the internal reader.
-
-## Building
-
-`BuildEffect` accepts version-15 compiled-effect bytes only. It parses the
-complete input, resolves the requested permutation, lowers selected programs,
-and writes a new Carbon v15 container. Source-stage program bytes and the
-caller's source hash are not retained in the emitted wire.
-
-The returned build record is richer than the bytes. Its `info`, `metadata`,
-`permutationGraph`, `analysis`, `wgsl`, `backendBodySet`, `inspection`, and
-`qualification` fields are build-time evidence for callers. They must not be
-interpreted as separate records stored in the container.
-
-### Selected mode
-
-`mode: "selected"` is the default. The container still carries every
+
+## Building
+
+`BuildEffect` rebuilds version-15 input; source-stage program bytes and the
+caller's source hash are not retained in the wire. Its richer
+[build result](../reference/api.md#build-result-and-qualification) is caller
+evidence, not additional stored records. The modes below control translation,
+not which source permutation rows survive.
+
+### Selected mode
+
+`mode: "selected"` is the default. The container still carries every
 permutation row and representable non-program description fields, but only the
 resolved body's requested complete passes carry translated WGSL. Other bodies
 have zero-length program slots.
@@ -125,41 +109,26 @@ program and backend blobs; the wire does not contain a separate unit table.
 The shared Carbon reader validates version, count caps, dense positional
 offsets, arena bounds, and exact record ends. The WebGPU layer then checks each
 distinct body and rejects any program-bearing stage outside vertex, pixel, and
-compute. Geometry, hull, and domain reflection may remain only when the
-corresponding program slot is empty.
-
-Inspection reports:
-
-- Carbon version and compiler-version bytes;
-- permutation and distinct-body counts; and
-- stage, shader, and layout counts for the resolved translation.
-
-The JSON read shape contains `info`, `metadata`, `permutationGraph`,
-`analysis`, `wgsl`, `backendBodySet`, and convenience `stages`, `shaders`, and
-`layouts` arrays. `analysis`, `wgsl`, and `backendBodySet` are derived views.
-
-## Backend block
-
-Each translated pass may reference one version-1 backend block from the Carbon
-arena. The block carries:
-
-- physical bind-group and binding slots;
-- resource kind, stage visibility, register identity, generated symbol, and
-  optional structured-buffer or array-layer metadata; and
-- resource-transform family, identifier, and ordered source inputs.
-
-Strings inside the block are inline and length-prefixed. The block contains no
-arena offsets, so its bytes remain independent of the arena's content sort and
-can deduplicate safely. An unknown backend-block version is skipped instead of
-being guessed.
-
-Fields such as `identity`, `layoutKey`, transform output, and fixed layer
-numbers are reconstructed from the block plus record position. Backend-block
-version 1 stores visibility but not the original `scopeIdentity`; the reader
-reconstructs `${identity}@${visibility[0]}`. A multi-stage shared binding
-therefore rereads as stage-qualified rather than recovering its original bare
-scope. Callers must not use the wire view to infer that original sharing
-decision.
+compute. Geometry, hull, and domain reflection may remain only when the
+corresponding program slot is empty.
+
+See the API's [read result](../reference/api.md#read-result) for inspection
+counts and derived JSON fields. These views are computed from the record tree,
+not separately stored documents.
+
+## Backend block
+
+Each translated pass may reference one arena-backed WebGPU block. Its leading
+byte is backend engine ID `2`, not a version; no block-version byte follows.
+`CarbonWebgpuContainer` treats absent or foreign-backend blocks as no WebGPU
+backend data. Once the WebGPU block parser is selected, a mismatched engine ID
+or unparsed trailing bytes is an error, not a silent skip.
+
+The shared [optional trailing block](../../carbon-effect-container.md#the-optional-trailing-block)
+owns the field layout, inline strings, arena-independent deduplication, and
+reconstructed fields. In particular, the wire does not retain the original
+`scopeIdentity`: a multi-stage shared binding rereads as stage-qualified.
+Do not infer its original sharing decision from this view.
 
 ## Structured WGSL set
 

package/docs/resource/formats/webgpu/guides/effect-packaging.md

@@ -41,94 +41,50 @@ records build provenance in the returned result; it does not change the wire
 identity, which belongs to the resource path used to load the emitted bytes.
 When `sourceIdentity.sha256` is supplied, the build checks it against the exact
 input bytes.
-
-## What the bytes contain
-
-The emitted bytes are a stock Carbon v15 effect container:
-
-- every source permutation remains in the dense offset table;
-- each distinct emitted description body is stored once, based on exact emitted
-  bytes rather than the source alias partition;
-- representable non-program description/reflection fields remain in the Carbon
-  tree, non-dynamic sampler names and the authored stage order included;
-- translated stage program slots contain UTF-8 WGSL;
-- untranslated or unsupported stage program slots have zero length; and
-- translated passes may carry a WebGPU backend block with bind-group layouts
-  and resource transforms.
-
-Source-stage DXBC and the original source hash are not stored in Carbon WebGPU bytes.
-The build result no longer carries any source-reflection document; it was removed with the intermediate format. What remains in memory is
-`BuildEffect` result.
-
-There are no stored `INFO`, `META`, `PGRF`, `RFLX`, `ANLS`, `WGSL`, or `WGSB`
-chunks. The read API derives compatible JSON views from the Carbon records.
-
-## Translation modes
-
-### Selected
-
-`mode: "selected"` is the default. It translates the resolved body's requested
-complete passes. Every permutation row and representable non-program
-description fields remain in the container, but untranslated program slots are
-empty.
-
-Selected mode does not discard permutations. It narrows backend translation.
-
-### All
-
-`mode: "all"` first lowers the resolved selection; an unsupported resolved body
-aborts the build. Once that precondition succeeds, later bodies that lower
-successfully carry WGSL and backend blocks. A later body outside the compiler's
-current boundary remains present with non-program description fields and empty
-program slots. The in-memory body-set view records its reason; a reread can
-report only that it carries no translated programs.
-
-Passes, rather than individual stages, are the translation unit because a pass
-owns one binding plan and resource-transform plan.
-
-The compatibility option `allPermutations: true` selects all mode.
-`allPermutations: false` selects the requested `mode` or the selected default.
-
-## Build result
-
-The returned record contains build-time evidence in addition to `bytes`:
-
-| Field | Purpose |
-| --- | --- |
-| `bytes` | Carbon v15 Carbon WebGPU bytes. |
-| `info` | Producer, source, translation-scope, and completeness evidence. |
-| `metadata` | Resolved selection and caller provenance. |
-| `permutationGraph` | Complete source permutation and body-alias view. |
-| `analysis` | Selected-body diagnostic analysis. |
-| `wgsl` | Emitted shaders, layouts, and transforms. |
-| `backendBodySet` | All-body translation result, or `null` in selected mode. |
-| `inspection` | Summary obtained by rereading the emitted bytes. |
-| `qualification` | Structural build outcome and translation counts. |
-
-These fields are returned data. They are not separate documents stored beside
-the Carbon records.
-
-`qualification.packageValid` means the emitted container passed structural
-validation. It is not prepared-pipeline or rendered evidence.
-`backendComplete` and `runtimeComplete` remain false until the broader compiler,
-resource-hydration, selection, and execution gates are satisfied.
-
-## Read the result
-
-```js
+
+## What the bytes contain
+
+The [wire layout](../formats/carbon-webgpu.md#wire-layout) preserves permutation
+topology and representable reflection, replaces source programs with WGSL or
+empty slots, and may carry per-pass backend data. It stores neither source DXBC nor
+the original source hash, and has no separate compatibility-view chunks.
+
+## Translation modes
+
+### Selected
+
+The default [selected mode](../formats/carbon-webgpu.md#selected-mode) translates
+requested complete passes without discarding permutations.
+
+### All
+
+[All mode](../formats/carbon-webgpu.md#all-mode) first requires the resolved
+selection to translate, then attempts every distinct body. Passes own binding
+and transform plans; stages are not independent translation units. See the
+[API options](../reference/api.md#effect-package-options) for compatibility flags.
+
+## Build result
+
+Use `result.bytes` as the artifact. The
+[API result table](../reference/api.md#build-result-and-qualification) owns the
+additional evidence fields and completeness gates: a structurally valid package
+does not prove executable or rendered output.
+
+## Read the result
+
+```js
 const summary = CjsWebgpuFormat.inspect(packageBytes, {
     source: "res:/graphics/effect.webgpu/example.sm_hi"
 });
 
 const data = CjsWebgpuFormat.read(packageBytes, {
     source: "res:/graphics/effect.webgpu/example.sm_hi"
-});
-```
-
-The JSON read derives `info`, `metadata`, `permutationGraph`, `analysis`,
-`wgsl`, and `backendBodySet` views from the one record tree. It also exposes
-convenience `stages`, `shaders`, and `layouts` arrays.
-
+});
+```
+
+The [read result](../reference/api.md#read-result) is a derived JSON document,
+not another stored representation.
+
 The `raw` emit was retired (closure recorded 2026-08-13). Reads return the
 derived document; the only emit name is `"json"`, and unsupported values throw
 `TypeError`. The container reader remains internal. See
@@ -150,40 +106,22 @@ const plan = CjsWebgpuFormat.buildWgslBindingPlan(
 Unshared identities receive separate `@vertex` or `@fragment`
 `scopeIdentity` values and numeric slots. Shared identities retain one bare
 scope with combined visibility.
-
-## Resource transforms
-
-When semantic metadata proves that several logical textures may be represented
-by one physical array texture, the derived WGSL set uses version 3 and carries
-a `texture-2d-array` transform recipe.
-
-The consumer must assemble the named layers, match size/mips/sample
-type/format, and bind the resulting array through the transformed layout.
-Missing layers fail closed. A version-3 document is not executable evidence by
-itself.
-
-## Errors
-
-Conversion fails explicitly when:
-
-- the source is not a version-15 compiled effect;
-- a permutation assertion is unknown or unresolved;
-- the permutation table is sparse, misordered, out of bounds, or malformed;
-- the technique, pass, or requested stage does not exist;
-- the requested stage list is duplicated or incomplete;
-- the selected shader uses unsupported semantics;
-- resource declarations cannot form one unambiguous pass layout;
-- a lowerer emits an entry point other than `main`; or
-- the emitted Carbon records or backend block fail structural validation.
-
-Unsupported selected programs abort selected-mode packaging and also abort the
-initial selection gate in all mode. After that gate succeeds, an unsupported
-later body remains represented with empty program slots and an explicit
-in-memory derived status.
-
-## Related documentation
-
-- [Carbon WebGPU effect container](../formats/carbon-webgpu.md)
+
+## Resource transforms
+
+Follow the [version-3 resource-transform contract](../formats/carbon-webgpu.md#version-3-resource-transforms)
+to assemble and bind compatible array layers; missing layers fail closed.
+A version-3 document is not executable evidence by itself.
+
+## Errors
+
+See [API errors](../reference/api.md#errors) for rejected inputs and selections,
+and [all mode](../formats/carbon-webgpu.md#all-mode) for the distinction between
+an initial failure and a later unsupported body.
+
+## Related documentation
+
+- [Carbon WebGPU effect container](../formats/carbon-webgpu.md)
 - [Public API reference](../reference/api.md)
 - [WGSL compatibility](../reference/wgsl-compatibility.md)
 - [Carbon compiled-effect container](../../carbon-effect-container.md)

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

@@ -82,16 +82,12 @@ Callers establish identity through the resource path that supplied the bytes.
 | `schema` | Optional caller schema record retained by the profile. |
 | `classes` | Optional constructor registrations keyed by `CLASS_KEYS`. |
 
-Class registrations are validated and stored for forward compatibility.
-Current JSON reads return plain data rather than hydrated package classes.
-
-There is one emit. The document it returns carries every view a consumer needs,
-including `permutationGraph` and the complete `backendBodySet`, so there is no
-second read mode to choose and no reader object to hold.
-
-## Read result
-
-JSON `Read` returns:
+Class registrations are validated and stored for forward compatibility.
+Current JSON reads return plain data rather than hydrated package classes.
+
+## Read result
+
+JSON `Read` returns:
 
 - `format`, Carbon `version`, and `sourcePath`;
 - derived `info` and `metadata`;
@@ -110,60 +106,58 @@ 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, including non-dynamic sampler names and
-the file's authored pass-stage order. Source-stage DXBC and the caller's source
-hash are not retained in the wire. 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
-
-`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.
+analysis. It resolves exact permutation assertions and may include decoded
+DXBC instructions and compiler IR.
+
+`BuildEffect` requires version-15 input; the
+[wire contract](../formats/carbon-webgpu.md#building) owns preservation and
+translation modes. Compiler IR is transient: neither stored in the wire nor
+returned by `BuildEffect`.
+
+Unknown, duplicate, or unresolved permutation assertions fail closed.
+
+## Effect-package options
+
+`mode` is `"selected"` by default or `"all"`; see
+[selected mode](../formats/carbon-webgpu.md#selected-mode) and
+[all mode](../formats/carbon-webgpu.md#all-mode), including the initial
+resolved-body translation gate. `allPermutations: true` selects all mode;
+`false` uses the requested `mode` or selected default.
+
+`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`;
-- 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
-
+
+`BuildEffect` returns:
+
+| Field | Purpose |
+| --- | --- |
+| `bytes` | Carbon v15 Carbon WebGPU bytes. |
+| `info` | Producer, source, translation-scope, and completeness evidence. |
+| `metadata` | Resolved selection and caller provenance. |
+| `permutationGraph` | Complete source permutation and body-alias view. |
+| `analysis` | Selected-body diagnostic analysis. |
+| `wgsl` | Emitted shaders, layouts, and transforms. |
+| `backendBodySet` | All-body translation result, or `null` in selected mode. |
+| `inspection` | Summary obtained by rereading the emitted bytes. |
+| `qualification` | Structural build outcome and translation counts. |
+
+These fields are caller evidence, not separately stored documents. No
+source-reflection document or compiler IR is returned.
+
+`qualification.packageValid` reports structural validation, not complete
+translation, pipeline preparation or a successful draw. `backendComplete`
+and `runtimeComplete` remain false until the broader compiler,
+resource-hydration, selection and execution gates are satisfied.
+
+## 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
@@ -183,15 +177,18 @@ output.
 ## Errors
 
 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
-
+permutation tables, out-of-range arena references, trailing record bytes, or a
+program-bearing stage WebGPU cannot express.
+
+Builds additionally reject unsupported source versions; unknown, duplicate or
+unresolved permutation assertions; missing techniques, passes or stages;
+duplicated or incomplete requested stage lists; unsupported selected-program
+semantics; ambiguous pass layouts; non-`main` entry points; and malformed
+emitted records or backend blocks. The [all-mode contract](../formats/carbon-webgpu.md#all-mode)
+distinguishes the initial selection failure from a later unsupported body.
+
+## Related documentation
+
 - [Effect packaging guide](../guides/effect-packaging.md)
 - [Carbon WebGPU effect container](../formats/carbon-webgpu.md)
 - [WGSL compatibility](wgsl-compatibility.md)