@plasius/gpu-shader 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -44,8 +44,8 @@ The root export must remain browser-safe. Reflection and qualification tooling
44
44
  are loaded through subpaths so browser bundles do not eagerly include Node.js
45
45
  or browser-automation dependencies.
46
46
 
47
- The primary browser-safe APIs are `createGpuRecordCodec`,
48
- `computeGpuAbiHash`, `validateModelShaderCompatibility`,
47
+ The primary browser-safe APIs are `assertImmutableAssetVersion`,
48
+ `createGpuRecordCodec`, `computeGpuAbiHash`, `validateModelShaderCompatibility`,
49
49
  `loadShaderStyleProfile`, `prepareStyleProfile`,
50
50
  `createShaderStyleController`, and `activateStyleProfile`, together with the
51
51
  strict manifest parsers and versioned contracts. The build APIs
@@ -70,31 +70,42 @@ Release preparation always opens a short-lived `release/v*` pull request with
70
70
  an installation token from the repository's release-preparation GitHub App.
71
71
  The workflow refuses to mutate metadata unless `main` is protected and
72
72
  repository auto-merge is enabled. The workflow-dispatch SHA must equal the
73
- prepared commit before any release artifact is built. If preparation merges a
74
- package or changelog metadata commit, the original run remains bound to its
75
- earlier SHA and stops before publication. Start a second `bump: none` run from
76
- the newly prepared `main` commit; `bump: none` resumes that exact version and
77
- does not replace version preparation.
73
+ protected-main validation commit before any release artifact is built. If
74
+ preparation merges package or changelog metadata, the original run remains
75
+ bound to its earlier SHA and stops before publication. Start a second
76
+ `bump: none` run from the newly prepared `main` commit; `bump: none` resumes
77
+ that exact version and does not replace version preparation.
78
78
 
79
79
  CD then crosses an explicit privilege boundary. The read-only,
80
80
  unprivileged `validate-and-pack` job waits for successful push CI on the exact
81
- prepared commit, installs dependencies, runs all release gates, and packs the
82
- package once. It uploads an attempt-scoped artifact containing exactly the npm
83
- tarball, CycloneDX SBOM, and transport manifest; the artifact and manifest bind
84
- their file sizes, digests, package identity, prepared commit, and workflow run.
81
+ validation commit, checks out the immutable release source commit, installs
82
+ dependencies, runs all release gates, and packs the package once. For a new
83
+ publication those commits must be identical. During recovery of an exact
84
+ already-published version, the release commit is derived from npm SLSA
85
+ provenance, must match the existing tag, and must remain an ancestor of the
86
+ validation commit. The attempt-scoped artifact contains exactly the npm
87
+ tarball, reproducible CycloneDX SBOM, and transport manifest; the release uses
88
+ a fixed Node/npm toolchain, and npm's volatile SBOM UUID and timestamp are
89
+ deterministically derived from the release source before schema v2 binds both
90
+ commit authorities, the file sizes and digests, package identity, and workflow
91
+ run.
85
92
  The production `publish` job does not check out the repository or execute
86
93
  checked-out package code. It downloads the artifact by its exact run-scoped identity
87
94
  and GitHub artifact digest, revalidates the three-file closure and every bound
88
95
  digest, resolves authoritative live npm state, and preflights the complete
89
96
  GitHub tag/release/SBOM state before any mutation. Prerelease status and the npm
90
97
  dist-tag are derived from the transported semantic version rather than retry
91
- inputs. Only then does the job attest, tag, publish, and finalize the release.
98
+ inputs. For a new publication, only then does the job attest, tag, publish, and
99
+ finalize the release. For an already-published recovery it verifies and
100
+ reconciles the same immutable state but does not create replacement tarball or
101
+ SBOM attestations.
92
102
 
93
103
  Publication and recovery use that same tarball identity: an existing registry
94
104
  version is accepted only when its SHA-512 integrity is identical. CD requires
95
- npm SLSA provenance for the exact `main` commit and `cd.yml` workflow, verifies
96
- npm registry signatures, and confirms the GitHub tag and non-draft release
97
- point to the same commit.
105
+ npm SLSA provenance for the immutable release commit and protected-main
106
+ `cd.yml`, verifies npm registry signatures, and confirms the GitHub tag and
107
+ non-draft release point to that release commit. Recovery does not create new
108
+ tarball or SBOM attestations under the newer validation commit.
98
109
 
99
110
  The first public version requires the production-environment `NPM_TOKEN`
100
111
  because npm trusted publishing cannot be configured until the package exists.
@@ -232,6 +243,16 @@ does not replace the model-facing hash.
232
243
  Style profiles map roles such as `material`, `lighting`, `outline`, `shadow`,
233
244
  and `post-processing` to exact immutable shader versions.
234
245
 
246
+ Every model, GPU-interface, shader, and profile version carried by a manifest
247
+ or immutable reference is checked with `assertImmutableAssetVersion`.
248
+ Reference versions are rejected before their corresponding catalog resolver
249
+ runs; loaded manifest versions are rejected before any child asset resolves.
250
+ Exact tokens such as `1`, `v1`, `1.2.3`, and
251
+ `2026.07.13-a1` are valid. Mutable aliases (`latest`, `stable`, `default`,
252
+ `main`, and similar), ranges, wildcards, URLs, and path syntax are rejected.
253
+ Catalog channels may use friendly names, but a resolved reference must contain
254
+ the exact immutable version.
255
+
235
256
  ```ts
236
257
  import {
237
258
  activateStyleProfile,
@@ -281,7 +302,10 @@ It contains 15 representative physical cells and one required Ubuntu Chromium
281
302
  SwiftShader smoke cell. All 16 are blocking; only the 15 physical cells count
282
303
  toward stable physical support. A skip, timeout, unavailable runner or adapter,
283
304
  device loss, missing result, stale evidence, or unexpected result fails the
284
- gate.
305
+ gate. The checked-in file is the exact canonical JSON policy artifact; its byte
306
+ digest must equal `SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES[0].matrixSha256`.
307
+ Any policy-byte or digest change requires complete shader-inventory
308
+ requalification and does not itself qualify a shader.
285
309
 
286
310
  Candidate archives may contain only declarative JSON, WGSL, and bounded binary
287
311
  fixtures. Physical runners execute a pinned trusted harness from this
@@ -424,7 +448,9 @@ standing line-coverage exception, replaced by 100% compile-unit inventory and
424
448
  - [Documentation index](docs/index.md)
425
449
  - [Framework design](docs/design/wgsl-shader-compatibility-and-style-framework.md)
426
450
  - [ADR: final WGSL is the source of truth](docs/adrs/adr-0001-final-assembled-wgsl-is-the-interface-source-of-truth.md)
451
+ - [ADR: immutable GPU asset versions before catalog access](docs/adrs/adr-0003-immutable-gpu-asset-versions-before-catalog-access.md)
427
452
  - [TDR: qualification evidence and trusted runners](docs/tdrs/tdr-0001-qualification-evidence-and-trusted-runners.md)
453
+ - [TDR: exact immutable GPU asset version grammar](docs/tdrs/tdr-0002-exact-immutable-gpu-asset-version-grammar.md)
428
454
  - [Physical fleet readiness](docs/operations/physical-fleet-readiness.md)
429
455
  - [Security policy](SECURITY.md)
430
456
  - [Contributing](CONTRIBUTING.md)