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

package/docs/resource/formats/webgpu/reference/wgsl-compatibility.md

@@ -19,12 +19,17 @@ each entry says why it exists and what revisiting it would take. Categories:
   explicit diagnostic rather than guessing.
 - **Bounded / temporary** — supported within stated limits; the limits are the
   first thing to widen when a shader trips them.
-
-## Adapted
-
-### `precise` floating-point operations → ordinary math + `@invariant` position
-
-Current package policy adapts DXBC `precise`, which forbids
+
+## Adapted
+
+Completed per-profile corpus-count transitions remain in
+[pinned history](https://github.com/carbonenginejs/runtime/blob/1e7f6d83684d37d6f39615beb7ab18d8c9f072cb/docs/resource/formats/webgpu/reference/wgsl-compatibility.md#adapted).
+The support limits, browser-gate scope and runtime premises below remain active;
+retiring those measurements does not widen qualification.
+
+### `precise` floating-point operations → ordinary math + `@invariant` position
+
+Current package policy adapts DXBC `precise`, which forbids
 reassociation/fusion so multi-pass position math is bit-identical.
 WGSL has no general no-contraction control, so instead of rejecting these
 operations (a previous compiler boundary for higher-quality shader profiles):
@@ -398,17 +403,12 @@ The package carries the declared thread-group size as `[1, 1, 1]`. Trinity
 effect metadata identifies compute as stage type `2`, while the decoded DXBC
 program type remains `5`; these two enums are intentionally kept separate.
 The browser gate creates and validates native shader modules, compute bind-group
-layouts, pipeline layouts, and compute pipelines. It does not dispatch work or
-expand the public render-only device API.
-
-The full corpus transition moved from 504 qualified / 33 unsupported / 0
-failed to 506 / 31 / 0: exactly the two programs named above became qualified,
-and SHA-256 comparison confirmed all 504 previously qualified package bytes
-remained identical.
-
-### Bounded 64×1×1 structured skinning compute
-
-A second, separate SM5.0 compute profile is currently exercised by
+layouts, pipeline layouts, and compute pipelines. It does not dispatch work or
+expand the public render-only device API.
+
+### Bounded 64×1×1 structured skinning compute
+
+A second, separate SM5.0 compute profile is currently exercised by
 `system/raytracing/skinvertices`. Profile selection is structural rather than
 path- or byte-hash-based, and malformed members of the selected declaration
 family fail there instead of falling through to the scalar-word profile. The
@@ -442,17 +442,12 @@ dispatching work.
 *Checked against vkd3d-shader:* its compute builtin maps to the global
 invocation identifier, its raw/structured buffers flatten to scalar words, and
 its structured loads/stores use direct backend accesses. Its Vulkan path
-relies on runtime robustness for physical out-of-bounds behavior; the explicit
-WGSL load-zero/store-drop guards above independently preserve the D3D result.
-
-The full corpus transition moved from 506 qualified / 31 unsupported / 0
-failed to 507 / 30 / 0: only `system/raytracing/skinvertices` became
-qualified, and direct byte comparison confirmed all 506 previously qualified
-packages remained identical.
-
-### Bounded 256×1×1 two-word particle sort step
-
-An isolated SM5.0/SM5.1 compute profile covers
+relies on runtime robustness for physical out-of-bounds behavior; the explicit
+WGSL load-zero/store-drop guards above independently preserve the D3D result.
+
+### Bounded 256×1×1 two-word particle sort step
+
+An isolated SM5.0/SM5.1 compute profile covers
 `particles/gpu/sortstep`. Both backends declare the same finite space-zero
 resources: immediate `cb3` with one vec4 row, typed uint buffer `t0`,
 non-coherent structured UAV `u0` with an 8-byte stride,
@@ -491,17 +486,12 @@ instruction when out of range.
 DX11 and DX12 are both substantive comparison inputs for this profile and emit
 the same WGSL and portable binding layout after finite-range normalization.
 The native browser gate validates the two-builtin 256×1×1 module, its compute
-bind-group and pipeline layouts, and the compute pipeline with zero WGSL
-warnings.
-
-The full corpus transition moved from 507 qualified / 30 unsupported / 0
-failed to 508 / 29 / 0: only `particles/gpu/sortstep` became qualified, and
-direct byte comparison confirmed all 507 previously qualified packages
-remained identical.
-
-### Bounded 256×1×1 shared-memory particle bitonic merge
-
-An isolated SM5.0/finite-SM5.1 profile covers
+bind-group and pipeline layouts, and the compute pipeline with zero WGSL
+warnings.
+
+### Bounded 256×1×1 shared-memory particle bitonic merge
+
+An isolated SM5.0/finite-SM5.1 profile covers
 `particles/gpu/sortinner`. Both forms declare a typed uint Buffer `t0`, a
 non-coherent structured UAV `u0` with an 8-byte stride, flattened and vector
 local-thread identifiers, `workgroup_id.x`, three temporary registers,
@@ -619,17 +609,12 @@ dispatch the chunk groups that cover that logical range before scheduling
 the subsequent merge profiles. This is a result-coverage obligation, not a
 shared-memory-safety precondition of this profile.
 
-The native browser gate validates the shared-memory module and both paired
-compute pipelines with zero WGSL warnings.
-
-The full corpus transition moved from 509 qualified / 28 unsupported / 0
-failed to 510 / 27 / 0: only `particles/gpu/sort` became qualified. The
-hardened direct-byte comparator cached and compared all 509 previously
-qualified package outputs, with zero byte changes and zero regressions.
-
-### `float_16` minimum precision → full-precision f32
-
-D3D minimum precision is a floor, not a format: an implementation that computes
+The native browser gate validates the shared-memory module and both paired
+compute pipelines with zero WGSL warnings.
+
+### `float_16` minimum precision → full-precision f32
+
+D3D minimum precision is a floor, not a format: an implementation that computes
 `min16float` operands at full 32-bit precision is conforming, and the registers
 are 32-bit regardless of the hint. Numeric/value operands tagged `float_16`
 therefore lower as ordinary f32 lanes — the hint is dropped, which changes
@@ -692,17 +677,12 @@ bindings intentionally produce the source's zero-load/drop-atomic behavior
 rather than the complete intended histogram.
 
 The substantive DX11 and DX12 shader pair passes the real comparison matrix
-and emits byte-identical WGSL after finite-range normalization. The native
-browser gate validates both paired compute pipelines with zero WGSL warnings.
-
-The full corpus transition moved from 510 qualified / 27 unsupported / 0
-failed to 511 / 26 / 0: only `postprocess/mergehistograms` became qualified.
-The hardened direct-byte comparator cached and compared all 510 previously
-qualified package outputs, with zero byte changes and zero regressions.
-
-### Exact 16×16×1 atomic histogram creation
-
-An isolated dual-validator profile covers `postprocess/createhistograms`.
+and emits byte-identical WGSL after finite-range normalization. The native
+browser gate validates both paired compute pipelines with zero WGSL warnings.
+
+### Exact 16×16×1 atomic histogram creation
+
+An isolated dual-validator profile covers `postprocess/createhistograms`.
 Both backends declare immediate one-row `cb0`, float `texture2d` `t0`, a
 non-coherent typed uint Buffer UAV `u0`, two-component workgroup, local, and
 global invocation identifiers, 64 stride-4 thread-group records in `g0`, and
@@ -773,17 +753,12 @@ explicit guards, but cannot produce the complete intended histogram.
 
 The substantive DX11 and DX12 pair passes the real comparison matrix and
 emits byte-identical WGSL after schedule and finite-range normalization. The
-native browser gate validates the shared module and both paired compute
-pipelines with zero WGSL warnings.
-
-The full corpus transition moved from 511 qualified / 26 unsupported / 0
-failed to 512 / 25 / 0: only `postprocess/createhistograms` became qualified.
-The hardened direct-byte comparator confirmed all 511 common previously
-qualified package outputs remained byte-identical.
-
-### Exact two-pass particle clear with effect-proven signed counter
-
-An effect-level profile covers `managed/space/specialfx/particles/gpu/clear`.
+native browser gate validates the shared module and both paired compute
+pipelines with zero WGSL warnings.
+
+### Exact two-pass particle clear with effect-proven signed counter
+
+An effect-level profile covers `managed/space/specialfx/particles/gpu/clear`.
 It requires exactly `Main.pass0.compute` and `Main.pass1.compute`, each as the
 only active stage in its pass. Reflection must identify pass 0 `u0` and pass 1
 `u1` as the same one-element `ParticleCounters` UAV with Carbon type 10,
@@ -840,18 +815,12 @@ The intentionally standalone matrix view keeps pass 0 unsupported while pass
 reconciles the exact two-pass body, stage digests, occurrence counts, per-key
 coverage, reset WGSL, and signed atomic layout before admitting that contextual
 pass. Its required native WebGPU gate compiled one unique independently
-emitted module and prepared four compute pipelines for the paired backends
-with zero WGSL warnings.
-
-The full corpus transition moved from 512 qualified / 25 unsupported / 0
-failed to 513 / 24 / 0: only
-`managed/space/specialfx/particles/gpu/clear` became qualified. The hardened
-direct-byte comparator confirmed all 512 common previously qualified package
-outputs remained byte-identical, with zero regressions.
-
-### Exact 16×16×1 shared-memory particle emit
-
-A dedicated SM5.0 profile covers
+emitted module and prepared four compute pipelines for the paired backends
+with zero WGSL warnings.
+
+### Exact 16×16×1 shared-memory particle emit
+
+A dedicated SM5.0 profile covers
 `managed/space/specialfx/particles/gpu/emit`. Admission is two-layered:
 the exact declaration family (immediate `cb3` of 4096 vec4s, stride-32
 `ParticleBuffer` UAV, signed typed counter buffer, stride-4 `DeadBuffer`,
@@ -887,18 +856,12 @@ The genuine paired effects are exercised through the optional
 inputs. With both fixtures present the suite runs with zero skips: the DX11
 package qualifies with its `Main.pass0` ready, the DX12 counterpart reports
 the comparison-only boundary, and the required native WebGPU gate compiled
-the one unique emitted module and prepared its compute pipeline with zero
-WGSL warnings.
-
-The full corpus transition moved from 506 qualified / 31 unsupported / 0
-failed to 507 / 30 / 0: only
-`managed/space/specialfx/particles/gpu/emit` became qualified, and direct
-comparison confirmed all 506 common previously qualified package outputs
-remained byte-identical.
-
-### The exact compute-profile set is complete and frozen
-
-The emit profile completes the audited GPU particle pipeline
+the one unique emitted module and prepared its compute pipeline with zero
+WGSL warnings.
+
+### The exact compute-profile set is complete and frozen
+
+The emit profile completes the audited GPU particle pipeline
 (`setdrawparameters`, `setsortargs`, `sortstep`, `sort`, `sortinner`,
 `createhistograms`, `mergehistograms`, `clear`, `emit`) alongside structured
 skinning. No further package-specific exact compute profiles should be added:
@@ -1265,174 +1228,55 @@ without the directive.
 Representative implicit-LOD and derivative cases are browser-gated with the
 directive enabled, while uniform control-flow cases verify that the directive
 is not emitted unnecessarily.
-
-## Selected-effect package provenance
-
-The versioned checkpoints in this section describe the retired flat-chunk wire
-used before the Carbon-container switchover. Their corpus counts remain
-compiler and provenance evidence; `INFO`, `META`, `PGRF`, `RFLX`, `RBLB`,
-`ANLS`, and `WGSL` are no longer stored chunks. Current bytes are Carbon
-version-15 records with derived compatibility views. See
-[Carbon WebGPU effect container](../formats/carbon-webgpu.md).
-
-At the 0.4.2 checkpoint, `BuildEffect` emitted selected-effect INFO schema
-version 2 while the binary Carbon WebGPU container remained version 1. INFO v2
-recorded the WebGPU target,
-backend-package and translator semantic versions, and a lower-case SHA-256
-digest computed over the exact compiled-effect input byte view. A conflicting
-caller digest fails closed. The reader retains legacy selected-effect INFO v1
-support and rejects unknown INFO schema versions.
-
-The 0.4.2 strong-provenance checkpoint was metadata/container-only. Its
-exact-build corpus retained 507 qualified and 30 unsupported packages with no
-failures; all 537 status/error results were unchanged. Every qualified package
-changed only in INFO, while all 507 `META`, `ANLS`, and `WGSL` payloads remained
-byte-identical.
-
-The 0.4.3 PGRF checkpoint additionally records the complete builder-derived
-source permutation topology and identity-only unique-body table. Exact build
-3444265 again retains 507 qualified and 30 unsupported packages with no
-failures and all 537 status/error results unchanged. Across the 507 qualified
-packages:
-
-- all 1,521 `META`, `ANLS`, and `WGSL` chunks are byte-identical to 0.4.2;
-- all INFO documents equal 0.4.2 after removing only the PGRF pointer and
-  normalizing the producer/translator versions;
-- an independent source-byte comparison matches all 507 PGRF documents,
-  covering 8,257 permutation variants and 3,331 unique body identities; and
-- a full 537-source header audit finds no anomalies across 8,722 permutations,
-  3,567 unique body records, and 5,155 exact aliases (maximum 972
-  permutations in one source).
-
-The final DX11/DX12 quads matrix remains qualified with matching active
-topology and both stages emitted. A new browser gate is not required for this
-checkpoint because emitted WGSL, analysis, metadata, layouts, and transforms
-are unchanged; old readers tolerate the additive chunk.
-
-The 0.4.4 selected-reflection checkpoint adds complete version-15 reflection
-for the selected body in `RFLX`, with every exact byte vector externalized into
-canonical deduplicated `RBLB` records. A body-reflection validator was rerun
-after reconstruction; package validation also reconciles INFO source identity,
-META/PGRF body identity, and every ANLS pass/stage source record. Earlier
-effect versions retain the legacy package surface. All-body reflection remains
-unsupported, so source/backend/runtime completeness remain false.
-
-The exact-build 3444265 corpus remains 507 qualified, 30 unsupported, and zero
-failed/unqualified. All 537 statuses and errors match 0.4.3. Across the 507
-qualified packages:
-
-- all `META`, `PGRF`, `ANLS`, and `WGSL` payloads are byte-identical;
-- INFO differs only by the 0.4.4 producer/translator versions and its RFLX/RBLB
-  pointer;
-- all 507 packages contain deterministic, structurally valid RFLX/RBLB;
-- reconstructing every selected portable document from RFLX/RBLB deep-equals
-  a fresh source reflection, including 16 non-default/non-first bodies; and
-- the reflected corpus covers 885 techniques, 937 passes, 1,863 stage
-  programs, 4,366 constants, 2,281 resources, 1,027 samplers, 16 UAVs, 1,589
-  render states, and 74,912 exact constant-default bytes.
-
-A packed-package Chrome smoke builds and reads a real version-15 effect in the
-browser, resolves all reflected byte references, structured-clones the JSON
-view, and fails closed after raw blob corruption with no console errors. The
-engine prepares a newly generated real `quads.sm_hi` Carbon WebGPU package with 10
-canonical bindings and zero WGSL warnings. The high-tier
-`unpacked_quadv5.sm_depth` DX11 self-pair remains exhaustively qualified across
-480 bodies, 4,480 emitted stage occurrences, and 2,240 ready pass occurrences;
-the envelope slice changes none of its WGSL.
-
-The 0.5.0 all-source-reflection checkpoint replaces selected-only RFLX v1
-output with INFO v3 plus all-unique RFLX v2/RBLB. It records complete portable
-reflection for every unique version-15 source body while ANLS/WGSL remain
-selected-backend data. `GetPortableEffectReflection(permutationIndex)` exposes
-any package permutation as a fresh, format-hlsl-validated document with owned
-byte payloads. The `resource` layer owns `Tr2EffectRes` selection, canonical
-`Tr2Shader` construction, and the per-index cache; renderer-owned handles
-remain an engine concern.
-
-That RFLX/RBLB apparatus and its accessor were removed after this checkpoint.
-`Tr2EffectRes` now reads the Carbon container directly; the entries above are
-retained as the record of what the format did at the time.
-
-An exhaustive build-3444265 oracle retains 507 qualified, 30 unsupported, and
-zero failed/unqualified results. For all 507 emitted packages, `META`, `PGRF`,
-`ANLS`, and `WGSL` are byte-identical to 0.4.4 after the expected INFO/RFLX
-schema change. Reconstructing all 8,257 permutations deep-equals fresh source
-reflection across 3,331 unique bodies, 23,949 source programs, 11,549
-techniques, 11,963 passes, 68,367 constants, 38,335 resources, 10,858
-samplers, 16 UAVs, and 1,241,456 exact constant-default bytes. The shared
-RBLB stores 5,901 deduplicated payloads / 20,625,492 bytes. Candidate packages
-total 132,688,092 bytes versus 39,643,003 bytes at 0.4.4; the median package
-ratio is 1.008 and p95 is 8.51. A second fresh build using format-hlsl 0.1.8
-produces all 507 packages byte-for-byte identically.
-
-The format-hlsl 0.1.8 prerequisite preserves Carbon's authored zero-count
-bindless descriptor ranges and requires every resource/UAV map entry to match
-exactly one signature record. The real DX12 High unpacked-Quad source validates
-all 288 unique bodies, including its zero/unbounded SRV, UAV, and sampler
-ranges. The exact DX11/DX12
-`managed/space/spaceobject/v5/quad/unpacked_quadv5.sm_depth` matrix remains
-qualified across 480 bodies per backend; DX11 emits all 4,480 stage
-occurrences and 2,240 passes, while DX12's expected unbounded-range backend
-boundary remains comparison-only for 480 pass occurrences.
-
-Explicit `SPACE_OBJECT_PPT_ENABLED=SOPPT_ENABLED` body-4 packages were then
-prepared through the unchanged engine/webgpu reader on a real WebGPU adapter.
-The DX11 package contains 144 reflected bodies and the DX12 package 288; each
-selected Main pass exposes two modules and 25 canonical bindings. Both browser
-gates compile with zero WGSL warnings.
-
-## All-body backend packaging
-
-`mode: "all"` attempts every unique source body after the resolved selection
-passes its initial translation gate. In the retired chunk wire, the result was
-stored as a `WGSB` `CJS_WGSL_BODY_SET` document. The current Carbon wire stores
-WGSL in stage program slots and bind-group/transform data in per-pass backend
-blocks; `backendBodySet` is now a derived compatibility view. Selected mode
-remains the default.
-
-The translation unit is deliberately one pass of one body rather than one
-stage. A pass owns its binding plan and resource-transform plan, so identical
-stage bytecode can legitimately translate differently when its pass-mates
-differ; sharing at stage granularity would be unsound. The Carbon wire has no
-unit table. Exact emitted program and backend-block bytes share storage through
-the arena's bytewise deduplication.
-
-All mode first requires the resolved selection to lower successfully. After
-that gate, a later body the compiler cannot lower is retained with empty
-program slots and coverage degrades to `partial`. The in-memory build result
-retains its specific reason; the wire does not. A reread can say only that the
-body carries no translated programs. Permutation topology and representable
-non-program description fields remain present, but source-stage programs are
-not stored. Non-dynamic sampler names and the authored stage order are both
-preserved.
-
-Translating every body is deliberately **not** treated as backend completeness.
-`backendComplete` and `runtimeComplete` remain false, matching the sibling
-WebGL package. The engine now realizes the documented layouts and
+
+## Selected-effect package provenance
+
+The 0.4.2–0.5.0 checkpoints describe the retired flat-chunk wire, not current
+reader APIs. Their provenance, reflection reconstruction, byte-identity, corpus
+and browser receipts remain in [pinned history](https://github.com/carbonenginejs/runtime/blob/1e7f6d83684d37d6f39615beb7ab18d8c9f072cb/docs/resource/formats/webgpu/reference/wgsl-compatibility.md#selected-effect-package-provenance).
+They are historical evidence, not a fresh qualification of this compiler.
+
+Current bytes use Carbon v15 records with derived compatibility views; the
+former INFO/PGRF/RFLX/RBLB apparatus and reflection accessor were removed.
+See [the wire owner](../formats/carbon-webgpu.md#no-stored-chunks), not those
+retired schemas, for integration.
+
+The ownership statement recorded at the 0.5.0 checkpoint is retained:
+The `resource` layer owns `Tr2EffectRes` selection, canonical
+`Tr2Shader` construction, and the per-index cache; renderer-owned handles
+remain an engine concern.
+
+The same history retains the build-3444265 source-header audit and the
+format-hlsl 0.1.8 zero-count bindless-range prerequisite. Those DX12 comparisons
+did not qualify unbounded ranges for backend execution. Current bindless
+limitations remain under [Not supported](#not-supported-fail-closed).
+All-body translation and runtime completeness are separate gates below.
+
+## All-body backend packaging
+
+The [all-mode contract](../formats/carbon-webgpu.md#all-mode) owns the
+selection-first gate, later unsupported-body representation and pass-scoped
+translation/deduplication rules. Selected mode remains the default.
+Later unsupported bodies degrade coverage to `partial`.
+The wire has no WGSB document or unit table: `backendBodySet` is a derived view.
+
+Translating every body is deliberately **not** treated as backend completeness.
+`backendComplete` and `runtimeComplete` remain false, matching the sibling
+WebGL package. The engine now realizes the documented layouts and
 `texture-2d-array` transforms and has exact draw evidence for representative
 Detail and HeatDetail families. That proof does not cover every required
 translated program, layout, and transform, and complete resource hydration and
 selection also remain open. The `BuildEffect` result carries the
-translated-body scope in `info.backendBodyCoverage`; the bytes express it
-structurally through which bodies carry programs.
-
-Historical evidence for the retired WGSB implementation: its
-every-permutation reader join resolved
-every permutation of a real Quad family package to translated programs and
-reached every unique body; the selected body's shared units were byte-identical
-to that package's derived `WGSL` view; a full corpus rebuild leaves every
-selected-mode package byte-identical with unchanged statuses; every effect in
-the corpus builds in all-body mode with no build failures, the small number of
-partial results losing bodies only to already-documented compiler boundaries;
-and 202 translated modules from bodies that selected-mode packaging never
-emitted were compiled on a real WebGPU adapter with zero warnings, including a
-High `.sm_depth` explicit PPT-on Detail-family package with version-3
-resource-transform units and the exact bounded particle-clear compute profile.
-That is compiler and module evidence for the newly packaged bodies. It is not a
-prepared-pipeline or rendered claim for them.
-
-Two defects in the first implementation were found only by building the whole
-corpus in all-body mode, not by the package suite: stage selection outside the
+translated-body scope in `info.backendBodyCoverage`; the bytes express it
+structurally through which bodies carry programs.
+
+The [retired WGSB receipt](https://github.com/carbonenginejs/runtime/blob/1e7f6d83684d37d6f39615beb7ab18d8c9f072cb/docs/resource/formats/webgpu/reference/wgsl-compatibility.md#all-body-backend-packaging)
+records every-permutation joins, selected-mode byte stability, the all-body
+corpus sweep and 202 newly exposed modules compiled with zero WGSL warnings.
+It is compiler/module evidence, not a prepared-pipeline or rendered claim.
+
+Two defects in the first implementation were found only by building the whole
+corpus in all-body mode, not by the package suite: stage selection outside the
 per-body guard turned one geometry-stage body into a whole-package failure, and
 the all-body path initially omitted the particle-clear effect-profile
 preflight. The synthetic fixtures cannot express either condition, so an