Design rules

115 rules

Every rule of the compiler's design document, docs/language-design.md, read from its traceability tree at commit 26de7be8. A rule constrains an author writing a "use typeshade" file or the compiler itself. Each one states one requirement, why it holds, what it derives from, and where the compiler enforces it.

How each rule is verified, as the traceability tree records it:

Test 107 rules: a test, a gate script or a CI workflow names the rule.
Code only 2 rules: only the implementation carries the rule, and no test checks it yet.
Not enforced 1 rule: listed as not yet enforced, in Appendix B of the design document.
Review 5 rules: held by review, and no file checks them.

What is guaranteed lists the rules of each kind, with the files that verify each one.

The rule text and the parts under it are the compiler's own English, as the design document writes them.

Changes since the previous pin

Between the previous pin, 4dda5269 (2026-10-04), and this one, 26de7be8, as the compiler's traceability tree records them. A rule changed when its fingerprint moved, which happens when its text or the files that verify it change. 0 added, 0 removed, 3 changed.

Changed

Rule 3.2 compiler commits 4ab63ac0
Rule 5.1 compiler commits 4ab63ac0
Rule 8.9 compiler commits 4ab63ac0

1. Introduction

Rule 1.1 Test: A "use typeshade" program must mean what the WGSL program it emits means, unless a rule in this document says otherwise.
Rule 1.2 Code only: GLSL ES 3.00 is a target of the compiler; it must not be the definition of a construct.
Rule 1.3 Test: 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.

2. Sources of the surface

Rule 2.1 Test: Every author-facing name must come from exactly one of three sources:
Rule 2.2 Test: A compiler-internal name (§2.1) must not be authorable.
Rule 2.3 Test: 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.
Rule 2.4 Test: 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.

3. Textual structure and names

Rule 3.1 Test: A shader file must begin with the directive "use typeshade" as its first statement.
Rule 3.2 Test: A local variable, parameter, module constant or module variable may use any identifier TypeScript permits.
Rule 3.3 Test: 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.
Rule 3.4 Test: 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.
Rule 3.5 Test: A name the compiler generates (the mangler, the type aliaser) must not be a keyword or reserved word of either target.
Rule 3.6 Test: 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.
Rule 3.7 Review: 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.
Rule 3.8 Test: 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.
Rule 3.9 Test: 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.

4. Types

Rule 4.1 Test: Every type an author writes must be a WGSL type under a TypeScript spelling, or a member of the f64 family (Rule 4.4).
Rule 4.2 Test: A type alias is another name for its target.
Rule 4.3 Test: 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.
Rule 4.4 Test: 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.
Rule 4.5 Test: 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.
Rule 4.6 Test: number and boolean must not be written as shader types; a number on the GPU has a width, and the boolean is spelled bool.
Rule 4.7 Test: 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.
Rule 4.8 Test: Every matCxR with C and R in 2, 3, 4 must be a type, and a square one must also answer to matN.

5. Literals and typing

Rule 5.1 Test: An integer-written literal must take the integer type the position around it declares.
Rule 5.2 Test: 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.
Rule 5.3 Test: 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.
Rule 5.4 Test: A literal must fit the type it takes; -1 in a u32 position and 2147483648 in an i32 position are refused as written.
Rule 5.5 Test: 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.

6. Declarations and resources

Rule 6.1 Test: 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>.
Rule 6.2 Test: 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>.
Rule 6.3 Test: 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.
Rule 6.4 Test: A pipeline-overridable constant must be written const x: override<T> = default or declare const x: override<T>.
Rule 6.5 Test: 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.
Rule 6.6 Test: 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.
Rule 6.7 Test: 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.
Rule 6.8 Test: 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.
Rule 6.9 Test: A struct must be the members written in it, in one of three spellings (class, interface, a type over an object literal).
Rule 6.10 Test: A local const binds its name once and leaves what it holds as writable as TypeScript does.
Rule 6.11 Test: 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).

7. Expressions and statements

Rule 7.1 Test: An operator, a swizzle, an index, and a call must mean what WGSL’s typing table gives them.
Rule 7.2 Test: Where TypeShade lowers a TypeScript form to a WGSL form, the mapping must be a rule with a recorded divergence; the mappings today are:
Rule 7.3 Test: 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.
Rule 7.4 Test: 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.
Rule 7.5 Test: 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.
Rule 7.6 Not enforced: 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.
Rule 7.7 Test: 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.
Rule 7.8 Test: 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.
Rule 7.9 Test: 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.

8. Functions and entry points

Rule 8.1 Test: An entry point is a top-level function; an entry method on a class must be refused.
Rule 8.2 Test: 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.
Rule 8.3 Test: 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.
Rule 8.4 Test: 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.
Rule 8.5 Test: A collective operation (a derivative, an implicit-LOD texture sample, a barrier) must be in uniform control flow.
Rule 8.6 Test: An entry point must not be called from another function, and neither may a kernel function (Rule 8.22).
Rule 8.7 Test: @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.
Rule 8.8 Test: A parameter an author writes must be passed by value; there must be no pointers and no reference parameters.
Rule 8.9 Test: 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).
Rule 8.10 Test: 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.
Rule 8.11 Test: 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.
Rule 8.12 Test: 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.
Rule 8.13 Test: 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.
Rule 8.14 Test: 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.
Rule 8.15 Test: 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.
Rule 8.16 Test: 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.
Rule 8.17 Test: 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.
Rule 8.18 Test: 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).
Rule 8.19 Test: 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.
Rule 8.20 Test: 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).
Rule 8.21 Test: 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.
Rule 8.22 Test: 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.
Rule 8.23 Test: 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.
Rule 8.24 Test: An exported @compute entry is called from host code as entry(bindings, workgroups).

9. Built-in functions and the TypeShade extensions

Rule 9.1 Test: 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.
Rule 9.2 Test: A builtin’s signature must be WGSL’s, checked at the call.
Rule 9.3 Test: 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.
Rule 9.4 Test: 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).
Rule 9.5 Test: 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.
Rule 9.6 Test: 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.
Rule 9.7 Test: 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].
Rule 9.8 Test: 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.

10. Extensions and capabilities

Rule 10.1 Test: A "use typeshade" file must not spell a WGSL enable or requires statement.
Rule 10.2 Test: The compiler must derive requiredFeatures from the module and must report them through reflect(), with every implied capability included.
Rule 10.3 Test: 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.
Rule 10.4 Test: 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.
Rule 10.5 Test: 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.

11. Targets and the oracle

Rule 11.1 Test: 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.
Rule 11.2 Test: 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.
Rule 11.3 Test: 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.
Rule 11.4 Test: 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.
Rule 11.5 Code only: 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.
Rule 11.6 Test: 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.
Rule 11.7 Test: 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.
Rule 11.8 Test: 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.
Rule 11.9 Test: 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 }.
Rule 11.10 Test: 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.
Rule 11.11 Test: 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.
Rule 11.12 Test: 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.

12. Diagnostics

Rule 12.1 Test: 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.
Rule 12.2 Review: 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.
Rule 12.3 Test: 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.
Rule 12.4 Test: One mistake reads as one diagnostic; a refusal must not be followed by further diagnostics about the same mistake.
Rule 12.5 Test: 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.
Rule 12.6 Test: 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.
Rule 12.7 Test: 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.

13. Change control

Rule 13.1 Review: An issue or pull request that changes what an author can write must cite the rule of this document it rests on.
Rule 13.2 Review: 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.
Rule 13.3 Test: 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.
Rule 13.4 Test: 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.
Rule 13.5 Review: 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.
Rule 13.6 Test: 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.
Rule 13.7 Test: 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.
Rule 13.8 Test: 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.
Rule 13.9 Test: 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.
Rule 13.10 Test: 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).

Edit this page Report a problem