@plasius/gpu-shader 0.1.1 → 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
@@ -243,6 +243,16 @@ does not replace the model-facing hash.
243
243
  Style profiles map roles such as `material`, `lighting`, `outline`, `shadow`,
244
244
  and `post-processing` to exact immutable shader versions.
245
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
+
246
256
  ```ts
247
257
  import {
248
258
  activateStyleProfile,
@@ -438,7 +448,9 @@ standing line-coverage exception, replaced by 100% compile-unit inventory and
438
448
  - [Documentation index](docs/index.md)
439
449
  - [Framework design](docs/design/wgsl-shader-compatibility-and-style-framework.md)
440
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)
441
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)
442
454
  - [Physical fleet readiness](docs/operations/physical-fleet-readiness.md)
443
455
  - [Security policy](SECURITY.md)
444
456
  - [Contributing](CONTRIBUTING.md)
package/dist/cli.cjs CHANGED
@@ -606,6 +606,7 @@ ${canonicalizeGpuContract(core)}`
606
606
  // src/contracts.ts
607
607
  var GPU_INTERFACE_MANIFEST_VERSION = "1.0.0";
608
608
  var SHADER_VERSION_MANIFEST_VERSION = "1.0.0";
609
+ var SHADER_STYLE_PROFILE_MANIFEST_VERSION = "1.0.0";
609
610
  var SHADER_COMPILE_UNIT_VERSION = "1.0.0";
610
611
  var SHADER_VALIDATION_EVIDENCE_VERSION = "1.0.0";
611
612
  var STABLE_WEBGPU_MATRIX_VERSION = "1.0.0";
@@ -621,6 +622,29 @@ var SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES = [
621
622
  Object.freeze(SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES);
622
623
  var SUPPORTED_ADDITIVE_WEBGPU_MATRIX_POLICIES = Object.freeze([]);
623
624
 
625
+ // src/asset-version.ts
626
+ var ASSET_VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._-]{0,127}$/u;
627
+ var MUTABLE_VERSION_ALIASES = /* @__PURE__ */ new Set([
628
+ "latest",
629
+ "current",
630
+ "stable",
631
+ "preview",
632
+ "default",
633
+ "production",
634
+ "canary",
635
+ "next",
636
+ "head",
637
+ "main"
638
+ ]);
639
+ var X_WILDCARD_SEGMENT_PATTERN = /^(?:[vV])?[xX](?:\.|-|$)|\.[xX](?:\.|-|$)/u;
640
+ var IMMUTABLE_VERSION_ERROR_MESSAGE = "Immutable asset version must be an exact token up to 128 characters; mutable aliases, ranges, wildcards, and URLs are not allowed.";
641
+ function assertImmutableAssetVersion(value) {
642
+ if (typeof value !== "string" || !ASSET_VERSION_PATTERN.test(value) || MUTABLE_VERSION_ALIASES.has(value.toLowerCase()) || X_WILDCARD_SEGMENT_PATTERN.test(value)) {
643
+ throw new TypeError(IMMUTABLE_VERSION_ERROR_MESSAGE);
644
+ }
645
+ return value;
646
+ }
647
+
624
648
  // src/requirements-validation.ts
625
649
  var ENABLED_FEATURES = Object.freeze({
626
650
  f16: "shader-f16",
@@ -948,6 +972,15 @@ function validateShaderDerivedRequirements(input) {
948
972
  // src/manifest-validation.ts
949
973
  var stages = ["vertex", "fragment", "compute"];
950
974
  var roles = ["material", "lighting", "outline", "shadow", "post-processing"];
975
+ function detachedJson(value, path2) {
976
+ try {
977
+ return JSON.parse(canonicalizeGpuContract(value));
978
+ } catch (cause) {
979
+ const detail = cause instanceof Error ? cause.message : "Contract snapshot failed.";
980
+ const boundedDetail = [...detail].slice(0, 512).join("");
981
+ throw new TypeError(`${path2} must contain detached JSON contract data: ${boundedDetail}`, { cause });
982
+ }
983
+ }
951
984
  function object(value, path2) {
952
985
  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${path2} must be an object.`);
953
986
  return value;
@@ -968,6 +1001,16 @@ function token(value, path2) {
968
1001
  if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/u.test(result) || result.includes("..")) throw new TypeError(`${path2} must be a safe token.`);
969
1002
  return result;
970
1003
  }
1004
+ function immutableVersion(value, path2) {
1005
+ try {
1006
+ return assertImmutableAssetVersion(value);
1007
+ } catch (cause) {
1008
+ throw new TypeError(
1009
+ `${path2} must be an immutable asset version: exact token required; mutable aliases, ranges, wildcards, and URLs are not allowed.`,
1010
+ { cause }
1011
+ );
1012
+ }
1013
+ }
971
1014
  function enumeration(value, values, path2) {
972
1015
  if (!values.includes(value)) throw new TypeError(`${path2} is invalid.`);
973
1016
  return value;
@@ -1241,7 +1284,7 @@ function interfaceRef(value, path2) {
1241
1284
  const input = object(value, path2);
1242
1285
  exact(input, ["interfaceId", "interfaceVersion", "manifestUri", "manifestSha256", "interfaceAbiHash", "modelAbiHash"], path2);
1243
1286
  token(input.interfaceId, `${path2}.interfaceId`);
1244
- token(input.interfaceVersion, `${path2}.interfaceVersion`);
1287
+ immutableVersion(input.interfaceVersion, `${path2}.interfaceVersion`);
1245
1288
  uri(input.manifestUri, `${path2}.manifestUri`);
1246
1289
  digest(input.manifestSha256, `${path2}.manifestSha256`);
1247
1290
  digest(input.interfaceAbiHash, `${path2}.interfaceAbiHash`);
@@ -1379,7 +1422,7 @@ function pipeline(value, path2, moduleIds) {
1379
1422
  return input;
1380
1423
  }
1381
1424
  function parseSerializableGpuPipelineDescriptors(value, moduleIds, path2 = "pipelines") {
1382
- const parsed = array(value, path2).map((item, index) => pipeline(item, `${path2}[${index}]`, new Set(moduleIds)));
1425
+ const parsed = array(detachedJson(value, path2), path2).map((item, index) => pipeline(item, `${path2}[${index}]`, new Set(moduleIds)));
1383
1426
  unique(parsed, (item) => item.pipelineId, path2);
1384
1427
  return freeze(parsed);
1385
1428
  }
@@ -1387,7 +1430,7 @@ function compatibleModel(value, path2) {
1387
1430
  const input = object(value, path2);
1388
1431
  exact(input, ["interfaceId", "interfaceVersion", "manifestSha256", "interfaceAbiHash", "modelAbiHash"], path2);
1389
1432
  token(input.interfaceId, `${path2}.interfaceId`);
1390
- token(input.interfaceVersion, `${path2}.interfaceVersion`);
1433
+ immutableVersion(input.interfaceVersion, `${path2}.interfaceVersion`);
1391
1434
  digest(input.manifestSha256, `${path2}.manifestSha256`);
1392
1435
  digest(input.interfaceAbiHash, `${path2}.interfaceAbiHash`);
1393
1436
  digest(input.modelAbiHash, `${path2}.modelAbiHash`);
@@ -1400,7 +1443,7 @@ function validationEvidenceRef(value, path2) {
1400
1443
  uri(evidence.uri, `${path2}.uri`);
1401
1444
  digest(evidence.sha256, `${path2}.sha256`);
1402
1445
  token(evidence.matrixId, `${path2}.matrixId`);
1403
- token(evidence.matrixVersion, `${path2}.matrixVersion`);
1446
+ immutableVersion(evidence.matrixVersion, `${path2}.matrixVersion`);
1404
1447
  digest(evidence.matrixSha256, `${path2}.matrixSha256`);
1405
1448
  const attestation = object(evidence.attestationRef, `${path2}.attestationRef`);
1406
1449
  exact(attestation, ["uri", "sha256"], `${path2}.attestationRef`);
@@ -1427,11 +1470,11 @@ function reflectedRecordBindingSize(record) {
1427
1470
  return Math.ceil(unrounded / record.alignment) * record.alignment;
1428
1471
  }
1429
1472
  function parseGpuInterfaceManifest(value) {
1430
- const input = object(value, "GpuInterfaceManifest");
1473
+ const input = object(detachedJson(value, "GpuInterfaceManifest"), "GpuInterfaceManifest");
1431
1474
  exact(input, ["contractVersion", "interfaceId", "interfaceVersion", "modules", "records", "bindings", "entryPoints", "vertexInputs", "overrides", "modelAbi", "modelAbiHash", "interfaceAbiHash", "generatedBy"], "GpuInterfaceManifest");
1432
1475
  if (input.contractVersion !== GPU_INTERFACE_MANIFEST_VERSION) throw new TypeError("Unsupported GPU interface contract version.");
1433
1476
  token(input.interfaceId, "GpuInterfaceManifest.interfaceId");
1434
- token(input.interfaceVersion, "GpuInterfaceManifest.interfaceVersion");
1477
+ immutableVersion(input.interfaceVersion, "GpuInterfaceManifest.interfaceVersion");
1435
1478
  const moduleValues = array(input.modules, "GpuInterfaceManifest.modules");
1436
1479
  if (moduleValues.length === 0) throw new TypeError("GpuInterfaceManifest.modules must not be empty.");
1437
1480
  const moduleIds = moduleValues.map((value2, index) => {
@@ -1613,11 +1656,11 @@ function parseGpuInterfaceManifest(value) {
1613
1656
  return freeze(input);
1614
1657
  }
1615
1658
  function parseShaderVersionManifest(value) {
1616
- const input = object(value, "ShaderVersionManifest");
1659
+ const input = object(detachedJson(value, "ShaderVersionManifest"), "ShaderVersionManifest");
1617
1660
  exact(input, ["contractVersion", "shaderId", "version", "modules", "gpuInterface", "pipelines", "renderRoles", "compatibleModelInterfaces", "requirements", "shaderAbiHash", "validationEvidence", "additionalValidationEvidence"], "ShaderVersionManifest");
1618
1661
  if (input.contractVersion !== SHADER_VERSION_MANIFEST_VERSION) throw new TypeError("Unsupported shader manifest contract version.");
1619
1662
  token(input.shaderId, "ShaderVersionManifest.shaderId");
1620
- token(input.version, "ShaderVersionManifest.version");
1663
+ immutableVersion(input.version, "ShaderVersionManifest.version");
1621
1664
  const moduleValues = array(input.modules, "ShaderVersionManifest.modules");
1622
1665
  if (moduleValues.length === 0) throw new TypeError("ShaderVersionManifest.modules must not be empty.");
1623
1666
  const moduleIds = moduleValues.map((item, index) => {
@@ -1730,7 +1773,7 @@ function parseShaderVersionManifest(value) {
1730
1773
  return freeze(input);
1731
1774
  }
1732
1775
  function parseShaderVersionManifestCore(value) {
1733
- const input = object(value, "ShaderVersionManifestCore");
1776
+ const input = object(detachedJson(value, "ShaderVersionManifestCore"), "ShaderVersionManifestCore");
1734
1777
  if ("validationEvidence" in input || "additionalValidationEvidence" in input) {
1735
1778
  throw new TypeError("ShaderVersionManifestCore must not contain validationEvidence or additionalValidationEvidence.");
1736
1779
  }
@@ -1755,11 +1798,59 @@ function parseShaderVersionManifestCore(value) {
1755
1798
  void additionalValidationEvidence;
1756
1799
  return freeze(core);
1757
1800
  }
1801
+ function parseShaderStyleProfileManifest(value) {
1802
+ const input = object(detachedJson(value, "ShaderStyleProfileManifest"), "ShaderStyleProfileManifest");
1803
+ exact(input, ["contractVersion", "profileId", "version", "style", "roles", "compatibleModelInterfaces", "requiredSemantics", "requiredValidationScopes"], "ShaderStyleProfileManifest");
1804
+ if (input.contractVersion !== SHADER_STYLE_PROFILE_MANIFEST_VERSION) throw new TypeError("Unsupported style-profile contract version.");
1805
+ token(input.profileId, "ShaderStyleProfileManifest.profileId");
1806
+ immutableVersion(input.version, "ShaderStyleProfileManifest.version");
1807
+ token(input.style, "ShaderStyleProfileManifest.style");
1808
+ const roleValues = array(input.roles, "ShaderStyleProfileManifest.roles", 5);
1809
+ if (roleValues.length === 0) throw new TypeError("ShaderStyleProfileManifest.roles must not be empty.");
1810
+ const roleNames = [];
1811
+ roleValues.forEach((item, index) => {
1812
+ const path2 = `ShaderStyleProfileManifest.roles[${index}]`;
1813
+ const role = object(item, path2);
1814
+ exact(role, ["role", "shader"], path2);
1815
+ roleNames.push(enumeration(role.role, roles, `${path2}.role`));
1816
+ const shader = object(role.shader, `${path2}.shader`);
1817
+ exact(shader, ["shaderId", "version", "manifestUri", "manifestSha256"], `${path2}.shader`);
1818
+ token(shader.shaderId, `${path2}.shader.shaderId`);
1819
+ immutableVersion(shader.version, `${path2}.shader.version`);
1820
+ uri(shader.manifestUri, `${path2}.shader.manifestUri`);
1821
+ digest(shader.manifestSha256, `${path2}.shader.manifestSha256`);
1822
+ });
1823
+ unique(roleNames, String, "ShaderStyleProfileManifest.roles");
1824
+ const compatible = array(input.compatibleModelInterfaces, "ShaderStyleProfileManifest.compatibleModelInterfaces").map((item, index) => compatibleModel(item, `ShaderStyleProfileManifest.compatibleModelInterfaces[${index}]`));
1825
+ if (compatible.length === 0) throw new TypeError("ShaderStyleProfileManifest.compatibleModelInterfaces must not be empty.");
1826
+ unique(compatible, (item) => `${item.interfaceId}:${item.interfaceVersion}:${item.manifestSha256}:${item.interfaceAbiHash}:${item.modelAbiHash}`, "ShaderStyleProfileManifest.compatibleModelInterfaces");
1827
+ tokenArray(input.requiredSemantics, "ShaderStyleProfileManifest.requiredSemantics");
1828
+ const requiredValidationScopes = array(input.requiredValidationScopes, "ShaderStyleProfileManifest.requiredValidationScopes").map((item, index) => {
1829
+ const path2 = `ShaderStyleProfileManifest.requiredValidationScopes[${index}]`;
1830
+ const requirement = object(item, path2);
1831
+ exact(requirement, ["scope", "matrixId", "matrixVersion", "matrixSha256"], path2);
1832
+ const scope = token(requirement.scope, `${path2}.scope`);
1833
+ if (scope === "universal") throw new TypeError(`${path2}.scope must not use the reserved universal scope.`);
1834
+ token(requirement.matrixId, `${path2}.matrixId`);
1835
+ immutableVersion(requirement.matrixVersion, `${path2}.matrixVersion`);
1836
+ const matrixSha256 = digest(requirement.matrixSha256, `${path2}.matrixSha256`);
1837
+ if (SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES.some((policy) => policy.matrixSha256 === matrixSha256)) {
1838
+ throw new TypeError(`${path2} must require an additive matrix policy, not the universal matrix policy.`);
1839
+ }
1840
+ if (!SUPPORTED_ADDITIVE_WEBGPU_MATRIX_POLICIES.some((policy) => scope === policy.scope && requirement.matrixId === policy.matrixId && requirement.matrixVersion === policy.matrixVersion && matrixSha256 === policy.matrixSha256)) {
1841
+ throw new TypeError(`${path2} is not a supported additive WebGPU matrix policy.`);
1842
+ }
1843
+ return requirement;
1844
+ });
1845
+ unique(requiredValidationScopes, (item) => String(item.scope), "ShaderStyleProfileManifest.requiredValidationScopes scopes");
1846
+ unique(requiredValidationScopes, (item) => String(item.matrixSha256), "ShaderStyleProfileManifest.requiredValidationScopes matrix policies");
1847
+ return freeze(input);
1848
+ }
1758
1849
  function parseModelGpuCompatibilityDescriptor(value) {
1759
- const input = object(value, "ModelGpuCompatibilityDescriptor");
1850
+ const input = object(detachedJson(value, "ModelGpuCompatibilityDescriptor"), "ModelGpuCompatibilityDescriptor");
1760
1851
  exact(input, ["modelId", "version", "gpuInterface", "modelAbiHash", "providedSemantics", "defaultStyleProfile"], "ModelGpuCompatibilityDescriptor");
1761
1852
  token(input.modelId, "ModelGpuCompatibilityDescriptor.modelId");
1762
- token(input.version, "ModelGpuCompatibilityDescriptor.version");
1853
+ immutableVersion(input.version, "ModelGpuCompatibilityDescriptor.version");
1763
1854
  const gpuInterface = interfaceRef(input.gpuInterface, "ModelGpuCompatibilityDescriptor.gpuInterface");
1764
1855
  const modelAbiHash = digest(input.modelAbiHash, "ModelGpuCompatibilityDescriptor.modelAbiHash");
1765
1856
  if (gpuInterface.modelAbiHash !== modelAbiHash) throw new TypeError("ModelGpuCompatibilityDescriptor.gpuInterface.modelAbiHash differs from modelAbiHash.");
@@ -1768,14 +1859,17 @@ function parseModelGpuCompatibilityDescriptor(value) {
1768
1859
  const profile = object(input.defaultStyleProfile, "ModelGpuCompatibilityDescriptor.defaultStyleProfile");
1769
1860
  exact(profile, ["profileId", "version", "manifestUri", "manifestSha256"], "ModelGpuCompatibilityDescriptor.defaultStyleProfile");
1770
1861
  token(profile.profileId, "ModelGpuCompatibilityDescriptor.defaultStyleProfile.profileId");
1771
- token(profile.version, "ModelGpuCompatibilityDescriptor.defaultStyleProfile.version");
1862
+ immutableVersion(profile.version, "ModelGpuCompatibilityDescriptor.defaultStyleProfile.version");
1772
1863
  uri(profile.manifestUri, "ModelGpuCompatibilityDescriptor.defaultStyleProfile.manifestUri");
1773
1864
  digest(profile.manifestSha256, "ModelGpuCompatibilityDescriptor.defaultStyleProfile.manifestSha256");
1774
1865
  }
1775
1866
  return freeze(input);
1776
1867
  }
1777
1868
  function parseShaderQualificationModelCompatibilityFixture(value) {
1778
- const input = object(value, "ShaderQualificationModelCompatibilityFixture");
1869
+ const input = object(
1870
+ detachedJson(value, "ShaderQualificationModelCompatibilityFixture"),
1871
+ "ShaderQualificationModelCompatibilityFixture"
1872
+ );
1779
1873
  exact(input, ["contractVersion", "fixtureId", "model"], "ShaderQualificationModelCompatibilityFixture");
1780
1874
  if (input.contractVersion !== SHADER_QUALIFICATION_FIXTURE_VERSION) throw new TypeError("Unsupported model compatibility fixture version.");
1781
1875
  token(input.fixtureId, "ShaderQualificationModelCompatibilityFixture.fixtureId");
@@ -1791,6 +1885,11 @@ function issue(code, message, path2) {
1791
1885
  function object2(value) {
1792
1886
  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
1793
1887
  }
1888
+ function freezeJson(value) {
1889
+ if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
1890
+ for (const child of Object.values(value)) freezeJson(child);
1891
+ return Object.freeze(value);
1892
+ }
1794
1893
  function exactKeys(value, keys2) {
1795
1894
  const expected = new Set(keys2);
1796
1895
  return Object.keys(value).every((key) => expected.has(key)) && keys2.every((key) => key in value);
@@ -1798,6 +1897,14 @@ function exactKeys(value, keys2) {
1798
1897
  function safeToken(value) {
1799
1898
  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/u.test(value) && !value.includes("..");
1800
1899
  }
1900
+ function immutableVersion2(value) {
1901
+ try {
1902
+ assertImmutableAssetVersion(value);
1903
+ return true;
1904
+ } catch {
1905
+ return false;
1906
+ }
1907
+ }
1801
1908
  function validSha(value) {
1802
1909
  try {
1803
1910
  asSha256Hex(String(value));
@@ -1807,8 +1914,20 @@ function validSha(value) {
1807
1914
  }
1808
1915
  }
1809
1916
  function validateCompileUnitInventory(value) {
1810
- const envelope = object2(value);
1811
- const candidate = envelope && "inventory" in envelope ? object2(value.inventory) : envelope;
1917
+ let snapshot;
1918
+ try {
1919
+ snapshot = JSON.parse(canonicalizeGpuContract(value));
1920
+ } catch (cause) {
1921
+ return {
1922
+ ok: false,
1923
+ diagnostics: [issue(
1924
+ "invalid-contract",
1925
+ cause instanceof Error ? cause.message : "Compile-unit inventory must contain detached JSON data."
1926
+ )]
1927
+ };
1928
+ }
1929
+ const envelope = object2(snapshot);
1930
+ const candidate = envelope && Object.hasOwn(envelope, "inventory") ? object2(snapshot.inventory) : envelope;
1812
1931
  const diagnostics = [];
1813
1932
  if (!candidate || !exactKeys(candidate, ["contractVersion", "fragments", "compileUnits"])) {
1814
1933
  return { ok: false, diagnostics: [issue("invalid-contract", "Compile-unit inventory has unknown or missing fields.")] };
@@ -1939,7 +2058,7 @@ function validateCompileUnitInventory(value) {
1939
2058
  diagnostics.push(issue("invalid-contract", cause instanceof Error ? cause.message : "Compile-unit pipelines are invalid.", `${path2}.pipelines`));
1940
2059
  }
1941
2060
  const interfaceRef2 = object2(unit.interfaceRef);
1942
- if (!interfaceRef2 || !exactKeys(interfaceRef2, ["interfaceId", "interfaceVersion", "manifestUri", "manifestSha256", "interfaceAbiHash", "modelAbiHash"]) || !safeToken(interfaceRef2.interfaceId) || !safeToken(interfaceRef2.interfaceVersion) || typeof interfaceRef2.manifestUri !== "string" || !interfaceRef2.manifestUri.startsWith("https://") || !validSha(interfaceRef2.manifestSha256) || !validSha(interfaceRef2.interfaceAbiHash) || !validSha(interfaceRef2.modelAbiHash)) {
2061
+ if (!interfaceRef2 || !exactKeys(interfaceRef2, ["interfaceId", "interfaceVersion", "manifestUri", "manifestSha256", "interfaceAbiHash", "modelAbiHash"]) || !safeToken(interfaceRef2.interfaceId) || !immutableVersion2(interfaceRef2.interfaceVersion) || typeof interfaceRef2.manifestUri !== "string" || !interfaceRef2.manifestUri.startsWith("https://") || !validSha(interfaceRef2.manifestSha256) || !validSha(interfaceRef2.interfaceAbiHash) || !validSha(interfaceRef2.modelAbiHash)) {
1943
2062
  diagnostics.push(issue("invalid-contract", "Compile-unit interfaceRef is invalid.", `${path2}.interfaceRef`));
1944
2063
  }
1945
2064
  const fixture = object2(unit.qualificationFixture);
@@ -1950,7 +2069,7 @@ function validateCompileUnitInventory(value) {
1950
2069
  for (const fragmentId of fragmentIds) {
1951
2070
  if (!covered.has(fragmentId)) diagnostics.push(issue("uncovered-fragment", `WGSL fragment ${fragmentId} has no compile unit.`));
1952
2071
  }
1953
- return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true, value: candidate };
2072
+ return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true, value: freezeJson(candidate) };
1954
2073
  }
1955
2074
 
1956
2075
  // src/testing/qualification-bundle.ts
@@ -2042,6 +2161,18 @@ function object3(value, path2) {
2042
2161
  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${path2} must be an object.`);
2043
2162
  return value;
2044
2163
  }
2164
+ function detachedJson2(value, label) {
2165
+ try {
2166
+ return JSON.parse(canonicalizeGpuContract(value));
2167
+ } catch (cause) {
2168
+ throw new TypeError(`${label} must contain detached JSON contract data.`, { cause });
2169
+ }
2170
+ }
2171
+ function freezeJson2(value) {
2172
+ if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
2173
+ for (const child of Object.values(value)) freezeJson2(child);
2174
+ return Object.freeze(value);
2175
+ }
2045
2176
  function exact2(value, keys2, path2) {
2046
2177
  const expected = new Set(keys2);
2047
2178
  if (!Object.keys(value).every((key) => expected.has(key)) || !keys2.every((key) => key in value)) throw new TypeError(`${path2} has unknown or missing fields.`);
@@ -2050,6 +2181,16 @@ function token2(value, path2) {
2050
2181
  if (typeof value !== "string" || !TOKEN.test(value) || value.includes("..")) throw new TypeError(`${path2} must be a safe token.`);
2051
2182
  return value;
2052
2183
  }
2184
+ function immutableVersion3(value, path2) {
2185
+ try {
2186
+ return assertImmutableAssetVersion(value);
2187
+ } catch (cause) {
2188
+ throw new TypeError(
2189
+ `${path2} must be an immutable asset version: exact token required; mutable aliases, ranges, wildcards, and URLs are not allowed.`,
2190
+ { cause }
2191
+ );
2192
+ }
2193
+ }
2053
2194
  function path(value, label, extensions) {
2054
2195
  if (typeof value !== "string" || !SAFE_PATH2.test(value) || !extensions.some((extension) => value.endsWith(extension))) {
2055
2196
  throw new TypeError(`${label} must be a safe data-only bundle path (${extensions.join(", ")}).`);
@@ -2184,7 +2325,7 @@ function jsonValue(value, label, depth = 0) {
2184
2325
  }
2185
2326
  function validateQualificationFixture(value, unit) {
2186
2327
  try {
2187
- const fixture = object3(value, "fixture");
2328
+ const fixture = object3(detachedJson2(value, "fixture"), "fixture");
2188
2329
  exact2(fixture, ["contractVersion", "fixtureId", "resources", "bindGroups", "commands", "layoutProbes", "readbacks", "bounds"], "fixture");
2189
2330
  if (fixture.contractVersion !== SHADER_QUALIFICATION_FIXTURE_VERSION) throw new TypeError("Unsupported qualification fixture version.");
2190
2331
  token2(fixture.fixtureId, "fixture.fixtureId");
@@ -2520,14 +2661,14 @@ function validateQualificationFixture(value, unit) {
2520
2661
  }
2521
2662
  unique2(probeIds, "fixture.layoutProbes probe IDs");
2522
2663
  unique2(probeSources, "fixture.layoutProbes model sources");
2523
- return { ok: true, value: fixture };
2664
+ return { ok: true, value: freezeJson2(fixture) };
2524
2665
  } catch (cause) {
2525
2666
  return { ok: false, diagnostics: [{ code: "invalid-contract", severity: "error", message: cause instanceof Error ? cause.message : "Invalid qualification fixture." }] };
2526
2667
  }
2527
2668
  }
2528
2669
  function validateQualificationBundleManifest(value) {
2529
2670
  try {
2530
- const bundle = object3(value, "qualification");
2671
+ const bundle = object3(detachedJson2(value, "qualification"), "qualification");
2531
2672
  exact2(bundle, ["contractVersion", "inventory", "subject", "shaderManifestCorePath", "gpuInterfaceManifest", "modelCompatibilityFixtures", "modules", "fixtures"], "qualification");
2532
2673
  if (bundle.contractVersion !== SHADER_QUALIFICATION_BUNDLE_VERSION) throw new TypeError("Unsupported qualification bundle version.");
2533
2674
  const inventory = validateCompileUnitInventory(bundle.inventory);
@@ -2537,7 +2678,7 @@ function validateQualificationBundleManifest(value) {
2537
2678
  const candidate = object3(subject.shaderManifestCore, "qualification.subject.shaderManifestCore");
2538
2679
  exact2(candidate, ["shaderId", "version", "sha256"], "qualification.subject.shaderManifestCore");
2539
2680
  token2(candidate.shaderId, "qualification.subject.shaderManifestCore.shaderId");
2540
- token2(candidate.version, "qualification.subject.shaderManifestCore.version");
2681
+ immutableVersion3(candidate.version, "qualification.subject.shaderManifestCore.version");
2541
2682
  sha(candidate.sha256, "qualification.subject.shaderManifestCore.sha256");
2542
2683
  path(bundle.shaderManifestCorePath, "qualification.shaderManifestCorePath", [".json"]);
2543
2684
  const interfaceManifest = object3(bundle.gpuInterfaceManifest, "qualification.gpuInterfaceManifest");
@@ -2597,7 +2738,7 @@ function validateQualificationBundleManifest(value) {
2597
2738
  const expectedUnits = [...inventory.value.compileUnits.map((unit) => unit.compileUnitId)].sort();
2598
2739
  if (unitIds.join("\n") !== expectedUnits.join("\n")) throw new TypeError("Subject compile-unit IDs differ from inventory.");
2599
2740
  orderedUniqueTokens(subject.requiredCellIds, "qualification.subject.requiredCellIds");
2600
- return { ok: true, value: bundle };
2741
+ return { ok: true, value: freezeJson2(bundle) };
2601
2742
  } catch (cause) {
2602
2743
  return { ok: false, diagnostics: [{ code: "invalid-contract", severity: "error", message: cause instanceof Error ? cause.message : "Invalid qualification bundle." }] };
2603
2744
  }
@@ -8726,7 +8867,7 @@ function validatePipelineInterfaces(input) {
8726
8867
  // package.json
8727
8868
  var package_default = {
8728
8869
  name: "@plasius/gpu-shader",
8729
- version: "0.1.1",
8870
+ version: "0.1.2",
8730
8871
  description: "Reflection-first WebGPU WGSL interfaces, CPU codecs, compatibility validation, style profiles, and qualification tooling",
8731
8872
  type: "module",
8732
8873
  sideEffects: false,
@@ -11977,11 +12118,21 @@ function verifyReflectedLayoutProbeOutputs(input) {
11977
12118
 
11978
12119
  // src/compatibility.ts
11979
12120
  function error(code, message, path2) {
11980
- return { code, severity: "error", message, ...path2 ? { path: path2 } : {} };
12121
+ const bounded = [...message].map((character) => {
12122
+ const codePoint = character.codePointAt(0);
12123
+ return codePoint <= 31 || codePoint === 127 ? " " : character;
12124
+ }).slice(0, 512).join("");
12125
+ return { code, severity: "error", message: bounded, ...path2 ? { path: path2 } : {} };
11981
12126
  }
11982
12127
  function interfaceMatches(item, model) {
11983
12128
  return item.interfaceId === model.gpuInterface.interfaceId && item.interfaceVersion === model.gpuInterface.interfaceVersion && item.manifestSha256 === model.gpuInterface.manifestSha256 && item.interfaceAbiHash === model.gpuInterface.interfaceAbiHash && item.modelAbiHash === model.modelAbiHash;
11984
12129
  }
12130
+ function detachedContract(value) {
12131
+ return JSON.parse(canonicalizeGpuContract(value));
12132
+ }
12133
+ function hasValidationEvidence(value) {
12134
+ return typeof value === "object" && value !== null && !Array.isArray(value) && (Object.hasOwn(value, "validationEvidence") || Object.hasOwn(value, "additionalValidationEvidence"));
12135
+ }
11985
12136
  function validateRequirements(shader, gpuInterface, model, capabilities, diagnostics) {
11986
12137
  const semantics = new Set(model.providedSemantics);
11987
12138
  const requiredSemantics = /* @__PURE__ */ new Set([
@@ -12020,7 +12171,31 @@ function validateRequirements(shader, gpuInterface, model, capabilities, diagnos
12020
12171
  }
12021
12172
  function validateModelShaderCompatibility(input) {
12022
12173
  const diagnostics = [];
12023
- const { model, shader, gpuInterface, profile, capabilities } = input;
12174
+ let model;
12175
+ let shader;
12176
+ let gpuInterface;
12177
+ let profile;
12178
+ let capabilities;
12179
+ try {
12180
+ const modelSnapshot = detachedContract(input.model);
12181
+ const shaderSnapshot = detachedContract(input.shader);
12182
+ const gpuInterfaceSnapshot = detachedContract(input.gpuInterface);
12183
+ const profileValue = input.profile;
12184
+ const profileSnapshot = profileValue === void 0 ? void 0 : detachedContract(profileValue);
12185
+ model = parseModelGpuCompatibilityDescriptor(modelSnapshot);
12186
+ shader = hasValidationEvidence(shaderSnapshot) ? parseShaderVersionManifest(shaderSnapshot) : parseShaderVersionManifestCore(shaderSnapshot);
12187
+ gpuInterface = parseGpuInterfaceManifest(gpuInterfaceSnapshot);
12188
+ profile = profileSnapshot === void 0 ? void 0 : parseShaderStyleProfileManifest(profileSnapshot);
12189
+ capabilities = input.capabilities;
12190
+ } catch (cause) {
12191
+ return {
12192
+ ok: false,
12193
+ diagnostics: [error(
12194
+ "invalid-contract",
12195
+ cause instanceof Error ? cause.message : "GPU compatibility contract snapshot failed."
12196
+ )]
12197
+ };
12198
+ }
12024
12199
  try {
12025
12200
  validateShaderInterfaceRequirements({ manifest: shader, gpuInterface });
12026
12201
  } catch (cause) {
@@ -12050,7 +12225,15 @@ function validateModelShaderCompatibility(input) {
12050
12225
  }
12051
12226
  }
12052
12227
  }
12053
- validateRequirements(shader, gpuInterface, model, capabilities, diagnostics);
12228
+ try {
12229
+ validateRequirements(shader, gpuInterface, model, capabilities, diagnostics);
12230
+ } catch (cause) {
12231
+ diagnostics.push(error(
12232
+ "invalid-contract",
12233
+ cause instanceof Error ? cause.message : "GPU capability snapshot validation failed.",
12234
+ "capabilities"
12235
+ ));
12236
+ }
12054
12237
  if (diagnostics.length > 0) return { ok: false, diagnostics };
12055
12238
  return {
12056
12239
  ok: true,