What is guaranteed

A "use typeshade" program must mean what the WGSL program it emits means, unless a rule in this document says otherwise.

Verified by scripts/compile-gate.ts:68

The CPU oracle is the reference evaluation of the IR: where WGSL fixes a result, the oracle must produce that result, and where WGSL leaves room (§11), the oracle’s answer is one of the permitted ones.

Verified by src/core/oracle-backend-parity.test.ts:1src/core/passes/determinism.test.ts:10

Every author-facing name must come from exactly one of three sources:

Verified by src/compiler/ts/class-methods.test.ts:200src/compiler/ts/host-names.test.ts:1src/compiler/ts/matrix-f-aliases.test.ts:4src/compiler/ts/new-expression.test.ts:113src/core/spec-conformance/surface-names.test.ts:136src/language-service/ambient-parity.test.ts:238src/language-service/diagnostics.test.ts:823

A compiler-internal name (§2.1) must not be authorable.

Verified by src/compiler/ts/math-alias.ts:3src/compiler/ts/swizzle-random.test.ts:45src/core/spec-conformance/surface-names.test.ts:50

A value sometimes has to cross between a representation the compiler chose and one the target has: an f64 and the two f32 halves that carry it across an interface of f32.

Verified by src/compiler/ts/f64-types.test.ts:16src/compiler/ts/lower/function.ts:3

An ECMAScript name that has a WGSL meaning must lower to that meaning, and an ECMAScript name that has no WGSL meaning is still an ECMAScript name, whatever the backend expands it to.

Verified by src/core/spec-conformance/surface-names.test.ts:52

A shader file must begin with the directive "use typeshade" as its first statement.

Verified by src/compiler/ts/compile.contract.test.ts:6src/compiler/ts/directive-placement.test.ts:1

A local variable, parameter, module constant or module variable may use any identifier TypeScript permits.

Verified by examples/emit-goldens.test.ts:20src/compiler/ts/function-shadowing.test.ts:1src/compiler/ts/link.test.ts:2src/compiler/ts/link.ts:29src/compiler/ts/reserved-names.test.ts:36src/compiler/ts/reserved-names.ts:7src/core/passes/variable-names.ts:2

A local variable, parameter, module constant or module variable named by a WGSL keyword or reserved word must receive a fresh backend spelling, with every reference rewritten.

Verified by src/compiler/ts/reserved-names.test.ts:36src/compiler/ts/reserved-names.ts:7src/core/passes/variable-names.ts:2src/core/reserved-words.ts:11

A local variable, parameter, module constant or module variable that collides with a GLSL ES 3.00 identifier restriction must be renamed consistently by the GLSL writer; helper function renaming retains its existing behavior.

Verified by src/compiler/ts/reserved-names.test.ts:36src/compiler/ts/reserved-names.ts:7src/core/backends/glsl-sanitize.ts:16src/core/passes/variable-names.ts:2

A name the compiler generates (the mangler, the type aliaser) must not be a keyword or reserved word of either target.

Verified by examples/reserved-word-safety.test.ts:23

A type name an author writes must be lowercase when WGSL declares it and capitalized when TypeShade declares it, so the case of a name says where its meaning comes from.

Verified by src/core/spec-conformance/surface-names.test.ts:52

A shader module that host code imports is named *.shade.ts, and a host import of a .ts file that begins with the directive under any other name must be refused with the rename.

Verified by src/vite.test.ts:1src/vite.ts:21

A shader file may import what another shader file exports, by a relative specifier or, from a package, by the package’s name; the file a compile starts from and every shader file it imports, directly or through another, are one program, which emits one module, and each file keeps the scope TypeScript gives it.

Verified by scripts/user-journey.ts:24src/compiler/ts/link.test.ts:1src/compiler/ts/link.ts:1src/compiler/ts/specifier.test.ts:1src/compiler/ts/specifier.ts:1src/language-service/check.test.ts:216src/vite.test.ts:2

Every type an author writes must be a WGSL type under a TypeScript spelling, or a member of the f64 family (Rule 4.4).

Verified by src/compiler/ts/type-map.ts:3src/core/spec-conformance/surface-names.test.ts:52

A type alias is another name for its target.

Verified by src/compiler/ts/type-alias.test.ts:10src/compiler/ts/type-structs.test.ts:12

A brand must be erased: f32 & { readonly [m]: 'm' } and { readonly __brand: 'm' } are the carrier type, and the brand must reach no emitted text.

Verified by examples/shade-examples.test.ts:26

The f64 family (f64, vec2f64, vec3f64, vec4f64, the short spellings vec2d, vec3d, and vec4d and, by type argument, mat2<f64>, mat3<f64>, and mat4<f64>) is the one numeric type family TypeShade adds that WGSL does not have.

Verified by src/core/passes/fp64-lower.test.ts:3

A TypeScript type the GPU has no word for must be refused in one sentence naming the reason and what to write instead; the list is surface §28 and is not repeated here.

Verified by src/compiler/ts/honest-refusals.test.ts:19

number and boolean must not be written as shader types; a number on the GPU has a width, and the boolean is spelled bool.

Verified by src/compiler/ts/honest-refusals.test.ts:19

f16 and the h spellings must not be authorable until the roadmap’s After 1.0 row is picked up; the f16 capability may be declared through the EDSL and nothing an author writes uses it.

Verified by src/core/backends/capability-reachability.test.ts:40

Every matCxR with C and R in 2, 3, 4 must be a type, and a square one must also answer to matN.

Verified by examples/shade-examples.test.ts:26src/compiler/ts/bindings.ts:613src/compiler/ts/matrices.test.ts:14src/compiler/ts/type-map.ts:3src/compiler/ts/uniform-layout.test.ts:547src/core/reflect.test.ts:1src/core/reflect.ts:18src/core/std140.ts:7

An integer-written literal must take the integer type the position around it declares.

Verified by src/compiler/ts/int-lit-coerce.test.ts:1src/compiler/ts/int-lit-context.test.ts:7src/compiler/ts/lit-coerce.ts:1src/compiler/ts/local-numeric-inference.test.ts:1src/compiler/ts/local-numeric-inference.ts:1

A written number beside a typed peer in an arithmetic operator or a builtin call must take the peer’s kind; a written number beside an f64 or an f64 vector must become an f64 literal carrying the full double.

Verified by src/compiler/ts/f64-types.test.ts:16src/compiler/ts/int-lit-coerce.test.ts:1src/compiler/ts/int-lit-context.test.ts:7src/compiler/ts/numeric.ts:3

There is no implicit conversion between concrete types; an i32 beside a u32, or an integer beside a float, must be refused with the cast to write.

Verified by src/compiler/ts/local-numeric-inference.test.ts:1src/compiler/ts/numeric.test.ts:1src/compiler/ts/numeric.ts:3

A literal must fit the type it takes; -1 in a u32 position and 2147483648 in an i32 position are refused as written.

Verified by src/compiler/ts/int-lit-context.test.ts:7src/compiler/ts/local-numeric-inference.test.ts:1

A single float-written literal valued as a whole number may take a declared integer type in a declaration only; a return, an argument, and a field must not take that carve-out.

Verified by src/compiler/ts/int-lit-context.test.ts:7

A resource must be written declare const x: uniform<T>, declare const x: storage<T>, declare const x: storage<T, "read_write">, or declare const x: <texture or sampler type>.

Verified by examples/binding-declared.test.ts:29src/compiler/ts/bindings.ts:1

A storage binding’s access mode is its second type argument: storage<T> is var<storage, read> and storage<T, "read_write"> is var<storage, read_write>.

Verified by src/compiler/ts/bindings.ts:1src/compiler/ts/context.ts:1src/compiler/ts/declare-bind.test.ts:1src/compiler/ts/lower/atomics.ts:1src/compiler/ts/member-assign.test.ts:6src/compiler/ts/remedy-lines.test.ts:1src/language-service/ambient.test.ts:1

A top-level const is a module constant: a scalar must fold to one value carried at double precision for the oracle and at the target’s precision for emit, and a vector, array, or struct must carry a constant-foldable expression every backend evaluates.

Verified by src/compiler/ts/module-const.test.ts:1src/compiler/ts/module-const.ts:3

A pipeline-overridable constant must be written const x: override<T> = default or declare const x: override<T>.

Verified by examples/override-constants.test.ts:9

A top-level let is a module variable in the per-invocation (private) address space; workgroup memory must be written let x: workgroup<T>; a module variable must take no declare.

Verified by src/compiler/ts/module-vars.test.ts:10

An entry point’s inputs and outputs are explicit parameters and return values; every parameter and every field of an entry I/O struct must carry @builtin("...") or @location(n), and the builtin name must be one WGSL defines for that stage and direction.

Verified by src/compiler/ts/builtin-values.test.ts:21src/compiler/ts/stage3.test.ts:6

The attribute names the compiler reads are @vertex, @fragment, @compute, @builtin, @location, @interpolate, @invariant, @blend_src, and @diagnostic (the last four since #168, surface §53 and §54); every other WGSL attribute is either inferred by the compiler or carried as an argument (@compute([64, 1, 1]) carries @workgroup_size), and a decorator outside that list must be refused.

Verified by src/compiler/ts/stage3.test.ts:6src/core/spec-conformance/surface-names.test.ts:52src/language-service/service.test.ts:142

The byte layout the emitted module assumes for a resource and the layout reflect() reports must agree byte for byte, under WGSL’s uniform and storage layout rules, and so must the layout the manifest carries (Rule 11.10); a vertex entry’s vertex buffer is one layout, its @location inputs tightly packed in the order written, which reflect().vertex and the manifest both report.

Verified by examples/emit-reflection-conformance.test.ts:31src/compiler/ts/uniform-layout.test.ts:20src/core/manifest.test.ts:6src/core/reflect.ts:18

A struct must be the members written in it, in one of three spellings (class, interface, a type over an object literal).

Verified by examples/shade-examples.test.ts:26src/compiler/ts/class-syntax.test.ts:1585src/compiler/ts/inheritance.test.ts:12src/compiler/ts/type-structs.test.ts:12

A local const binds its name once and leaves what it holds as writable as TypeScript does.

Verified by examples/shade-examples.test.ts:26src/compiler/ts/class-methods.test.ts:688src/compiler/ts/class-syntax.test.ts:1372src/compiler/ts/member-assign.test.ts:372

The compiler adds one binding an author did not write for a console call, and only when a compile asks for GPU recording (compile(src, { console: 'gpu' })): _console, a read_write storage buffer of struct _Console { cursor: atomic<u32>, dropped: atomic<u32>, words: array<u32> }, at group 0, the first binding past the module’s own group-0 bindings, the slot the _fp64 guard takes by the same rule (the guard, when there is one, comes one past it).

Verified by src/core/passes/console-buffer.test.ts:9src/core/passes/console-buffer.ts:25

An operator, a swizzle, an index, and a call must mean what WGSL’s typing table gives them.

Verified by src/compiler/ts/lower/operator-kinds.ts:1src/compiler/ts/operators-statements.test.ts:17src/core/oracle-backend-parity.test.ts:1src/language-service/service.test.ts:198

Where TypeShade lowers a TypeScript form to a WGSL form, the mapping must be a rule with a recorded divergence; the mappings today are:

Verified by examples/emit-goldens.test.ts:20examples/loop-examples.test.ts:1src/core/kernel-tree.test.ts:1

An empty switch case directly above a case with a body is one clause with several selectors (case 0: case 1: is WGSL’s case 0, 1:); an empty case with no case below it or directly above default:, and an empty default: with a case after it, must be refused; a case body must not fall through into the body of a case below it.

Verified by src/compiler/ts/fallthrough.ts:1src/compiler/ts/operators-statements.test.ts:230src/compiler/ts/switch-array.test.ts:1

A shift amount the compiler can fold must be in 0 to 31; a divisor the compiler can prove to be zero must be refused where the division is lowered.

Verified by src/compiler/ts/loop-bound.ts:4src/compiler/ts/lower/expression.ts:3src/compiler/ts/lower/statement.ts:3src/compiler/ts/module-const.ts:3src/compiler/ts/shift-amount.test.ts:8src/compiler/ts/zero-divisor.test.ts:7

A for loop must be counted: an i32 or u32 induction variable, a constant step, and an exit that compares the induction variable to a bound; the start and the bound may be runtime values, the loop body must not write the bound, and the step must move the variable toward the bound.

Verified by examples/shade-examples.test.ts:26src/compiler/ts/loop-shapes.test.ts:19src/compiler/ts/lower/control.ts:32src/compiler/ts/runtime-loop-bound.test.ts:1

discard must be written as a bare statement, the identifier alone (discard), and may stand in a fragment entry and in a helper no vertex or compute entry can reach.

Verified by src/compiler/ts/builtins.test.ts:6src/compiler/ts/unknown-names.test.ts:3

The refusals of surface §28 (a union of two GPU types, a string type, a nullable, a mixed tuple, a rest tuple, symbol, an intersection of carriers, instanceof, in) must apply to expressions as they do to types, each in one sentence.

Verified by src/compiler/ts/console.test.ts:60src/compiler/ts/honest-refusals.test.ts:19

An expression must be evaluated left to right, as TypeScript and WGSL both evaluate it, and a call that writes (its object, a module variable, a storage binding, an atomic location) inside a larger expression must take effect in that order on every target.

Verified by examples/shade-examples.test.ts:26src/compiler/ts/sequence.test.ts:2src/compiler/ts/sequence.ts:1

An entry point is a top-level function; an entry method on a class must be refused.

Verified by src/compiler/ts/class-syntax.test.ts:20

A vertex entry must return the position, as a bare vec4 or as a struct with a @builtin("position") field; a fragment entry returns one @location(0) value, a struct of render targets, or nothing.

Verified by src/compiler/ts/entry-io.test.ts:17

A builtin WGSL confines by stage may be used in an entry of a permitted stage, and in a helper that no entry of an excluded stage can reach.

Verified by src/compiler/ts/atomics.test.ts:10src/compiler/ts/lower/function.ts:3

A function must not take part in a call cycle, directly or through other functions; the check reads the calls a body writes, and the calls a method call, an accessor and new lower to, before any optimisation, so a call in a branch the optimizer would drop is a cycle too.

Verified by src/compiler/ts/class-syntax.test.ts:1626src/compiler/ts/default-args.test.ts:9src/compiler/ts/namespace.test.ts:9src/compiler/ts/recursion.test.ts:17

A collective operation (a derivative, an implicit-LOD texture sample, a barrier) must be in uniform control flow.

Verified by src/compiler/ts/barriers.test.ts:10src/core/passes/uniformity.test.ts:23

An entry point must not be called from another function, and neither may a kernel function (Rule 8.22).

Verified by src/compiler/ts/kernel-loops.test.ts:3src/compiler/ts/operators-statements.test.ts:17

@compute carries the workgroup size as an array literal of one to three whole numbers, x, y and z, a missing y or z being 1, and the default is 64; every extent reaches the emitted @workgroup_size and the reflection, and a shape over WebGPU’s default compute limits must be reported as a warning.

Verified by src/compiler/ts/stage3.test.ts:6

A parameter an author writes must be passed by value; there must be no pointers and no reference parameters.

Verified by src/compiler/ts/lower/function.ts:2889src/compiler/ts/mutable-parameters.test.ts:1src/compiler/ts/overloads.test.ts:9src/compiler/ts/tint-invalid.test.ts:167

Method dispatch must be static, and a generic function or class must be compiled once per set of type arguments the program uses (Rule 3.9).

Verified by examples/shade-examples.test.ts:26src/compiler/ts/class-syntax.test.ts:22src/compiler/ts/class-upcasts.test.ts:1src/compiler/ts/class-upcasts.ts:1src/compiler/ts/fieldless-classes.test.ts:1src/compiler/ts/link.test.ts:3src/core/passes/empty-struct.test.ts:1src/core/passes/empty-struct.ts:1

A method that writes its object (assigns to this or to a field, a component or an element of it, applies ++ or -- to one, or calls such a method or reads such a getter on this, on a field, a component or an element of it whatever class that field is, or through super) must take the object by reference, and may return a value like any other method; a base’s body that a class calls through super and that writes its object takes it by reference too, and so does the copy of a method that takes a function (Rule 8.18) when a function handed over writes the variable the call is on.

Verified by examples/shade-examples.test.ts:26src/compiler/ts/class-methods.test.ts:8src/compiler/ts/class-syntax.test.ts:1022src/compiler/ts/higher-order.test.ts:517src/compiler/ts/inout-params.test.ts:25

A get or set accessor is a function of the module, Owner_get_x or Owner_set_x, which takes its object as a method does (Rule 8.10); a read of o.x must call the getter, and an assignment, a compound assignment, ++ and -- must call the setter with the new value, the compound forms reading the old one through the getter.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/class-syntax.test.ts:90

A private name #x must be emitted without its #: a field as the struct member x, a method as Owner_x, an accessor as Owner_get_x and Owner_set_x, a static field as Owner_x.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/class-syntax.test.ts:322

A static field must be a module constant Owner_x when nothing in the program writes it, and a module variable in the per-invocation space (Rule 6.5) when something does; a readonly static is never written.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/class-methods.test.ts:259src/compiler/ts/class-syntax.test.ts:442src/compiler/ts/link.test.ts:4

A constructor’s parameter property (constructor(public x: f32), or private, protected or readonly in place of public) is a field of its class, at the constructor’s place among the members, which the constructor assigns from the parameter before the field initializers run.

Verified by src/compiler/ts/class-syntax.test.ts:488

A member declared private may be named only inside the body of the class that declares it, and one declared protected only inside the bodies of that class and of the classes that extend it, on an object of the naming body’s own class or of one that extends it; a name either rule does not allow must be refused with the remedy.

Verified by src/compiler/ts/class-syntax.test.ts:948

An instance field that holds an arrow function or a function expression is a method of its class under the field’s name: the function’s parameters, return type and body are the method’s, an expression body is the value it returns, and this in it is the object, as it is in TypeScript.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/class-methods.test.ts:278src/compiler/ts/class-syntax.test.ts:1443

A local function (a const that holds an arrow function or a function expression, or a function declaration, written inside a function’s body) is a function of the module named after the body that declares it (surface §14), and it may read and write the variables of the functions around it, as a TypeScript closure does.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/closures.test.ts:2src/compiler/ts/mutable-parameters.test.ts:1

A function whose parameter has a function type, written out (f: (x: f32) => f32) or through a type alias of one, takes a function: a function declared at the top of the file or of a namespace, a method, a static method, a constructor, a field that holds a function (Rule 8.16) and a local function (Rule 8.17).

Verified by examples/shade-examples.test.ts:27src/compiler/ts/array-methods.test.ts:1src/compiler/ts/higher-order.test.ts:1

A function that writes no return type returns what its body does, as TypeScript infers it: a function of the file or of a namespace, a local function (Rule 8.17), each instance of a generic function (Rule 8.9) and of a function that takes a function (Rule 8.18), a method, a getter and a field that holds a function (Rule 8.16) take the type of their first return with a value, the returns after it are typed against that type as against a written one, and one with no such return returns nothing.

Verified by examples/shade-examples.test.ts:27src/compiler/ts/return-inference.test.ts:1

A function a host file can call through an import of its module is an exported function that is not an entry point, is not generic, takes no function, has a host value (Rule 8.21) for each parameter and for its result, and reaches, through the calls of its body, no binding, no workgroup variable and no builtin only a GPU computes (a derivative, a barrier, an atomic, an implicit-LOD texture sample).

Verified by src/compiler/ts/host-face.test.ts:1src/compiler/ts/host-face.ts:6

A host call passes and returns host values by value: an f32, f64, i32 or u32 is a number, a bool a boolean, a vector a readonly tuple of its components as an argument and a tuple as a result, a matrix a flat column-major array of its components, an array<T, N> an array of N host values of T, a struct an object of its fields, and an enum member its number.

Verified by src/compiler/ts/fieldless-classes.test.ts:1src/compiler/ts/host-draw.test.ts:2src/compiler/ts/host-entry.test.ts:2src/compiler/ts/host-face.test.ts:2src/compiler/ts/host-face.ts:7src/compiler/ts/host-kernel.test.ts:1src/core/host-values.ts:1src/core/passes/empty-struct.test.ts:1

A kernel function is an exported function that is not an entry point and takes at least one array with no size (array<T>); its candidate loops are the for and for…of statements at the top level of its body, and no other loop is ever a candidate.

Verified by examples/loop-examples.test.ts:2src/compiler/ts/host-kernel.test.ts:2src/compiler/ts/kernel-corpus.test.ts:1src/compiler/ts/kernel-loops.test.ts:1src/compiler/ts/kernel-loops.ts:1src/core/host-kernel.ts:212src/core/kernel-tree.test.ts:1src/core/kernel-tree.ts:1src/core/passes/kernel-lower.ts:1src/core/passes/parallel-loop.test.ts:1src/core/passes/parallel-loop.ts:1

A kernel function’s parameter of an array with no size is the caller’s storage, passed by reference: the body reads and writes its elements in place, reads its .length, and cannot assign it whole; whether the body writes it decides its access.

Verified by src/compiler/ts/host-kernel.test.ts:3src/compiler/ts/kernel-loops.test.ts:2src/compiler/ts/lower/function.ts:2080src/core/ir/kernels.ts:1

An exported @compute entry is called from host code as entry(bindings, workgroups).

Verified by scripts/entry-calls.ts:1scripts/user-journey.ts:259src/compiler/ts/host-draw.test.ts:1src/compiler/ts/host-entry.test.ts:1src/compiler/ts/host-face.ts:111src/core/console-print.test.ts:4src/core/console-print.ts:1src/core/host-compute.ts:36src/core/host-draw.ts:1src/core/host-entry.ts:1src/vite.test.ts:3src/vite.ts:13

Every builtin id the compiler can emit must be classified as portable (PORTABLE_INTRINSICS) or as a row of the INTRINSICS registry; an unclassified id must not reach a backend.

Verified by src/core/intrinsic-coverage.test.ts:1

A builtin’s signature must be WGSL’s, checked at the call.

Verified by src/compiler/ts/lower/math-args.ts:22src/core/spec-conformance/surface-names.test.ts:50

A WGSL builtin GLSL ES 3.00 has no spelling for must be behind a capability, and the GLSL emit must fail closed on it.

Verified by src/core/backends/capability-reachability.test.ts:40src/core/passes/required-caps.ts:10

A Math member and its free-function spelling must lower to the WGSL builtin of the same meaning; a Math member with no WGSL builtin must be expanded into WGSL arithmetic and stays an ECMAScript name; Math.fround(x) is f32(x).

Verified by src/compiler/ts/math-expand.test.ts:1src/core/spec-conformance/surface-names.test.ts:260

A function the file declares or imports (Rule 3.9) must win over a builtin of the same name, as a module-scope declaration hides a predeclared object in WGSL.

Verified by src/compiler/ts/builtins.test.ts:6src/compiler/ts/closures.test.ts:664src/compiler/ts/higher-order.test.ts:908src/compiler/ts/link.test.ts:5

The author-facing names of source (c) must be exactly the rows below; the table is shrink-only, and a name may join it only by Rule 13.6.

Verified by src/core/spec-conformance/surface-names.test.ts:559

A name must be added to the table in this order and in no other: the rationale is written into this section (and into Rule 4.4’s family for an f64 type), the row is added to TYPESHADE_EXTENSIONS with the same reason, the surface document gains or extends a §, and CHANGELOG.md gains an entry under [Unreleased].

Verified by src/core/spec-conformance/surface-names.test.ts:787

A row, a declaration, a signature, an overload, or a member must never be added for a compiler-internal name (§2.1), under its own id, under an allowed id, or under a new spelling that denotes the same thing.

Verified by src/core/spec-conformance/surface-names.test.ts:551

A "use typeshade" file must not spell a WGSL enable or requires statement.

Verified by src/compiler/ts/builtin-values.test.ts:21

The compiler must derive requiredFeatures from the module and must report them through reflect(), with every implied capability included.

Verified by src/core/backends/extension-profile.test.ts:117src/core/passes/required-caps.test.ts:1

A GLSL ES 3.00 emit that lacks a capability’s row must fail closed with the target sentence, which opens backend 'glsl-es300' cannot emit this module and ends missing capabilities: <ids>; on a module with a render entry that is a TS8015 warning that leaves wgsl in place, and on a compute-only module it is silence, glsl being undefined.

Verified by src/compiler/ts/compile.contract.test.ts:6src/core/backends/glsl-compute.test.ts:8src/core/backends/glsl.test.ts:15src/core/passes/required-caps.test.ts:1

Every capability must have a witness: a module shape an author can write that uses the feature; a declarable capability with no witness is recorded as such and never advertised as usable.

Verified by src/core/backends/capability-reachability.test.ts:40

A GLSL lowering of a WGSL-only feature (the family #130 to #139: 1d, multisampled, depth read both ways, gather, cube array, storage texture, read-write storage, atomics, and barriers) is deferred by the maintainer, and must not be written until the deferral is lifted.

Verified by src/core/backends/capability-reachability.test.ts:40

There must be one IR, and the WGSL writer, the GLSL ES 3.00 writer, and the CPU oracle must consume it over one shared tree walk; a new emit feature must go into the shared walk, or the oracle and the GLSL writer drift.

Verified by examples/glsl-stages-parity.test.ts:20src/core/oracle-backend-parity.test.ts:1

A divergence between targets, or between a target and the oracle, must be measured on Tint and on a WebGL2 driver before it is kept, and recorded where the emit is decided: a comment on the INTRINSICS row with the measured text, and a row of the determinism report (surface §38) where the results may differ.

Verified by src/core/passes/determinism.test.ts:10

Every registered example must compile on Tint and, where the module has a GLSL row for each capability it needs, on a WebGL2 driver; an example that is WGSL-only says so with renderable: false and a stated reason.

Verified by scripts/compile-gate.ts:68

An emit golden is a reviewed artifact: a change to examples/__emit-goldens__/ must be read as a diff and must not be re-baked as a rubber stamp.

Verified by examples/emit-goldens.test.ts:20examples/shade-examples.test.ts:27

The public API surface (src/__api__/surface.md) is generated and must not be edited by hand; an exported name or type may change only with a re-bake.

Verified by src/api-surface.test.ts:51

The CPU tier, which runs a host call of a module’s function and, where there is no GPU tier, the invocations of an entry a host calls and the pixels of a fragment entry a host draws (Rule 8.24), is the oracle’s generated code (generateModuleJs) at f32 precision, written into the module the bundler reads as module code, with no new Function, over the op library alone, typeshade/runtime/internal.

Verified by src/compiler/ts/host-draw.test.ts:3src/compiler/ts/host-entry.test.ts:3src/compiler/ts/host-face.test.ts:3src/compiler/ts/host-face.ts:11src/core/host-runtime.ts:1

A kernel function’s call (Rule 8.21) runs on the first tier of configure({ prefer }) that can run it, WebGPU, WebGL2 and the CPU tier being the default order: WebGPU when the function lowers (Rule 8.22) and there is a device, WebGL2 when every loop writes one array of 4-byte elements (f32, i32, u32) at exactly i and every scalar parameter is a number or a vector, each loop one fragment program into an R32UI target that starts out holding the array, so an iteration that writes nothing leaves its element, and the CPU tier always; a list of one tier makes that tier required, and a call no tier on the list can run throws an Error naming each tier’s reason.

Verified by src/compiler/ts/host-draw.test.ts:333src/compiler/ts/host-entry.test.ts:177src/compiler/ts/host-face.ts:765src/compiler/ts/host-kernel.test.ts:279src/core/host-compute.ts:37src/core/host-draw.ts:25src/core/host-kernel-gl.ts:1src/core/host-kernel.ts:104src/core/passes/kernel-lower.ts:1062src/core/resident.ts:2src/runtime/runtime.test.ts:5

A console call computes nothing a shader reads: its arguments must be evaluated once, in order, on every target, and the call then delivers an event, { method, args, span, invocation }.

Verified by src/compiler/ts/console.test.ts:8src/core/debug/console.test.ts:8src/core/passes/console-buffer.test.ts:9src/core/passes/console-buffer.ts:25

A compiled program’s manifest, what packModule() returns and what the default export of a module’s host import is, must be one JSON object that carries its schema (schema, 1) and the package version that wrote it (compiler); each binding with its group and slot, its resource in reflect()’s vocabulary, the stages that reach it, and a buffer’s byte layout with every offset, size and stride under the rule of its space (Rule 6.8), the _fp64 guard the emit adds among them; each entry with its stage, its workgroup size, its inputs and outputs with their locations, builtins and interpolation, the bindings it reaches and which it writes, a vertex entry’s vertex buffer, and its line; the overrides and the WebGPU features; with console, the recorded variant, its WGSL, its log table and its bindings; with ir, the program as portable IR and the package version that wrote it, which emitted again gives every other field byte for byte; and what the WebGL2 tier uses, each full-screen fragment entry’s GLSL ES 3.00 program, block names and texture-sampler pairs, and each storage array’s data texture.

Verified by src/compiler/ts/host-face.ts:369src/compiler/ts/pack.ts:20src/core/emit.ts:747src/core/ir/portable.test.ts:1src/core/manifest.test.ts:1src/core/manifest.ts:447src/core/passes/texture-pairs.test.ts:2src/core/passes/texture-pairs.ts:1src/core/reflect.ts:18src/vite.test.ts:67

The program runtime, typeshade/runtime, loads a manifest (Rule 11.10) and runs its entries on WebGPU, on the host’s device or on one it requests with the features the programs need; its module closure must hold no file of src/compiler/ and no package, and its bundle must stay within the size budget scripts/bundle-budget.json records.

Verified by journeys/_harness.mjs:16scripts/bundle-boundary.ts:1scripts/entry-calls-page.ts:10src/runtime/program.ts:1src/runtime/resources.ts:1src/runtime/runtime.test.ts:1src/runtime/runtime.ts:1

An integer division, remainder and shift, and a float’s conversion to an integer, must give WGSL’s answer on GLSL ES 3.00 for every input WGSL settles: the GLSL writer spells each through a helper that settles the inputs GLSL ES 3.00 leaves undefined, and uses the bare operator only where the operands cannot reach one.

Verified by scripts/gpu-differential.ts:35src/core/backends/glsl-int-answers.test.ts:1src/core/backends/glsl-int.ts:1

A diagnostic must name the offending thing and the remedy in at most two sentences: the first states the mistake, and the second, when there is one, states the remedy or the reason.

Verified by src/compiler/ts/foreign-names.test.ts:2src/compiler/ts/foreign-names.ts:9src/compiler/ts/honest-refusals.test.ts:19src/compiler/ts/unknown-names.test.ts:1src/compiler/ts/unknown-names.ts:1src/language-service/editor-parity.test.ts:2

Severity must follow the target’s role: a program WGSL refuses must be an error; a shortfall of GLSL ES 3.00 on a module with a render entry must be a warning that leaves wgsl in place; a compute-only module’s GLSL shortfall must be no diagnostic at all.

Verified by src/compiler/ts/compile.contract.test.ts:6src/compiler/ts/reserved-names.test.ts:36

One mistake reads as one diagnostic; a refusal must not be followed by further diagnostics about the same mistake.

Verified by src/compiler/ts/generic-classes.test.ts:428src/compiler/ts/honest-refusals.test.ts:19src/compiler/ts/host-names.test.ts:21src/compiler/ts/refused-names.ts:1src/language-service/diagnostics.test.ts:1src/language-service/diagnostics.ts:1227

The message text is part of the contract: a test that pins a refusal must assert the code and the text, and a change to the text is a change to the surface.

Verified by src/compiler/ts/honest-refusals.test.ts:19

A requirement the front end can check must be checked at the front end, in the author’s words, and not left to Tint or a driver.

Verified by src/compiler/ts/clamp-bounds.test.ts:6src/compiler/ts/f32-const-range.test.ts:5src/compiler/ts/honest-refusals.test.ts:19src/compiler/ts/loop-shapes.test.ts:19src/compiler/ts/lower/runtime-array.ts:1src/compiler/ts/runtime-array-values.test.ts:1src/compiler/ts/unknown-names.test.ts:2

The language service and the compiler must name one vocabulary: the ambient library’s declarations are derived from the compiler’s own tables and never retyped, a builtin’s overloads from Tint’s core.def through the TypeShade overlay, and a program the compiler accepts must draw no error in the editor or in tshc check.

Verified by src/compiler/ts/doc-snippets.test.ts:191src/compiler/ts/type-spelling.test.ts:15src/core/spec-conformance/coredef-overloads.test.ts:1src/core/spec-conformance/surface-names.test.ts:52src/language-service/ambient.test.ts:1src/language-service/diagnostics.test.ts:2src/language-service/editor-parity.test.ts:1src/language-service/expression-parity.test.ts:1src/language-service/hover.test.ts:358src/language-service/projection.test.ts:1src/language-service/projection.ts:37

A design that a target might refuse must be measured on Tint, on a WebGL2 driver, or on a device before it is kept, and the measured text must be recorded in the plan and in the code comment.

Verified by scripts/compile-gate.ts:68

Every change must pass the mechanical gates: bun run build; bun run test, with surface-names.test.ts, intrinsic-coverage.test.ts, capability-reachability.test.ts, determinism.test.ts, api-surface.test.ts, emit-reflection-conformance.test.ts, and the emit goldens among them; bun run gate:compile; the docs snippet test src/compiler/ts/doc-snippets.test.ts, which compiles every snippet of the surface document.

Verified by .github/workflows/ci.yml:3

A new author-facing name must be added only by its source: a WGSL name by citing the specification section that declares it, and an ECMAScript name by citing the Math or console member it is.

Verified by src/core/spec-conformance/surface-names.test.ts:52

The extension table must shrink when WGSL grows a builtin or a type a row was standing in for, or when a spelling is withdrawn; the row must be deleted, the surface document must say so, and the CHANGELOG must record it.

Verified by src/core/spec-conformance/surface-names.test.ts:52

Every change to the surface must carry a CHANGELOG entry under [Unreleased] in the house style (a bold lead naming the feature and the § or roadmap item, then what an author can now write, what each target emits, what is refused and how, and what was measured) and a surface § whose snippets compile.

Verified by src/compiler/ts/doc-snippets.test.ts:34

A published version must follow Semantic Versioning 2.0.0, and before 1.0.0 the minor is the breaking position: a breaking change must ship only in a new 0.N.0, and a 0.N.P must only fix and add.

Verified by src/changelog.test.ts:1

A change that keeps a program compiling and makes it compute something else must ship in two steps, and the second must come no earlier than the next breaking release after the first step’s release was published (the next minor before 1.0.0, the next major after it).

Verified by src/compiler/ts/integer-literal-deprecation.test.ts:8

GLSL ES 3.00 is a target of the compiler; it must not be the definition of a construct.

Implemented in src/core/passes/required-caps.ts:10

Where WGSL fixes a result and GLSL ES 3.00 does not, the oracle must follow WGSL; where a GLSL spelling answers differently on an input WGSL settles, the determinism report must list the operation as target.

Implemented in src/core/passes/determinism.ts:46

A read of a local before its first assignment is zero on WGSL and on the CPU, and undefined on GLSL ES 3.00; the divergence is recorded and the author should assign before reading.

A new surface section must take the next free § number in docs/use-typeshade-surface.md as the current tree makes it, and a new diagnostic must take the next free TS80xx code in src/compiler/ts/codes.ts.

src/compiler/ts/codes.ts:15

A code must be TS8 followed by a sequential number in the order codes were added, or a number from a block handed to a parallel branch (Rule 3.7), whose unused numbers stay a gap.

An issue or pull request that changes what an author can write must cite the rule of this document it rests on.

A change the rules do not cover must change the rules first: the rule is written or amended in this document, in the same pull request, before the surface moves.

A hot-spot file must be edited only after reading what the branch already did to it, and a claim of a § number, a TS80xx code, or an INTRINSICS row must be made in the issue before the branch is opened.