@plasius/gpu-shader 0.1.0

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.
@@ -0,0 +1,1220 @@
1
+ /** Contract version shared by the first reflection-first manifest family. */
2
+ declare const GPU_INTERFACE_MANIFEST_VERSION: "1.0.0";
3
+ declare const SHADER_VERSION_MANIFEST_VERSION: "1.0.0";
4
+ declare const SHADER_STYLE_PROFILE_MANIFEST_VERSION: "1.0.0";
5
+ declare const SHADER_COMPILE_UNIT_VERSION: "1.0.0";
6
+ declare const SHADER_VALIDATION_EVIDENCE_VERSION: "1.0.0";
7
+ declare const STABLE_WEBGPU_MATRIX_VERSION: "1.0.0";
8
+ declare const SHADER_QUALIFICATION_FIXTURE_VERSION: "1.0.0";
9
+ declare const SHADER_QUALIFICATION_BUNDLE_VERSION: "1.0.0";
10
+ /** Remotely controlled rollout gate owned by the asset service. */
11
+ declare const GPU_SHADER_STORE_FEATURE_FLAG: "asset.pipeline.shader-store.enabled";
12
+ /** User-visible style discovery/selection entitlement owned by the capability service. */
13
+ declare const GPU_SHADER_STYLE_SELECTION_CAPABILITY: "gpu.shader.style.select";
14
+ /** Lowercase hexadecimal SHA-256 value. Runtime parsers enforce its shape. */
15
+ type Sha256Hex = string & {
16
+ readonly __sha256Hex: unique symbol;
17
+ };
18
+ /** Stable universal policies accepted by this contract implementation. */
19
+ declare const SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES: readonly [Readonly<{
20
+ matrixId: "stable-webgpu";
21
+ matrixVersion: "2026-07-13";
22
+ matrixSha256: "9b47ff8162b055d49e38c4fe90b9074992ab8c9e1125926e936f8122e6119fd8";
23
+ }>];
24
+ /**
25
+ * Exact additive policies accepted by this release. Empty means supplemental
26
+ * qualification fails closed until reviewed policy bytes and lanes are added.
27
+ */
28
+ declare const SUPPORTED_ADDITIVE_WEBGPU_MATRIX_POLICIES: readonly Readonly<{
29
+ scope: string;
30
+ matrixId: string;
31
+ matrixVersion: string;
32
+ matrixSha256: string;
33
+ }>[];
34
+ interface GitObjectId {
35
+ readonly algorithm: "sha1" | "sha256";
36
+ readonly hex: string;
37
+ }
38
+ type JsonPrimitive = string | number | boolean | null;
39
+ type JsonValue = JsonPrimitive | readonly JsonValue[] | {
40
+ readonly [key: string]: JsonValue;
41
+ };
42
+ type ShaderDiagnosticSeverity = "error" | "warning" | "info";
43
+ type ShaderDiagnosticCode = "invalid-contract" | "digest-mismatch" | "model-abi-mismatch" | "interface-abi-mismatch" | "shader-abi-mismatch" | "incompatible-model-interface" | "missing-semantic" | "missing-feature" | "limit-not-met" | "unsupported-format" | "unpromoted-asset" | "compilation-error" | "pipeline-error" | "device-lost" | "activation-error" | "stale-evidence" | "incomplete-matrix" | "uncovered-fragment" | "timeout" | "runner-unavailable" | "adapter-unavailable";
44
+ interface ShaderDiagnostic {
45
+ readonly code: ShaderDiagnosticCode;
46
+ readonly severity: ShaderDiagnosticSeverity;
47
+ readonly message: string;
48
+ readonly path?: string;
49
+ readonly expected?: JsonValue;
50
+ readonly actual?: JsonValue;
51
+ }
52
+ type ShaderResult<T> = {
53
+ readonly ok: true;
54
+ readonly value: T;
55
+ } | {
56
+ readonly ok: false;
57
+ readonly diagnostics: readonly ShaderDiagnostic[];
58
+ };
59
+ type GpuScalarKind = "i32" | "u32" | "f32" | "f16" | "bool";
60
+ type GpuHostAddressSpace = "uniform" | "storage";
61
+ type GpuAddressSpace = GpuHostAddressSpace | "function" | "private" | "workgroup";
62
+ interface GpuScalarLayout {
63
+ readonly kind: "scalar";
64
+ readonly scalar: GpuScalarKind;
65
+ readonly alignment: number;
66
+ readonly byteSize: number;
67
+ }
68
+ interface GpuAtomicLayout {
69
+ readonly kind: "atomic";
70
+ readonly scalar: "i32" | "u32";
71
+ readonly alignment: number;
72
+ readonly byteSize: number;
73
+ }
74
+ interface GpuVectorLayout {
75
+ readonly kind: "vector";
76
+ readonly scalar: GpuScalarKind;
77
+ readonly width: 2 | 3 | 4;
78
+ readonly alignment: number;
79
+ readonly byteSize: number;
80
+ }
81
+ interface GpuMatrixLayout {
82
+ readonly kind: "matrix";
83
+ readonly scalar: "f32" | "f16";
84
+ readonly columns: 2 | 3 | 4;
85
+ readonly rows: 2 | 3 | 4;
86
+ readonly columnStride: number;
87
+ readonly alignment: number;
88
+ readonly byteSize: number;
89
+ }
90
+ interface GpuArrayLayout {
91
+ readonly kind: "array";
92
+ readonly element: GpuTypeLayout;
93
+ /** Null represents a WGSL runtime-sized array. */
94
+ readonly count: number | null;
95
+ readonly stride: number;
96
+ readonly alignment: number;
97
+ readonly byteSize: number | null;
98
+ }
99
+ interface GpuRecordReferenceLayout {
100
+ readonly kind: "record";
101
+ readonly recordName: string;
102
+ readonly alignment: number;
103
+ readonly byteSize: number | null;
104
+ }
105
+ type GpuTypeLayout = GpuScalarLayout | GpuAtomicLayout | GpuVectorLayout | GpuMatrixLayout | GpuArrayLayout | GpuRecordReferenceLayout;
106
+ interface GpuRecordMemberLayout {
107
+ readonly name: string;
108
+ readonly offset: number;
109
+ /** Effective alignment after applying an optional WGSL `@align`. */
110
+ readonly alignment: number;
111
+ /** Logical size of the value, excluding a member-level `@size`. */
112
+ readonly valueByteSize: number | null;
113
+ /** Occupied member span, including a member-level `@size`. */
114
+ readonly occupiedByteSize: number | null;
115
+ readonly explicitAlign: number | null;
116
+ readonly explicitSize: number | null;
117
+ readonly type: GpuTypeLayout;
118
+ }
119
+ interface GpuRecordLayout {
120
+ readonly name: string;
121
+ readonly alignment: number;
122
+ /** Null for records ending in a runtime-sized array. */
123
+ readonly byteSize: number | null;
124
+ /** Fixed prefix before any runtime-sized array. */
125
+ readonly minimumByteSize: number;
126
+ readonly runtimeArrayMember: string | null;
127
+ readonly addressSpaces: readonly GpuAddressSpace[];
128
+ /** WGSL declaration order; constructor and codec order depend on it. */
129
+ readonly members: readonly GpuRecordMemberLayout[];
130
+ }
131
+ type GpuShaderStage = "vertex" | "fragment" | "compute";
132
+ type GpuBindingAccess = "read" | "write" | "read_write";
133
+ type GpuBindingResourceLayout = {
134
+ readonly kind: "buffer";
135
+ readonly addressSpace: GpuHostAddressSpace;
136
+ readonly access: GpuBindingAccess;
137
+ readonly recordName: string | null;
138
+ readonly minimumBindingSize: number;
139
+ } | {
140
+ readonly kind: "sampler";
141
+ readonly samplerType: "filtering" | "non-filtering" | "comparison";
142
+ } | {
143
+ readonly kind: "texture";
144
+ readonly sampleType: "float" | "unfilterable-float" | "depth" | "sint" | "uint";
145
+ readonly viewDimension: "1d" | "2d" | "2d-array" | "cube" | "cube-array" | "3d";
146
+ readonly multisampled: boolean;
147
+ } | {
148
+ readonly kind: "storage-texture";
149
+ readonly access: "write-only" | "read-only" | "read-write";
150
+ readonly format: string;
151
+ readonly viewDimension: "1d" | "2d" | "2d-array" | "3d";
152
+ } | {
153
+ readonly kind: "external-texture";
154
+ };
155
+ interface GpuBindingLayout {
156
+ readonly moduleId: string;
157
+ readonly variableName: string;
158
+ readonly group: number;
159
+ readonly binding: number;
160
+ readonly resource: GpuBindingResourceLayout;
161
+ readonly visibility: readonly GpuShaderStage[];
162
+ }
163
+ interface GpuEntryPointIo {
164
+ readonly name: string;
165
+ readonly locationKind: "location" | "builtin";
166
+ readonly location: number | string;
167
+ readonly interpolation: string | null;
168
+ readonly type: GpuTypeLayout;
169
+ }
170
+ type GpuWorkgroupDimension = {
171
+ readonly kind: "literal";
172
+ readonly value: number;
173
+ } | {
174
+ readonly kind: "override";
175
+ readonly name: string;
176
+ };
177
+ interface GpuEntryPointInterface {
178
+ readonly moduleId: string;
179
+ readonly name: string;
180
+ readonly stage: GpuShaderStage;
181
+ readonly inputs: readonly GpuEntryPointIo[];
182
+ readonly outputs: readonly GpuEntryPointIo[];
183
+ readonly bindingKeys: readonly string[];
184
+ readonly overrideNames: readonly string[];
185
+ readonly workgroupSize: readonly [
186
+ GpuWorkgroupDimension,
187
+ GpuWorkgroupDimension,
188
+ GpuWorkgroupDimension
189
+ ] | null;
190
+ /**
191
+ * WebGPU workgroup-storage bytes statically used by a compute entry point.
192
+ * This is null for non-compute entry points.
193
+ */
194
+ readonly workgroupStorageSize: number | null;
195
+ }
196
+ interface GpuVertexInputLayout {
197
+ readonly pipelineId: string;
198
+ readonly moduleId: string;
199
+ readonly entryPoint: string;
200
+ readonly shaderLocation: number;
201
+ readonly shaderType: GpuTypeLayout;
202
+ readonly bufferSlot: number;
203
+ readonly format: string;
204
+ readonly offset: number;
205
+ readonly arrayStride: number;
206
+ readonly stepMode: "vertex" | "instance";
207
+ readonly semantic: string | null;
208
+ }
209
+ /** Shader-independent vertex bytes consumed from a model buffer. */
210
+ interface GpuModelVertexInputLayout {
211
+ readonly source: {
212
+ readonly pipelineId: string;
213
+ readonly shaderLocation: number;
214
+ };
215
+ readonly format: string;
216
+ readonly offset: number;
217
+ readonly arrayStride: number;
218
+ readonly stepMode: "vertex" | "instance";
219
+ readonly semantic: string;
220
+ }
221
+ /** A reflected model-facing resource projection; shader coordinates and visibility are excluded. */
222
+ interface GpuModelBindingLayout {
223
+ readonly source: {
224
+ readonly moduleId: string;
225
+ readonly group: number;
226
+ readonly binding: number;
227
+ };
228
+ readonly resource: GpuBindingResourceLayout;
229
+ readonly semantic: string | null;
230
+ }
231
+ interface GpuOverrideLayout {
232
+ readonly moduleId: string;
233
+ readonly name: string;
234
+ readonly id: number | null;
235
+ readonly type: "bool" | "i32" | "u32" | "f32" | "f16";
236
+ readonly defaultValue: boolean | number | null;
237
+ }
238
+ type GpuSemanticSource = {
239
+ readonly kind: "record-member";
240
+ readonly recordName: string;
241
+ readonly memberPath: readonly string[];
242
+ } | {
243
+ readonly kind: "vertex-attribute";
244
+ readonly pipelineId: string;
245
+ readonly shaderLocation: number;
246
+ } | {
247
+ readonly kind: "binding";
248
+ readonly moduleId: string;
249
+ readonly group: number;
250
+ readonly binding: number;
251
+ };
252
+ interface GpuSemanticProjection {
253
+ readonly semantic: string;
254
+ readonly source: GpuSemanticSource;
255
+ }
256
+ interface GpuModelAbiProjection {
257
+ readonly recordNames: readonly string[];
258
+ readonly bindings: readonly GpuModelBindingLayout[];
259
+ readonly vertexInputs: readonly GpuModelVertexInputLayout[];
260
+ readonly semantics: readonly GpuSemanticProjection[];
261
+ }
262
+ interface GpuInterfaceManifest {
263
+ readonly contractVersion: typeof GPU_INTERFACE_MANIFEST_VERSION;
264
+ readonly interfaceId: string;
265
+ readonly interfaceVersion: string;
266
+ readonly modules: readonly {
267
+ readonly moduleId: string;
268
+ readonly sha256: Sha256Hex;
269
+ }[];
270
+ readonly records: readonly GpuRecordLayout[];
271
+ readonly bindings: readonly GpuBindingLayout[];
272
+ readonly entryPoints: readonly GpuEntryPointInterface[];
273
+ readonly vertexInputs: readonly GpuVertexInputLayout[];
274
+ readonly overrides: readonly GpuOverrideLayout[];
275
+ readonly modelAbi: GpuModelAbiProjection;
276
+ readonly modelAbiHash: Sha256Hex;
277
+ readonly interfaceAbiHash: Sha256Hex;
278
+ readonly generatedBy: {
279
+ readonly packageVersion: string;
280
+ readonly reflector: "wgsl_reflect";
281
+ readonly reflectorVersion: "1.5.0";
282
+ };
283
+ }
284
+ interface GpuInterfaceRef {
285
+ readonly interfaceId: string;
286
+ readonly interfaceVersion: string;
287
+ readonly manifestUri: string;
288
+ readonly manifestSha256: Sha256Hex;
289
+ readonly interfaceAbiHash: Sha256Hex;
290
+ readonly modelAbiHash: Sha256Hex;
291
+ }
292
+ interface ShaderVersionRef {
293
+ readonly shaderId: string;
294
+ readonly version: string;
295
+ readonly manifestUri: string;
296
+ readonly manifestSha256: Sha256Hex;
297
+ }
298
+ interface ShaderStyleProfileRef {
299
+ readonly profileId: string;
300
+ readonly version: string;
301
+ readonly manifestUri: string;
302
+ readonly manifestSha256: Sha256Hex;
303
+ }
304
+ interface SerializableGpuProgrammableStage {
305
+ readonly moduleId: string;
306
+ readonly entryPoint: string;
307
+ readonly constants: Readonly<Record<string, boolean | number>>;
308
+ }
309
+ interface SerializableGpuBindGroupLayout {
310
+ readonly group: number;
311
+ readonly entries: readonly Omit<GpuBindingLayout, "moduleId" | "variableName">[];
312
+ }
313
+ interface SerializableGpuPipelineLayout {
314
+ readonly bindGroups: readonly SerializableGpuBindGroupLayout[];
315
+ }
316
+ interface SerializableGpuComputePipelineDescriptor {
317
+ readonly kind: "compute";
318
+ readonly pipelineId: string;
319
+ readonly layout: SerializableGpuPipelineLayout;
320
+ readonly compute: SerializableGpuProgrammableStage;
321
+ }
322
+ interface SerializableGpuRenderPipelineDescriptor {
323
+ readonly kind: "render";
324
+ readonly pipelineId: string;
325
+ readonly layout: SerializableGpuPipelineLayout;
326
+ readonly vertex: SerializableGpuProgrammableStage;
327
+ readonly fragment: SerializableGpuProgrammableStage | null;
328
+ readonly vertexBuffers: readonly {
329
+ readonly arrayStride: number;
330
+ readonly stepMode: "vertex" | "instance";
331
+ readonly attributes: readonly {
332
+ readonly format: string;
333
+ readonly offset: number;
334
+ readonly shaderLocation: number;
335
+ readonly semantic: string | null;
336
+ }[];
337
+ }[];
338
+ readonly primitive: {
339
+ readonly topology: "point-list" | "line-list" | "line-strip" | "triangle-list" | "triangle-strip";
340
+ readonly stripIndexFormat: "uint16" | "uint32" | null;
341
+ readonly frontFace: "ccw" | "cw";
342
+ readonly cullMode: "none" | "front" | "back";
343
+ readonly unclippedDepth: boolean;
344
+ };
345
+ readonly colorTargets: readonly {
346
+ readonly format: string;
347
+ readonly blend: {
348
+ readonly color: SerializableGpuBlendComponent;
349
+ readonly alpha: SerializableGpuBlendComponent;
350
+ } | null;
351
+ readonly writeMask: number;
352
+ }[];
353
+ readonly depthStencil: {
354
+ readonly format: string;
355
+ readonly depthWriteEnabled: boolean;
356
+ readonly depthCompare: GpuCompareFunction;
357
+ readonly stencilFront: SerializableGpuStencilFaceState;
358
+ readonly stencilBack: SerializableGpuStencilFaceState;
359
+ readonly stencilReadMask: number;
360
+ readonly stencilWriteMask: number;
361
+ readonly depthBias: number;
362
+ readonly depthBiasSlopeScale: number;
363
+ readonly depthBiasClamp: number;
364
+ } | null;
365
+ readonly multisample: {
366
+ readonly count: 1 | 4;
367
+ readonly mask: number;
368
+ readonly alphaToCoverageEnabled: boolean;
369
+ };
370
+ }
371
+ type GpuCompareFunction = "never" | "less" | "equal" | "less-equal" | "greater" | "not-equal" | "greater-equal" | "always";
372
+ interface SerializableGpuBlendComponent {
373
+ readonly operation: "add" | "subtract" | "reverse-subtract" | "min" | "max";
374
+ readonly srcFactor: "zero" | "one" | "src" | "one-minus-src" | "src-alpha" | "one-minus-src-alpha" | "dst" | "one-minus-dst" | "dst-alpha" | "one-minus-dst-alpha" | "src-alpha-saturated" | "constant" | "one-minus-constant";
375
+ readonly dstFactor: "zero" | "one" | "src" | "one-minus-src" | "src-alpha" | "one-minus-src-alpha" | "dst" | "one-minus-dst" | "dst-alpha" | "one-minus-dst-alpha" | "src-alpha-saturated" | "constant" | "one-minus-constant";
376
+ }
377
+ interface SerializableGpuStencilFaceState {
378
+ readonly compare: GpuCompareFunction;
379
+ readonly failOp: "keep" | "zero" | "replace" | "invert" | "increment-clamp" | "decrement-clamp" | "increment-wrap" | "decrement-wrap";
380
+ readonly depthFailOp: "keep" | "zero" | "replace" | "invert" | "increment-clamp" | "decrement-clamp" | "increment-wrap" | "decrement-wrap";
381
+ readonly passOp: "keep" | "zero" | "replace" | "invert" | "increment-clamp" | "decrement-clamp" | "increment-wrap" | "decrement-wrap";
382
+ }
383
+ type SerializableGpuPipelineDescriptor = SerializableGpuComputePipelineDescriptor | SerializableGpuRenderPipelineDescriptor;
384
+ interface GpuLimitRequirement {
385
+ readonly name: string;
386
+ readonly comparator: "at-least" | "at-most";
387
+ readonly value: number;
388
+ }
389
+ interface ShaderRequirements {
390
+ readonly semantics: readonly string[];
391
+ readonly features: readonly string[];
392
+ readonly limits: readonly GpuLimitRequirement[];
393
+ readonly formats: readonly string[];
394
+ }
395
+ type ShaderRenderRole = "material" | "lighting" | "outline" | "shadow" | "post-processing";
396
+ interface ShaderValidationEvidenceRef {
397
+ readonly evidenceId: string;
398
+ readonly uri: string;
399
+ readonly sha256: Sha256Hex;
400
+ readonly matrixId: string;
401
+ readonly matrixVersion: string;
402
+ /** Digest of the exact versioned matrix-policy bytes used to produce the evidence. */
403
+ readonly matrixSha256: Sha256Hex;
404
+ /** Exact external GitHub build-provenance reference artifact for the evidence bytes. */
405
+ readonly attestationRef: {
406
+ readonly uri: string;
407
+ readonly sha256: Sha256Hex;
408
+ };
409
+ }
410
+ /** Additional qualification required beyond the stable universal matrix. */
411
+ interface ScopedShaderValidationEvidenceRef {
412
+ /** Stable, profile-selectable scope such as `xr`; `universal` is reserved. */
413
+ readonly scope: string;
414
+ readonly evidence: ShaderValidationEvidenceRef;
415
+ }
416
+ /** Exact supplemental matrix policy a style profile requires for every role. */
417
+ interface ShaderValidationScopeRequirement {
418
+ /** Stable policy scope such as `xr`; `universal` is reserved. */
419
+ readonly scope: string;
420
+ readonly matrixId: string;
421
+ readonly matrixVersion: string;
422
+ readonly matrixSha256: Sha256Hex;
423
+ }
424
+ interface ShaderVersionManifest {
425
+ readonly contractVersion: typeof SHADER_VERSION_MANIFEST_VERSION;
426
+ readonly shaderId: string;
427
+ readonly version: string;
428
+ readonly modules: readonly {
429
+ readonly moduleId: string;
430
+ readonly uri: string;
431
+ readonly byteLength: number;
432
+ readonly sha256: Sha256Hex;
433
+ readonly contentType: "text/wgsl; charset=utf-8";
434
+ }[];
435
+ readonly gpuInterface: GpuInterfaceRef;
436
+ readonly pipelines: readonly SerializableGpuPipelineDescriptor[];
437
+ readonly renderRoles: readonly {
438
+ readonly role: ShaderRenderRole;
439
+ readonly pipelineIds: readonly string[];
440
+ }[];
441
+ readonly compatibleModelInterfaces: readonly {
442
+ readonly interfaceId: string;
443
+ readonly interfaceVersion: string;
444
+ readonly manifestSha256: Sha256Hex;
445
+ readonly interfaceAbiHash: Sha256Hex;
446
+ readonly modelAbiHash: Sha256Hex;
447
+ }[];
448
+ readonly requirements: ShaderRequirements;
449
+ readonly shaderAbiHash: Sha256Hex;
450
+ /** Passing evidence for the universal stable-WebGPU matrix. */
451
+ readonly validationEvidence: ShaderValidationEvidenceRef;
452
+ /** Passing evidence for additive matrices, for example XR device lanes. */
453
+ readonly additionalValidationEvidence: readonly ScopedShaderValidationEvidenceRef[];
454
+ }
455
+ /** Immutable shader manifest fields qualified before external evidence is attached. */
456
+ type ShaderVersionManifestCore = Omit<ShaderVersionManifest, "validationEvidence" | "additionalValidationEvidence">;
457
+ interface ShaderStyleRoleBinding {
458
+ readonly role: ShaderRenderRole;
459
+ readonly shader: ShaderVersionRef;
460
+ }
461
+ interface ShaderStyleProfileManifest {
462
+ readonly contractVersion: typeof SHADER_STYLE_PROFILE_MANIFEST_VERSION;
463
+ readonly profileId: string;
464
+ readonly version: string;
465
+ readonly style: string;
466
+ readonly roles: readonly ShaderStyleRoleBinding[];
467
+ readonly compatibleModelInterfaces: readonly {
468
+ readonly interfaceId: string;
469
+ readonly interfaceVersion: string;
470
+ readonly manifestSha256: Sha256Hex;
471
+ readonly interfaceAbiHash: Sha256Hex;
472
+ readonly modelAbiHash: Sha256Hex;
473
+ }[];
474
+ readonly requiredSemantics: readonly string[];
475
+ /** Exact supplemental matrix policies every referenced shader must provide. */
476
+ readonly requiredValidationScopes: readonly ShaderValidationScopeRequirement[];
477
+ }
478
+ interface ModelGpuCompatibilityDescriptor {
479
+ readonly modelId: string;
480
+ readonly version: string;
481
+ readonly gpuInterface: GpuInterfaceRef;
482
+ readonly modelAbiHash: Sha256Hex;
483
+ readonly providedSemantics: readonly string[];
484
+ readonly defaultStyleProfile: ShaderStyleProfileRef | null;
485
+ }
486
+ interface GpuCapabilitySnapshot {
487
+ readonly features: readonly string[];
488
+ readonly limits: Readonly<Record<string, number>>;
489
+ readonly formats: readonly string[];
490
+ }
491
+ interface ModelShaderCompatibility {
492
+ readonly modelAbiHash: Sha256Hex;
493
+ readonly shaderAbiHash: Sha256Hex;
494
+ readonly matchedInterfaceId: string;
495
+ }
496
+ type GpuScalarValue = number;
497
+ type GpuVectorValue = readonly number[];
498
+ type GpuMatrixValue = readonly (readonly number[])[];
499
+ type GpuRecordValue = Readonly<Record<string, unknown>>;
500
+ interface GpuRecordCodec<T = GpuRecordValue> {
501
+ readonly record: GpuRecordLayout;
502
+ readonly minimumByteLength: number;
503
+ byteLength(value: T): number;
504
+ encode(value: T): ArrayBuffer;
505
+ encodeInto(value: T, destination: ArrayBuffer | ArrayBufferView, byteOffset?: number): number;
506
+ decode(source: ArrayBuffer | ArrayBufferView, options?: {
507
+ readonly byteOffset?: number;
508
+ readonly byteLength?: number;
509
+ }): T;
510
+ }
511
+ interface PromotedShaderCatalogResolver {
512
+ /** Must prove the URI belongs to the configured promoted catalog root and exact immutable identity. */
513
+ isCatalogAssetUri(uri: string): boolean;
514
+ loadProfile(ref: ShaderStyleProfileRef, signal?: AbortSignal): Promise<{
515
+ readonly bytes: Uint8Array;
516
+ readonly promoted: boolean;
517
+ }>;
518
+ loadShader(ref: ShaderVersionRef, signal?: AbortSignal): Promise<{
519
+ readonly bytes: Uint8Array;
520
+ readonly promoted: boolean;
521
+ }>;
522
+ loadInterface(ref: GpuInterfaceRef, signal?: AbortSignal): Promise<{
523
+ readonly bytes: Uint8Array;
524
+ readonly promoted: boolean;
525
+ }>;
526
+ loadModule(shader: ShaderVersionRef, moduleId: string, uri: string, signal?: AbortSignal): Promise<{
527
+ readonly bytes: Uint8Array;
528
+ readonly promoted: boolean;
529
+ }>;
530
+ }
531
+ interface LoadedShaderVersion {
532
+ readonly ref: ShaderVersionRef;
533
+ readonly manifest: ShaderVersionManifest;
534
+ readonly gpuInterface: GpuInterfaceManifest;
535
+ readonly modules: ReadonlyMap<string, Uint8Array>;
536
+ }
537
+ interface LoadedShaderStyleProfile {
538
+ readonly ref: ShaderStyleProfileRef;
539
+ readonly manifest: ShaderStyleProfileManifest;
540
+ readonly shaders: ReadonlyMap<ShaderRenderRole, LoadedShaderVersion>;
541
+ }
542
+ interface GpuCompilationMessageLike {
543
+ readonly type: "error" | "warning" | "info";
544
+ readonly message: string;
545
+ readonly lineNum?: number;
546
+ readonly linePos?: number;
547
+ }
548
+ interface GpuShaderModuleLike {
549
+ getCompilationInfo(): Promise<{
550
+ readonly messages: readonly GpuCompilationMessageLike[];
551
+ }>;
552
+ }
553
+ interface GpuDeviceLike {
554
+ readonly features: Iterable<string>;
555
+ readonly limits: Readonly<Record<string, number>>;
556
+ readonly lost?: Promise<{
557
+ readonly reason?: string;
558
+ readonly message?: string;
559
+ }>;
560
+ createShaderModule(descriptor: {
561
+ readonly label?: string;
562
+ readonly code: string;
563
+ }): GpuShaderModuleLike;
564
+ createBindGroupLayout(descriptor: unknown): unknown;
565
+ createPipelineLayout(descriptor: {
566
+ readonly bindGroupLayouts: readonly unknown[];
567
+ }): unknown;
568
+ createComputePipelineAsync?(descriptor: unknown): Promise<unknown>;
569
+ createRenderPipelineAsync?(descriptor: unknown): Promise<unknown>;
570
+ createComputePipeline?(descriptor: unknown): unknown;
571
+ createRenderPipeline?(descriptor: unknown): unknown;
572
+ pushErrorScope?(filter: "validation"): void;
573
+ popErrorScope?(): Promise<{
574
+ readonly message?: string;
575
+ } | null>;
576
+ }
577
+ interface PreparedShaderStyleProfile {
578
+ readonly loaded: LoadedShaderStyleProfile;
579
+ readonly pipelines: ReadonlyMap<string, unknown>;
580
+ readonly preparedAt: number;
581
+ dispose(): void;
582
+ }
583
+ interface ActiveShaderStyleProfile {
584
+ readonly prepared: PreparedShaderStyleProfile;
585
+ readonly activatedAt: number;
586
+ }
587
+ interface FrameBoundaryScheduler {
588
+ schedule(operation: () => void): Promise<void>;
589
+ }
590
+ interface ShaderStyleController {
591
+ readonly current: ActiveShaderStyleProfile | null;
592
+ }
593
+ interface AssembledWgslModule {
594
+ readonly moduleId: string;
595
+ readonly source: string;
596
+ }
597
+ type GpuSemanticSelector = GpuSemanticProjection;
598
+ /** Selects a reflected binding. Callers cannot supply its resource layout. */
599
+ interface GpuModelBindingSelector {
600
+ readonly moduleId: string;
601
+ readonly group: number;
602
+ readonly binding: number;
603
+ readonly semantic?: string | null;
604
+ }
605
+ interface ReflectGpuInterfaceInput {
606
+ readonly interfaceId: string;
607
+ readonly interfaceVersion: string;
608
+ readonly modules: readonly AssembledWgslModule[];
609
+ readonly pipelines: readonly SerializableGpuPipelineDescriptor[];
610
+ readonly modelFacingRecordNames: readonly string[];
611
+ readonly modelFacingBindings: readonly GpuModelBindingSelector[];
612
+ readonly semantics: readonly GpuSemanticSelector[];
613
+ }
614
+ interface GeneratedGpuInterfaceArtifacts {
615
+ readonly manifestJson: string;
616
+ readonly jsonSchemas: string;
617
+ readonly typescriptTypes: string;
618
+ readonly byteConstants: string;
619
+ readonly codecs: string;
620
+ }
621
+ interface ShaderCompileUnitManifest {
622
+ readonly contractVersion: typeof SHADER_COMPILE_UNIT_VERSION;
623
+ readonly compileUnitId: string;
624
+ readonly fragmentIds: readonly string[];
625
+ readonly modules: readonly {
626
+ readonly moduleId: string;
627
+ readonly sha256: Sha256Hex;
628
+ readonly assembly: {
629
+ /** UTF-8 fragment bytes joined by one LF byte, with no executable transforms. */
630
+ readonly kind: "concat-v1";
631
+ readonly fragmentIds: readonly string[];
632
+ };
633
+ }[];
634
+ readonly entryPoints: readonly {
635
+ readonly moduleId: string;
636
+ readonly name: string;
637
+ readonly stage: GpuShaderStage;
638
+ }[];
639
+ readonly pipelines: readonly SerializableGpuPipelineDescriptor[];
640
+ readonly interfaceRef: GpuInterfaceRef;
641
+ readonly overrideValues: Readonly<Record<string, boolean | number>>;
642
+ readonly qualificationFixture: {
643
+ readonly fixtureId: string;
644
+ readonly path: string;
645
+ readonly sha256: Sha256Hex;
646
+ };
647
+ }
648
+ interface ShaderCompileUnitInventory {
649
+ readonly contractVersion: typeof SHADER_COMPILE_UNIT_VERSION;
650
+ readonly fragments: readonly {
651
+ readonly fragmentId: string;
652
+ readonly path: string;
653
+ readonly sha256: Sha256Hex;
654
+ }[];
655
+ readonly compileUnits: readonly ShaderCompileUnitManifest[];
656
+ }
657
+ type ShaderMatrixBrowserName = "chromium" | "chrome" | "edge" | "firefox" | "safari";
658
+ type ShaderMatrixOsName = "ubuntu" | "windows" | "macos" | "chromeos" | "android" | "ios" | "ipados" | "visionos";
659
+ interface StableWebGpuMatrixCell {
660
+ readonly cellId: string;
661
+ readonly runnerLabels: readonly string[];
662
+ readonly browser: {
663
+ readonly name: ShaderMatrixBrowserName;
664
+ readonly channel: "stable" | "playwright-bundled";
665
+ };
666
+ readonly os: {
667
+ readonly name: ShaderMatrixOsName;
668
+ readonly versionRequirement: {
669
+ readonly kind: "exact";
670
+ readonly value: string;
671
+ } | {
672
+ readonly kind: "major";
673
+ readonly value: number;
674
+ } | {
675
+ readonly kind: "minimum-major";
676
+ readonly value: number;
677
+ } | {
678
+ readonly kind: "stable-channel";
679
+ readonly channel: "stable";
680
+ };
681
+ readonly architecture: "x64" | "arm64";
682
+ };
683
+ readonly adapter: {
684
+ readonly kind: "software" | "physical";
685
+ readonly vendor: string;
686
+ readonly family: string;
687
+ readonly backend: "swiftshader" | "d3d12" | "metal" | "vulkan";
688
+ };
689
+ readonly automation: {
690
+ readonly kind: "playwright" | "webdriver" | "device-farm" | "safari-webdriver";
691
+ };
692
+ readonly timeoutMs: number;
693
+ readonly blocking: boolean;
694
+ readonly countsTowardStableCoverage: boolean;
695
+ }
696
+ interface StableWebGpuMatrixManifest {
697
+ readonly contractVersion: typeof STABLE_WEBGPU_MATRIX_VERSION;
698
+ readonly matrixId: string;
699
+ readonly version: string;
700
+ readonly policy: {
701
+ readonly coverage: "all-cells-required";
702
+ readonly unavailable: "fail";
703
+ readonly skipped: "fail";
704
+ readonly timeout: "fail";
705
+ readonly deviceLoss: "fail";
706
+ readonly requiredPhysicalCellCount: 15;
707
+ readonly requiredBlockingCellCount: 16;
708
+ };
709
+ readonly cells: readonly StableWebGpuMatrixCell[];
710
+ }
711
+ type ShaderQualificationStatus = "passed" | "failed" | "skipped" | "timeout" | "device-lost" | "runner-unavailable" | "adapter-unavailable";
712
+ type ShaderQualificationPhaseName = "assembly" | "reflection-schema" | "shader-compilation" | "pipeline-layout" | "pipeline-creation" | "bind-group-creation" | "cpu-to-gpu-layout" | "gpu-to-cpu-layout" | "bounded-execution" | "semantic-readback";
713
+ type ShaderQualificationPhaseEvidence = {
714
+ readonly name: Exclude<ShaderQualificationPhaseName, "shader-compilation" | "semantic-readback">;
715
+ readonly status: "passed" | "failed";
716
+ readonly durationMs: number;
717
+ readonly evidenceSha256: Sha256Hex;
718
+ } | {
719
+ readonly name: "shader-compilation";
720
+ readonly status: "passed" | "failed";
721
+ readonly durationMs: number;
722
+ readonly compilationMessagesSha256: Sha256Hex;
723
+ readonly errorCount: number;
724
+ } | {
725
+ readonly name: "semantic-readback";
726
+ readonly status: "passed" | "failed";
727
+ readonly durationMs: number;
728
+ readonly expectedSha256: Sha256Hex;
729
+ readonly actualSha256: Sha256Hex;
730
+ };
731
+ interface ShaderQualificationResult {
732
+ readonly compileUnitId: string;
733
+ readonly cellId: string;
734
+ readonly status: ShaderQualificationStatus;
735
+ readonly startedAt: string;
736
+ readonly completedAt: string;
737
+ readonly observed: {
738
+ readonly runner: {
739
+ readonly id: string;
740
+ readonly labels: readonly string[];
741
+ };
742
+ readonly os: {
743
+ readonly name: string;
744
+ readonly version: string;
745
+ readonly channel: string | null;
746
+ readonly architecture: string;
747
+ };
748
+ readonly browser: {
749
+ readonly name: string;
750
+ readonly version: string;
751
+ readonly channel: string;
752
+ };
753
+ readonly adapter: {
754
+ readonly physical: boolean;
755
+ readonly vendor: string;
756
+ readonly family: string;
757
+ readonly architecture: string;
758
+ readonly device: string;
759
+ readonly description: string;
760
+ readonly backend: string;
761
+ readonly driver: string;
762
+ };
763
+ readonly features: readonly string[];
764
+ readonly limits: Readonly<Record<string, number>>;
765
+ };
766
+ readonly phases: readonly ShaderQualificationPhaseEvidence[];
767
+ readonly diagnostics: readonly ShaderDiagnostic[];
768
+ }
769
+ /** Candidate claims that can be serialized inside the candidate archive without a self-digest. */
770
+ interface ShaderQualificationCandidateSubject {
771
+ /** Digest of the ShaderVersionManifest projection with validationEvidence omitted. */
772
+ readonly shaderManifestCore: {
773
+ readonly shaderId: string;
774
+ readonly version: string;
775
+ readonly sha256: Sha256Hex;
776
+ };
777
+ readonly compileUnitInventorySha256: Sha256Hex;
778
+ readonly shaderAbiHash: Sha256Hex;
779
+ readonly interfaceManifestSha256: Sha256Hex;
780
+ readonly modelAbiHashes: readonly Sha256Hex[];
781
+ readonly modules: readonly {
782
+ readonly moduleId: string;
783
+ readonly sha256: Sha256Hex;
784
+ }[];
785
+ readonly requiredCompileUnitIds: readonly string[];
786
+ readonly requiredCellIds: readonly string[];
787
+ }
788
+ interface ShaderValidationEvidenceSubject extends ShaderQualificationCandidateSubject {
789
+ /** Verified externally over the complete immutable archive; never embedded in that archive. */
790
+ readonly dataBundleSha256: Sha256Hex;
791
+ }
792
+ interface ShaderTrustedWorkflowProvenance {
793
+ readonly repository: string;
794
+ readonly commit: GitObjectId;
795
+ readonly ref: string;
796
+ readonly workflowRef: string;
797
+ readonly workflowSha: GitObjectId;
798
+ readonly runId: string;
799
+ readonly runAttempt: number;
800
+ readonly job: string;
801
+ readonly eventName: string;
802
+ readonly oidcAttestation: {
803
+ readonly issuer: "https://token.actions.githubusercontent.com";
804
+ readonly subject: string;
805
+ readonly audience: string;
806
+ readonly verifiedClaimsSha256: Sha256Hex;
807
+ readonly verifiedAt: string;
808
+ readonly source: "trusted-runner-preflight";
809
+ };
810
+ }
811
+ /** Identifies the workflow job and runner that produced a qualification-cell artifact. */
812
+ interface ShaderQualificationExecutionProducer {
813
+ readonly repository: string;
814
+ readonly commit: GitObjectId;
815
+ readonly ref: string;
816
+ readonly runId: string;
817
+ readonly runAttempt: number;
818
+ readonly job: "swiftshader" | "physical" | "physical-runner-preflight";
819
+ readonly trustedWorkflowRepository: "Plasius-LTD/gpu-shader";
820
+ readonly trustedWorkflowRef: string;
821
+ readonly trustedWorkflowSha: GitObjectId;
822
+ readonly runner: {
823
+ readonly name: string;
824
+ readonly environment: "github-hosted" | "self-hosted" | "device-farm";
825
+ readonly os: string;
826
+ readonly architecture: string;
827
+ };
828
+ }
829
+ interface ShaderValidationEvidence {
830
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
831
+ readonly evidenceId: string;
832
+ readonly status: "passed" | "failed";
833
+ readonly generatedAt: string;
834
+ readonly subjectBindingSha256: Sha256Hex;
835
+ readonly subject: ShaderValidationEvidenceSubject;
836
+ readonly matrixRef: {
837
+ readonly matrixId: string;
838
+ readonly version: string;
839
+ readonly sha256: Sha256Hex;
840
+ };
841
+ readonly toolchain: {
842
+ readonly packageVersion: string;
843
+ readonly reflectorVersion: "1.5.0";
844
+ readonly harness: {
845
+ readonly id: string;
846
+ readonly version: string;
847
+ readonly sha256: Sha256Hex;
848
+ };
849
+ };
850
+ readonly qualificationPreflightProvenance: ShaderTrustedWorkflowProvenance;
851
+ readonly counts: {
852
+ readonly compileUnits: number;
853
+ readonly cells: number;
854
+ readonly expectedResults: number;
855
+ readonly passedResults: number;
856
+ };
857
+ readonly cellRuns: readonly ShaderValidationCellRun[];
858
+ readonly results: readonly ShaderQualificationResult[];
859
+ }
860
+ type ShaderQualificationResource = {
861
+ readonly kind: "buffer";
862
+ readonly resourceId: string;
863
+ readonly byteLength: number;
864
+ readonly usage: readonly string[];
865
+ readonly initialData: {
866
+ readonly path: string;
867
+ readonly sha256: Sha256Hex;
868
+ } | null;
869
+ } | {
870
+ readonly kind: "texture";
871
+ readonly resourceId: string;
872
+ readonly dimension: "1d" | "2d" | "3d";
873
+ readonly size: readonly [number, number, number];
874
+ readonly mipLevelCount: number;
875
+ readonly sampleCount: 1 | 4;
876
+ readonly format: string;
877
+ readonly usage: readonly string[];
878
+ readonly initialData: {
879
+ readonly path: string;
880
+ readonly sha256: Sha256Hex;
881
+ readonly bytesPerRow: number;
882
+ readonly rowsPerImage: number;
883
+ readonly mipLevel: number;
884
+ readonly origin: readonly [number, number, number];
885
+ readonly aspect: "all" | "depth-only" | "stencil-only";
886
+ } | null;
887
+ } | {
888
+ readonly kind: "sampler";
889
+ readonly resourceId: string;
890
+ readonly descriptor: Readonly<Record<string, JsonPrimitive>>;
891
+ };
892
+ type ShaderQualificationCommand = {
893
+ readonly kind: "dispatch";
894
+ readonly pipelineId: string;
895
+ readonly bindGroupIds: readonly string[];
896
+ readonly workgroups: readonly [number, number, number];
897
+ } | {
898
+ readonly kind: "draw";
899
+ readonly pipelineId: string;
900
+ readonly bindGroupIds: readonly string[];
901
+ readonly vertexBuffers: readonly {
902
+ readonly slot: number;
903
+ readonly resourceId: string;
904
+ readonly offset: number;
905
+ readonly size: number;
906
+ }[];
907
+ readonly colorAttachments: readonly {
908
+ readonly resourceId: string;
909
+ readonly view: ShaderQualificationTextureViewDescriptor;
910
+ readonly clearValue: readonly [number, number, number, number];
911
+ readonly loadOp: "clear" | "load";
912
+ readonly storeOp: "store" | "discard";
913
+ }[];
914
+ readonly depthStencilAttachment: {
915
+ readonly resourceId: string;
916
+ readonly view: ShaderQualificationTextureViewDescriptor;
917
+ readonly depthClearValue: number;
918
+ readonly depthLoadOp: "clear" | "load";
919
+ readonly depthStoreOp: "store" | "discard";
920
+ readonly stencilClearValue: number;
921
+ readonly stencilLoadOp: "clear" | "load" | null;
922
+ readonly stencilStoreOp: "store" | "discard" | null;
923
+ } | null;
924
+ readonly vertexCount: number;
925
+ readonly instanceCount: number;
926
+ readonly firstVertex: number;
927
+ readonly firstInstance: number;
928
+ } | {
929
+ readonly kind: "copy-buffer";
930
+ readonly source: string;
931
+ readonly destination: string;
932
+ readonly byteLength: number;
933
+ } | {
934
+ readonly kind: "copy-texture-to-buffer";
935
+ readonly source: {
936
+ readonly resourceId: string;
937
+ readonly mipLevel: number;
938
+ readonly origin: readonly [number, number, number];
939
+ readonly aspect: "all" | "depth-only" | "stencil-only";
940
+ };
941
+ readonly destination: {
942
+ readonly resourceId: string;
943
+ readonly offset: number;
944
+ readonly bytesPerRow: number;
945
+ readonly rowsPerImage: number;
946
+ };
947
+ readonly extent: readonly [number, number, number];
948
+ };
949
+ interface ShaderQualificationTextureViewDescriptor {
950
+ readonly format: string | null;
951
+ readonly dimension: "1d" | "2d" | "2d-array" | "cube" | "cube-array" | "3d" | null;
952
+ readonly aspect: "all" | "depth-only" | "stencil-only";
953
+ readonly baseMipLevel: number;
954
+ readonly mipLevelCount: number | null;
955
+ readonly baseArrayLayer: number;
956
+ readonly arrayLayerCount: number | null;
957
+ }
958
+ type ShaderQualificationBindGroupResource = {
959
+ readonly kind: "buffer";
960
+ readonly resourceId: string;
961
+ readonly offset: number;
962
+ readonly size: number;
963
+ } | {
964
+ readonly kind: "texture-view";
965
+ readonly resourceId: string;
966
+ readonly view: ShaderQualificationTextureViewDescriptor;
967
+ } | {
968
+ readonly kind: "sampler";
969
+ readonly resourceId: string;
970
+ };
971
+ /** A declarative host-codec ↔ final-WGSL record-layout probe. */
972
+ interface ShaderQualificationBufferRecordLayoutProbe {
973
+ readonly kind: "buffer-record";
974
+ readonly probeId: string;
975
+ readonly source: {
976
+ readonly moduleId: string;
977
+ readonly group: number;
978
+ readonly binding: number;
979
+ readonly recordName: string;
980
+ };
981
+ readonly pipelineId: string;
982
+ readonly commandIndex: number;
983
+ readonly input: {
984
+ readonly resourceId: string;
985
+ readonly byteOffset: number;
986
+ readonly byteLength: number;
987
+ /** Encoded with createGpuRecordCodec and compared byte-for-byte with admitted initialData. */
988
+ readonly value: JsonValue;
989
+ };
990
+ readonly output: {
991
+ readonly readbackIndex: number;
992
+ readonly recordName: string;
993
+ /** GPU output is decoded with the reflected codec and compared to this value. */
994
+ readonly expectedValue: JsonValue;
995
+ };
996
+ }
997
+ /** A declarative host vertex-format encoder ↔ final-WGSL vertex-fetch probe. */
998
+ interface ShaderQualificationVertexInputLayoutProbe {
999
+ readonly kind: "vertex-input";
1000
+ readonly probeId: string;
1001
+ readonly source: {
1002
+ readonly pipelineId: string;
1003
+ readonly shaderLocation: number;
1004
+ readonly semantic: string;
1005
+ };
1006
+ readonly commandIndex: number;
1007
+ readonly input: {
1008
+ readonly resourceId: string;
1009
+ readonly vertexBufferSlot: number;
1010
+ /** Absolute vertex or instance element selected by the draw command. */
1011
+ readonly elementIndex: number;
1012
+ /** Encoded from the reflected GPUVertexFormat and compared with admitted bytes. */
1013
+ readonly value: JsonValue;
1014
+ };
1015
+ readonly output: {
1016
+ readonly readbackIndex: number;
1017
+ readonly recordName: string;
1018
+ /** GPU-observed vertex value encoded through this reflected output record. */
1019
+ readonly expectedValue: JsonValue;
1020
+ };
1021
+ }
1022
+ type ShaderQualificationLayoutProbe = ShaderQualificationBufferRecordLayoutProbe | ShaderQualificationVertexInputLayoutProbe;
1023
+ interface ShaderQualificationFixtureManifest {
1024
+ readonly contractVersion: typeof SHADER_QUALIFICATION_FIXTURE_VERSION;
1025
+ readonly fixtureId: string;
1026
+ readonly resources: readonly ShaderQualificationResource[];
1027
+ readonly bindGroups: readonly {
1028
+ readonly bindGroupId: string;
1029
+ readonly group: number;
1030
+ readonly entries: readonly {
1031
+ readonly binding: number;
1032
+ readonly resource: ShaderQualificationBindGroupResource;
1033
+ }[];
1034
+ }[];
1035
+ readonly commands: readonly ShaderQualificationCommand[];
1036
+ readonly layoutProbes: readonly ShaderQualificationLayoutProbe[];
1037
+ readonly readbacks: readonly {
1038
+ readonly resourceId: string;
1039
+ readonly byteOffset: number;
1040
+ readonly byteLength: number;
1041
+ readonly expectedSha256: Sha256Hex;
1042
+ }[];
1043
+ readonly bounds: {
1044
+ readonly maxBufferBytes: number;
1045
+ readonly maxTextureTexels: number;
1046
+ readonly maxCommands: number;
1047
+ readonly timeoutMs: number;
1048
+ };
1049
+ }
1050
+ interface ShaderQualificationBundleManifest {
1051
+ readonly contractVersion: typeof SHADER_QUALIFICATION_BUNDLE_VERSION;
1052
+ readonly inventory: ShaderCompileUnitInventory;
1053
+ readonly subject: ShaderQualificationCandidateSubject;
1054
+ readonly shaderManifestCorePath: string;
1055
+ readonly gpuInterfaceManifest: {
1056
+ readonly path: string;
1057
+ readonly sha256: Sha256Hex;
1058
+ };
1059
+ readonly modelCompatibilityFixtures: readonly {
1060
+ readonly fixtureId: string;
1061
+ readonly path: string;
1062
+ readonly sha256: Sha256Hex;
1063
+ }[];
1064
+ readonly modules: readonly {
1065
+ readonly moduleId: string;
1066
+ readonly path: string;
1067
+ readonly sha256: Sha256Hex;
1068
+ }[];
1069
+ readonly fixtures: readonly {
1070
+ readonly fixtureId: string;
1071
+ readonly path: string;
1072
+ readonly sha256: Sha256Hex;
1073
+ readonly kind: "qualification-fixture";
1074
+ }[];
1075
+ }
1076
+ interface ShaderQualificationModelCompatibilityFixture {
1077
+ readonly contractVersion: typeof SHADER_QUALIFICATION_FIXTURE_VERSION;
1078
+ readonly fixtureId: string;
1079
+ readonly model: ModelGpuCompatibilityDescriptor;
1080
+ }
1081
+ interface ShaderCellEvidence {
1082
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
1083
+ readonly qualificationId: string;
1084
+ readonly matrixId: string;
1085
+ readonly matrixVersion: string;
1086
+ readonly matrixSha256: Sha256Hex;
1087
+ readonly cellId: string;
1088
+ readonly dataBundleSha256: Sha256Hex;
1089
+ readonly compileUnitInventorySha256: Sha256Hex;
1090
+ readonly harness: {
1091
+ readonly id: string;
1092
+ readonly version: string;
1093
+ readonly sha256: Sha256Hex;
1094
+ };
1095
+ readonly automation: {
1096
+ readonly kind: "playwright" | "webdriver" | "device-farm" | "safari-webdriver";
1097
+ readonly driver: string;
1098
+ readonly version: string;
1099
+ readonly sha256: Sha256Hex;
1100
+ };
1101
+ /** `sha256("plasius.gpu.qualification-subject/v1\n" + canonical(subject,digests))`. */
1102
+ readonly subjectBindingSha256: Sha256Hex;
1103
+ readonly qualificationPreflightProvenance: ShaderTrustedWorkflowProvenance;
1104
+ readonly producer: ShaderQualificationExecutionProducer;
1105
+ readonly results: readonly ShaderQualificationResult[];
1106
+ }
1107
+ interface ShaderRunnerCellPreflightEvidence {
1108
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
1109
+ readonly kind: "shader-runner-cell-preflight-evidence";
1110
+ readonly qualificationId: string;
1111
+ readonly cellId: string;
1112
+ readonly status: "available" | "runner-unavailable";
1113
+ readonly matrixSha256: Sha256Hex;
1114
+ readonly runnerLabels: readonly string[];
1115
+ /** API-observed self-hosted/device labels, or hosted image labels derived from the actual OS/architecture environment. */
1116
+ readonly matchedRunners: readonly {
1117
+ readonly name: string;
1118
+ readonly labels: readonly string[];
1119
+ }[];
1120
+ /** Independently verified adapter package/code identity, or null when inventory cannot observe it. */
1121
+ readonly adapterHarness: {
1122
+ readonly id: string;
1123
+ readonly version: string;
1124
+ readonly sha256: Sha256Hex;
1125
+ } | null;
1126
+ readonly qualificationPreflightProvenance: ShaderTrustedWorkflowProvenance;
1127
+ readonly producer: ShaderQualificationExecutionProducer;
1128
+ }
1129
+ interface ShaderValidationCellRun {
1130
+ readonly cellId: string;
1131
+ readonly source: "cell-evidence" | "runner-preflight" | "workflow-diagnostic";
1132
+ readonly sourceArtifactSha256: Sha256Hex;
1133
+ readonly resultsSha256: Sha256Hex;
1134
+ readonly qualificationPreflightProvenance: ShaderTrustedWorkflowProvenance;
1135
+ readonly producer: ShaderQualificationExecutionProducer;
1136
+ readonly harness: {
1137
+ readonly id: string;
1138
+ readonly version: string;
1139
+ readonly sha256: Sha256Hex;
1140
+ };
1141
+ /** Null when no adapter actually executed (runner-unavailable/workflow diagnostic). */
1142
+ readonly automation: {
1143
+ readonly kind: "playwright" | "webdriver" | "device-farm" | "safari-webdriver";
1144
+ readonly driver: string;
1145
+ readonly version: string;
1146
+ readonly sha256: Sha256Hex;
1147
+ } | null;
1148
+ readonly resultCount: number;
1149
+ readonly status: ShaderQualificationStatus;
1150
+ }
1151
+ /** Non-secret claims emitted by the trusted prepare job after Blob version and OIDC verification. */
1152
+ interface ShaderQualificationPreflightManifest {
1153
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
1154
+ readonly kind: "shader-qualification-preflight";
1155
+ readonly qualificationId: string;
1156
+ readonly sourceBlob: {
1157
+ readonly host: string;
1158
+ readonly versionId: string;
1159
+ readonly uri: string;
1160
+ };
1161
+ readonly dataBundleSha256: Sha256Hex;
1162
+ readonly compileUnitInventorySha256: Sha256Hex;
1163
+ readonly matrixSha256: Sha256Hex;
1164
+ readonly harnessSha256: Sha256Hex;
1165
+ readonly subjectBindingSha256: Sha256Hex;
1166
+ readonly provenance: ShaderTrustedWorkflowProvenance;
1167
+ }
1168
+ interface ShaderNonQualifyingWorkflowDiagnostic {
1169
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
1170
+ readonly kind: "non-qualifying-workflow-diagnostic";
1171
+ readonly qualificationId: string;
1172
+ readonly cellId: string;
1173
+ readonly status: "timeout" | "failed";
1174
+ readonly matrixSha256: Sha256Hex;
1175
+ readonly message: string;
1176
+ readonly qualificationPreflightProvenance: ShaderTrustedWorkflowProvenance;
1177
+ readonly producer: ShaderQualificationExecutionProducer;
1178
+ }
1179
+ /** External GitHub build-provenance reference; verified outside the evidence JSON digest. */
1180
+ interface ShaderValidationEvidenceAttestationRef {
1181
+ readonly contractVersion: typeof SHADER_VALIDATION_EVIDENCE_VERSION;
1182
+ readonly kind: "shader-validation-evidence-attestation-ref";
1183
+ readonly evidence: {
1184
+ readonly name: string;
1185
+ readonly sha256: Sha256Hex;
1186
+ };
1187
+ readonly attestation: {
1188
+ readonly id: string;
1189
+ readonly url: string;
1190
+ readonly bundle: {
1191
+ readonly name: string;
1192
+ readonly sha256: Sha256Hex;
1193
+ };
1194
+ };
1195
+ readonly producer: {
1196
+ readonly repository: string;
1197
+ readonly runId: string;
1198
+ readonly runAttempt: number;
1199
+ readonly trustedWorkflowRepository: "Plasius-LTD/gpu-shader";
1200
+ readonly trustedWorkflowRef: string;
1201
+ readonly trustedWorkflowSha: GitObjectId;
1202
+ };
1203
+ }
1204
+ interface ShaderCompileFixture {
1205
+ /** Local/hosted testing only. Callback fixtures can never produce trusted physical evidence. */
1206
+ readonly qualificationEligible: false;
1207
+ readonly fixtureId: string;
1208
+ setup(context: ShaderCompileContext): Promise<void>;
1209
+ encode(context: ShaderCompileContext): Promise<void>;
1210
+ verify(context: ShaderCompileContext): Promise<void>;
1211
+ cleanup(context: ShaderCompileContext): Promise<void>;
1212
+ }
1213
+ interface ShaderCompileContext {
1214
+ readonly device: GpuDeviceLike;
1215
+ readonly unit: ShaderCompileUnitManifest;
1216
+ readonly modules: ReadonlyMap<string, GpuShaderModuleLike>;
1217
+ readonly state: Map<string, unknown>;
1218
+ }
1219
+
1220
+ export { type GpuScalarValue as $, type ActiveShaderStyleProfile as A, type GpuBindingResourceLayout as B, type GpuCompareFunction as C, type GpuCompilationMessageLike as D, type GpuEntryPointInterface as E, type FrameBoundaryScheduler as F, type GpuInterfaceManifest as G, type GpuEntryPointIo as H, type GpuHostAddressSpace as I, type JsonValue as J, type GpuInterfaceRef as K, type LoadedShaderStyleProfile as L, type ModelGpuCompatibilityDescriptor as M, type GpuLimitRequirement as N, type GpuMatrixLayout as O, type PromotedShaderCatalogResolver as P, type GpuMatrixValue as Q, type GpuModelAbiProjection as R, type Sha256Hex as S, type GpuModelBindingLayout as T, type GpuModelBindingSelector as U, type GpuModelVertexInputLayout as V, type GpuOverrideLayout as W, type GpuRecordMemberLayout as X, type GpuRecordReferenceLayout as Y, type GpuScalarKind as Z, type GpuScalarLayout as _, type SerializableGpuPipelineDescriptor as a, type ShaderValidationEvidence as a$, type GpuSemanticProjection as a0, type GpuSemanticSelector as a1, type GpuSemanticSource as a2, type GpuShaderModuleLike as a3, type GpuShaderStage as a4, type GpuTypeLayout as a5, type GpuVectorLayout as a6, type GpuVectorValue as a7, type GpuVertexInputLayout as a8, type GpuWorkgroupDimension as a9, type ShaderDiagnosticCode as aA, type ShaderDiagnosticSeverity as aB, type ShaderMatrixBrowserName as aC, type ShaderMatrixOsName as aD, type ShaderNonQualifyingWorkflowDiagnostic as aE, type ShaderQualificationBindGroupResource as aF, type ShaderQualificationBufferRecordLayoutProbe as aG, type ShaderQualificationBundleManifest as aH, type ShaderQualificationCandidateSubject as aI, type ShaderQualificationCommand as aJ, type ShaderQualificationExecutionProducer as aK, type ShaderQualificationFixtureManifest as aL, type ShaderQualificationLayoutProbe as aM, type ShaderQualificationModelCompatibilityFixture as aN, type ShaderQualificationPhaseEvidence as aO, type ShaderQualificationPhaseName as aP, type ShaderQualificationPreflightManifest as aQ, type ShaderQualificationResource as aR, type ShaderQualificationResult as aS, type ShaderQualificationStatus as aT, type ShaderQualificationTextureViewDescriptor as aU, type ShaderQualificationVertexInputLayoutProbe as aV, type ShaderRenderRole as aW, type ShaderRunnerCellPreflightEvidence as aX, type ShaderStyleRoleBinding as aY, type ShaderTrustedWorkflowProvenance as aZ, type ShaderValidationCellRun as a_, type JsonPrimitive as aa, type LoadedShaderVersion as ab, type ReflectGpuInterfaceInput as ac, SHADER_COMPILE_UNIT_VERSION as ad, SHADER_QUALIFICATION_BUNDLE_VERSION as ae, SHADER_QUALIFICATION_FIXTURE_VERSION as af, SHADER_STYLE_PROFILE_MANIFEST_VERSION as ag, SHADER_VALIDATION_EVIDENCE_VERSION as ah, SHADER_VERSION_MANIFEST_VERSION as ai, STABLE_WEBGPU_MATRIX_VERSION as aj, SUPPORTED_ADDITIVE_WEBGPU_MATRIX_POLICIES as ak, SUPPORTED_STABLE_WEBGPU_MATRIX_POLICIES as al, type ScopedShaderValidationEvidenceRef as am, type SerializableGpuBindGroupLayout as an, type SerializableGpuBlendComponent as ao, type SerializableGpuComputePipelineDescriptor as ap, type SerializableGpuPipelineLayout as aq, type SerializableGpuProgrammableStage as ar, type SerializableGpuRenderPipelineDescriptor as as, type SerializableGpuStencilFaceState as at, type ShaderCellEvidence as au, type ShaderCompileContext as av, type ShaderCompileFixture as aw, type ShaderCompileUnitInventory as ax, type ShaderCompileUnitManifest as ay, type ShaderDiagnostic as az, type ShaderRequirements as b, type ShaderValidationEvidenceAttestationRef as b0, type ShaderValidationEvidenceRef as b1, type ShaderValidationEvidenceSubject as b2, type ShaderValidationScopeRequirement as b3, type ShaderVersionRef as b4, type StableWebGpuMatrixCell as b5, type StableWebGpuMatrixManifest as b6, type ShaderVersionManifest as c, type GpuRecordValue as d, type GpuRecordLayout as e, type GpuRecordCodec as f, type ShaderVersionManifestCore as g, type ShaderStyleProfileManifest as h, type GpuCapabilitySnapshot as i, type ShaderResult as j, type ModelShaderCompatibility as k, type ShaderStyleProfileRef as l, type GpuDeviceLike as m, type PreparedShaderStyleProfile as n, type ShaderStyleController as o, type AssembledWgslModule as p, GPU_INTERFACE_MANIFEST_VERSION as q, GPU_SHADER_STORE_FEATURE_FLAG as r, GPU_SHADER_STYLE_SELECTION_CAPABILITY as s, type GeneratedGpuInterfaceArtifacts as t, type GitObjectId as u, type GpuAddressSpace as v, type GpuArrayLayout as w, type GpuAtomicLayout as x, type GpuBindingAccess as y, type GpuBindingLayout as z };