@plasius/gpu-shader 0.1.1 → 0.1.3

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,14 +44,37 @@ 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
52
52
  `reflectGpuInterface`, `validateAssembledGpuInterface`, and
53
53
  `generateGpuInterfaceArtifacts` are exposed only from the Node subpath.
54
54
 
55
+ ### Bounded contract snapshot boundary
56
+
57
+ Every browser-safe manifest, compatibility, matrix, inventory, qualification,
58
+ evidence, and runtime-reference parser snapshots contract data before reading
59
+ schema fields. The snapshot accepts only JSON primitives, local-realm plain
60
+ objects, and dense ordinary arrays whose fields are own enumerable data
61
+ properties. Accessors, symbols, hidden fields, behavioral prototypes, sparse
62
+ or custom arrays, cycles, invalid Unicode, and over-limit graphs fail closed.
63
+
64
+ The snapshot never invokes a property getter or Proxy `get` trap. JavaScript
65
+ cannot portably detect a transparent Proxy, so its `getPrototypeOf`, `ownKeys`,
66
+ and `getOwnPropertyDescriptor` reflection traps may run. Any reflection failure
67
+ is replaced by a fixed bounded diagnostic; the thrown provider value is not
68
+ interpolated or retained as `error.cause`. Cross-realm or behavioral values
69
+ must first be JSON-decoded or structured-cloned into the current realm.
70
+
71
+ Runtime/model contracts and complete qualification products use separate
72
+ finite policies. The exact depth, node, property, element, per-string,
73
+ aggregate-string, aggregate-data, and encoded-input ceilings are recorded in
74
+ [TDR 0003](docs/tdrs/tdr-0003-bounded-contract-snapshot-policies.md). Valid
75
+ plain JSON retains byte-identical canonical JSON and ABI hashes. Changing a
76
+ policy requires affected shader requalification.
77
+
55
78
  ## Installation
56
79
 
57
80
  After an approved GitHub CD release publishes the package:
@@ -211,6 +234,19 @@ The codec is little-endian, bounds checked, strict about unknown or missing
211
234
  members, and writes deterministic zero padding. Unsupported or non-finite
212
235
  values fail before upload.
213
236
 
237
+ For network/storage input, prefer `parseJsonBytes` followed by the strict
238
+ manifest parser. Both encoded bytes and the resulting data graph are bounded;
239
+ syntax, UTF-8, snapshot, and schema failures do not retain parser/provider
240
+ causes.
241
+
242
+ Byte input is brand-checked and copied with captured TypedArray intrinsics, so
243
+ `Buffer`, Uint8Array subclasses, and cross-realm Uint8Arrays remain supported
244
+ without reading caller `byteLength`, `constructor`, iterator, or index
245
+ properties. Proxy-wrapped typed arrays fail the intrinsic brand check. Runtime
246
+ style-load request fields and catalog asset-result fields must likewise be
247
+ enumerable own data properties; catalog and attestation callback failures are
248
+ reported with fixed cause-free diagnostics.
249
+
214
250
  ## Validate a model and shader
215
251
 
216
252
  ```ts
@@ -243,6 +279,16 @@ does not replace the model-facing hash.
243
279
  Style profiles map roles such as `material`, `lighting`, `outline`, `shadow`,
244
280
  and `post-processing` to exact immutable shader versions.
245
281
 
282
+ Every model, GPU-interface, shader, and profile version carried by a manifest
283
+ or immutable reference is checked with `assertImmutableAssetVersion`.
284
+ Reference versions are rejected before their corresponding catalog resolver
285
+ runs; loaded manifest versions are rejected before any child asset resolves.
286
+ Exact tokens such as `1`, `v1`, `1.2.3`, and
287
+ `2026.07.13-a1` are valid. Mutable aliases (`latest`, `stable`, `default`,
288
+ `main`, and similar), ranges, wildcards, URLs, and path syntax are rejected.
289
+ Catalog channels may use friendly names, but a resolved reference must contain
290
+ the exact immutable version.
291
+
246
292
  ```ts
247
293
  import {
248
294
  activateStyleProfile,
@@ -438,7 +484,9 @@ standing line-coverage exception, replaced by 100% compile-unit inventory and
438
484
  - [Documentation index](docs/index.md)
439
485
  - [Framework design](docs/design/wgsl-shader-compatibility-and-style-framework.md)
440
486
  - [ADR: final WGSL is the source of truth](docs/adrs/adr-0001-final-assembled-wgsl-is-the-interface-source-of-truth.md)
487
+ - [ADR: immutable GPU asset versions before catalog access](docs/adrs/adr-0003-immutable-gpu-asset-versions-before-catalog-access.md)
441
488
  - [TDR: qualification evidence and trusted runners](docs/tdrs/tdr-0001-qualification-evidence-and-trusted-runners.md)
489
+ - [TDR: exact immutable GPU asset version grammar](docs/tdrs/tdr-0002-exact-immutable-gpu-asset-version-grammar.md)
442
490
  - [Physical fleet readiness](docs/operations/physical-fleet-readiness.md)
443
491
  - [Security policy](SECURITY.md)
444
492
  - [Contributing](CONTRIBUTING.md)