@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/materialGraph.ts

@@ -0,0 +1,1220 @@
+/**
+ * The material graph IR (SHARD-PLATFORM SF59 step 3, G155; `docs/design/mmo/research/sf59-tsl-spike.md` §4): a typed,
+ * versioned graph of approved nodes that a material (`family: "graph"`) or a post pass points to. Content carries this
+ * data and never shader code: the compiler (`render/graph/glsl.ts`, loaded lazily through `render/graphBackend.ts`)
+ * lowers each node to GLSL in our own code (the MaterialXLoader pattern), so three's `NodeLoader`, `CodeNode` and
+ * `glslFn` stay out of reach of content (§2.9).
+ *
+ * The shape (version 1, the starter vocabulary; §4 lists the ≈ 60 the format grows to):
+ * - `nodes`: id → `{ op, in?, … }`; an input is another node's id or a literal number / 2–4 number array;
+ * - `stages`: `vertex.offset` (a displacement in the mesh's model space, added after an instance's own transform: an
+ *   instanced mesh's `positionLocal` already carries it; `positionGeometry` is the vertex before it), `surface` (colour,
+ *   alpha, cutoff, emissive, roughness, metalness, occlusion), `lighting` (the lighting model: see below), `outline` (the
+ *   inverted-hull second draw: see below), `post` (a screen pass over `sceneColour`, with SF59 (2b)'s taps `sceneColourAt`,
+ *   `sceneDepth` and `sceneNormal`, each input one sampler: `inputs` in the validation names those a pass reads); the engine epilogue (fog, the CSM
+ *   cascade gate, the tent PCF, the shadow fade) is appended by the back-end; effectState.fog:false skips fog only, and
+ *   effectState.fog:'<id>' swaps the engine fog for the shard's declared fog graph of that catalogue id (below);
+ * - a `kind: 'fog'` graph is a shard-declared fog (O11): one `stages.fog.colour` (vec3) that runs in the fog epilogue's
+ *   place (`fog`) of every material selecting it, reading `fogInput` (the colour reaching the fog, after the output
+ *   transform), `engineFogged` (the engine fog's result for it), `fogScale` (the material's `vertex.scale.fog`, else 1),
+ *   `positionWorld` and `cameraPosition` (the fog's own frame), its params, textures and the safe maths; it is
+ *   declared once in the look catalogue and costed under its own budget (it adds to each selecting program);
+ * - `outline` (SF59 step 7, the ink outline as a render state the format owns, not a free one): a second draw of the
+ *   same geometry with a fixed render state: back faces only, depth tested and written, opaque, unlit, fogged by the
+ *   epilogue, casting no shadow. `offset` (vec3, the vertex place, model space like `vertex.offset`) pushes the hull out
+ *   (typically along `normalLocal`, scaled by the distance to the camera for a constant screen width) and `colour`
+ *   (vec3, a fragment place without the light inputs) is its ink. It doubles the mesh's draws and vertex work and adds
+ *   no per-pixel lighting, the cheapest true outline on the phone tier (a `sceneDepth` edge filter would cost a depth
+ *   target plus ≈ 9 taps a pixel at 2× over the whole frame);
+ * - `lighting` (SF59 step 6, the approved lighting-model stage; a `standard` material only): `sun` is the radiance the
+ *   sun adds, built per directional light (the sky rig's cascades are one sun) from the engine's light inputs
+ *   (`sunDirection`, `sunColour` unshadowed, `sunShadow` the cast-shadow ratio, with `normalView`, `viewDirection`,
+ *   `albedo`); `ambient` replaces the indirect diffuse (from `irradiance`); `sunSpecular` scales the physical model's own
+ *   specular for the sun (absent: the model is diffuse only, no specular at all); `grade` maps the lit colour
+ *   (`litColour`, emissive included) to the colour the output transform receives (a graded material is not tone mapped).
+ *   Every other light keeps the physical model's diffuse. Same vocabulary, no code nodes, constant loops only, the same
+ *   budget. The `sun` sub-graph runs once per directional light: its light-dependent nodes (those reading `sunDirection`,
+ *   `sunColour` or `sunShadow`, directly or through their inputs) count `cascades` times in the instruction estimate
+ *   (`SUN_CASCADES`, the sky rig's three, by default); its light-free part is built once and shared, so it counts once;
+ * - `params`: typed uniforms with ranges, each optionally bound to a day key or a declared public shard-state field.
+ *   A binding moves a value, never the program (§2.6);
+ * - loops have a constant count (`loop`, at most `LOOP_MAX` iterations), so the cost is known before compile;
+ * - a budget per program (node count, samplers, an instruction estimate) that validation refuses past.
+ *
+ * Pure data and checks: this module imports no three.js, so the shardfile validator can use it on any machine.
+ */
+
+/** A graph identifier matcher retains the original mutable RegExp contract. */
+type GraphIdentifierPattern = RegExp;
+
+/** a fog graph's catalogue id as a material's `effectState.fog` names it (the look catalogue's id pattern) */
+export const GRAPH_FOG_ID: GraphIdentifierPattern = /^[a-z][a-z0-9.-]{0,127}$/u;
+/** the IR version a graph declares; a graph of another version is refused (the lighting stage is additive: still version 1) */
+export const GRAPH_IR_VERSION = 1;
+/** the most iterations a `loop` node may run */
+export const LOOP_MAX = 16;
+/** Maximum elements in one fixed-capacity numeric uniform list. */
+export const GRAPH_ARRAY_MAX = 64;
+/** Total padded vector slots across a graph's uniform lists. */
+export const GRAPH_ARRAY_SLOTS_MAX = 128;
+/** the directional lights a `sun` sub-graph is built for by default: the sky rig's three CSM cascades */
+export const SUN_CASCADES = 3;
+/** the most cascades a validation may count (three's CSM tops out at four here) */
+export const SUN_CASCADES_MAX = 4;
+
+/** a value's type inside a graph */
+export type GraphValueType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'bool';
+/** a literal input: a float or a 2–4 component vector */
+export type GraphLiteral = number | readonly number[];
+/** an input: another node's id, or a literal */
+export type GraphRef = string | GraphLiteral;
+
+/** one node of a graph */
+export interface GraphNode {
+  readonly op: string;
+  readonly in?: readonly GraphRef[];
+  /** `const`: the value */
+  readonly value?: GraphLiteral;
+  /** `param`, `texture`: the param's name */
+  readonly param?: string;
+  /** `swizzle`: the components, e.g. `"xz"` */
+  readonly mask?: string;
+  /** `loop`: the iteration count (a constant, 1 … LOOP_MAX) */
+  readonly count?: number;
+  /** `loop`: the body, run `count` times; inside it `acc` is the running value and `index` the iteration (a float) */
+  readonly body?: GraphLoopBody;
+  /** `attribute`: the geometry attribute's name (`aSeed`: `a`, then a capital; three's own attributes are inputs);
+   *  `meshMap`: `bump` reads its bump map; `colourOrVertex` reads its colour map or the linear vertex colour when no map is bound */
+  readonly name?: string;
+  /** `attribute`: the attribute's type */
+  readonly type?: GraphValueType;
+  /** attribute only: optional numeric default, exactly matching type, used when a mesh omits the channel. */
+  readonly default?: GraphLiteral;
+  /** varying only: use the primitive's provoking vertex instead of interpolating; absent retains ordinary perspective interpolation. */
+  readonly interpolation?: 'flat';
+}
+/** a loop's body: its own nodes (they may read the outer graph's nodes too) and the node that is the next `acc` */
+export interface GraphLoopBody {
+  readonly nodes: Readonly<Record<string, GraphNode>>;
+  readonly out: GraphRef;
+}
+
+/** a param's type; a colour is written in sRGB and arrives linear, a texture names an admitted file */
+export type GraphParamType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'colour' | 'texture';
+/** where a bound param's value comes from: a day-key channel or a declared public numeric shard-state field */
+export type GraphBinding = { readonly day: string } | { readonly state: string };
+/** a typed param: a uniform the graph reads */
+export interface GraphParam {
+  readonly type: GraphParamType;
+  readonly value: GraphLiteral | string;
+  readonly min?: number;
+  readonly max?: number;
+  readonly bind?: GraphBinding;
+  /**
+   * Texture only: data bypasses sRGB conversion; absent retains the colour role. `lent`: no admitted file, a trusted
+   * runtime lends the sampled texture (`setTexture`, swapped without a program change; a 1×1 black stand-in until then)
+   * and `value` only names the slot; a texture it decodes at run time (a baked sky key) is sampled as it is.
+   */
+  readonly role?: 'colour' | 'data' | 'lent';
+}
+
+/** Fixed-capacity numeric uniform list. Each value has the declared element
+ * type; setArrayParam updates values without resizing or changing the program. */
+export interface GraphArrayParam {
+  readonly type: 'float' | 'vec2' | 'vec3' | 'vec4';
+  readonly value: readonly GraphLiteral[];
+}
+/** Absolute post-instance model-space position, replacing the ordinary vertex.
+ * Mutually exclusive with vertex.offset; shadow:true emits matching depth. */
+export interface GraphVertexPosition {
+  readonly position: GraphRef;
+  readonly shadow?: boolean;
+}
+
+/** the surface stage's outputs (each optional; an absent one keeps the lighting model's default) */
+export interface GraphSurface {
+  readonly colour?: GraphRef;
+  readonly alpha?: GraphRef;
+  readonly alphaCutoff?: number;
+  /** float: what an opaque draw writes into the colour target's alpha channel (coverage stays whole, nothing blends), as a
+   *  GLSL program's `gl_FragColor.a` did: a renderer that keeps the inverse view depth there (`cameraNear` over the view
+   *  depth) reads it in its post. Opaque only: never with `alpha` or a blend */
+  readonly targetAlpha?: GraphRef;
+  readonly emissive?: GraphRef;
+  readonly roughness?: GraphRef;
+  readonly metalness?: GraphRef;
+  readonly occlusion?: GraphRef;
+  /** bool: the fragment is discarded where it is true (a dither or a clip; a fragment-place op, like `alphaCutoff`) */
+  readonly discard?: GraphRef;
+  /** vec3: the shading normal in world space (unit; a lit model only), in place of the interpolated one: a per-pixel
+   *  ripple or detail normal the lighting, the environment's reflection and the lighting stage's `normalView` all use */
+  readonly normal?: GraphRef;
+}
+/** the vertex stage: an object-space offset; shadow:true also applies it and the surface mask to shadow depth */
+export interface GraphVertexOffset {
+  readonly offset: GraphRef;
+  readonly shadow?: boolean;
+}
+/**
+ * The lighting-model stage (a `standard` material only): what the sun adds, the ambient term, the sun's share of the
+ * physical specular and the per-pixel grade after lighting (the module comment says what each reads).
+ */
+export interface GraphLighting {
+  /** vec3: the radiance one directional light adds (built per cascade), added to the direct diffuse */
+  readonly sun: GraphRef;
+  /** float: the factor on the physical model's specular from the unshadowed sun (absent: no specular at all) */
+  readonly sunSpecular?: GraphRef;
+  /** vec3: the indirect diffuse radiance, from `irradiance` (absent: irradiance × albedo / π) */
+  readonly ambient?: GraphRef;
+  /** vec3: the lit colour (`litColour`) → the colour the output transform receives; a graded material is not tone mapped */
+  readonly grade?: GraphRef;
+}
+/**
+ * The outline stage: the inverted-hull second draw (back faces, depth tested and written, opaque, unlit, fogged, no
+ * shadow; the module comment says why this one render state and not a free one).
+ */
+export interface GraphOutline {
+  /** vec3: the hull's displacement in model space (the vertex place, as `vertex.offset`) */
+  readonly offset: GraphRef;
+  /** vec3: the ink colour (linear; a fragment place without the light inputs) */
+  readonly colour: GraphRef;
+}
+/** Optional effect render state. Absent fields retain the existing material defaults. */
+export interface GraphEffectState {
+  /** Unlit linear colour: apply the target's colour encoding, without tone mapping. Absent keeps legacy raw output. */
+  readonly output?: 'colour';
+  /** Alpha uses straight RGB; premultiplied expects RGB already multiplied by alpha. */
+  readonly blend?: 'alpha' | 'additive' | 'premultiplied';
+  /** false: bypass the engine fog epilogue for this effect only; a catalogue id: fog with that `kind: 'fog'` graph instead */
+  readonly fog?: false | string;
+  /** Whether fragments update depth; depth testing stays enabled. */
+  readonly depthWrite?: boolean;
+  /** Polygon offset factor and units, each finite and within -16 … 16. */
+  readonly depthBias?: { readonly factor: number; readonly units: number };
+  /** A double-sided effect draws both faces in one pass (unsorted), not three's back-then-front pair of draws. */
+  readonly singlePass?: true;
+}
+/** Typed graph stage outputs, including optional point size, surface, lighting and post colour. */
+export interface GraphStages {
+  /** Points only: diameter in drawing-buffer pixels, clamped to 1 … 2048 and the device's point range. */
+  readonly points?: { readonly size: GraphRef };
+  readonly 'vertex.offset'?: GraphVertexOffset;
+  readonly 'vertex.position'?: GraphVertexPosition;
+  /** Raw homogeneous clip-space position; excludes model-space position/offset outputs. */
+  readonly 'vertex.clip'?: { readonly position: GraphRef };
+  /** Interpolated vertex factors, clamped to 0..1; omitted factors are neutral. */
+  readonly 'vertex.scale'?: { readonly sun?: GraphRef; readonly fog?: GraphRef };
+  /** Object-space vertex normal, replacing the input before lighting interpolation. */
+  readonly 'vertex.normal'?: { readonly normal: GraphRef };
+  /** World-space receiver lookup shift; leaves geometry and caster depth unchanged. Lit meshes only. */
+  readonly 'shadow.offset'?: { readonly offset: GraphRef };
+  readonly surface?: GraphSurface;
+  readonly lighting?: GraphLighting;
+  readonly outline?: GraphOutline;
+  readonly post?: { readonly colour: GraphRef; readonly alpha?: GraphRef };
+  /** a fog graph's only stage: the fogged colour (vec3) from `fogInput` / `engineFogged`; alpha passes through */
+  readonly fog?: { readonly colour: GraphRef; readonly transmission?: GraphRef };
+}
+/** a graph */
+export interface GraphIr {
+  readonly version: typeof GRAPH_IR_VERSION;
+  /** Explicit per-program ceilings. Raising the defaults requires trusted runtime authority. */
+  readonly budget?: GraphBudget;
+  /** a material (vertex.offset + surface), a screen pass (post) or a shard's declared fog (fog, selected by materials) */
+  readonly kind: 'material' | 'post' | 'fog';
+  /** a material's lighting model: three's physical standard model, or unlit */
+  readonly model?: 'standard' | 'unlit' | 'toon';
+  /** Absent: mesh. Points require an unlit graph and a points.size vertex output. */
+  readonly primitive?: 'mesh' | 'points';
+  /** Optional material-only effect state; omission preserves every prior render default. */
+  readonly effectState?: GraphEffectState;
+  /** One named, admitted fog function for post-only fogSample nodes. Functions keep their own node ceiling; calls spend their full instruction cost. */
+  readonly postFog?: { readonly name: string; readonly graph: GraphIr };
+  readonly doubleSided?: boolean;
+  /** false: retain the front-face normal basis on back faces; culling is unchanged. */
+  readonly flipBackfaceNormals?: boolean;
+  /** false: omit underwater caustics for this toon material only. */
+  readonly toonCaustics?: boolean;
+  /** one normal per triangle (the toon family's faceted look): `normalView` is the face's */
+  readonly flatShading?: boolean;
+  readonly params?: Readonly<Record<string, GraphParam>>;
+  /** Numeric uniform arrays: 1–64 elements each, at most 128 padded vector slots in total. */
+  readonly arrays?: Readonly<Record<string, GraphArrayParam>>;
+  readonly nodes: Readonly<Record<string, GraphNode>>;
+  readonly stages: GraphStages;
+}
+
+/** the per-program ceilings validation refuses past */
+export interface GraphBudget {
+  readonly nodes: number;
+  readonly samplers: number;
+  readonly instructions: number;
+}
+/** the default ceilings (a starter graph: the measure preset is ≈ 60 nodes, ≈ 170 instructions) */
+export const DEFAULT_GRAPH_BUDGET: GraphBudget = { nodes: 160, samplers: 4, instructions: 480 };
+/** Hard ceilings for a trusted declaration; loop trips remain charged to the estimated cost. */
+export const MAX_GRAPH_BUDGET: GraphBudget = Object.freeze({ nodes: 4096, samplers: 16, instructions: 8192 });
+
+/** Raw graph JSON bounds, enforced before typing or compiler work; trusted presets supply their own node budget. */
+export const GRAPH_ADMISSION_LIMITS: Readonly<{ bytes: 96000; depth: 64; }> = Object.freeze({ bytes: 96_000, depth: 64 });
+/** whether JSON writes `value` as itself in quotes: printable ASCII with no quote or backslash (a loop, not a regex: Node's
+ *  type stripping rewrote the regex's escaped bracket and broke it) */
+function plainJsonString(value: string): boolean {
+  for (let i = 0; i < value.length; i++) { const c = value.codePointAt(i) ?? 0; if (c < 32 || c > 126 || c === 34 || c === 92) return false; }
+  return true;
+}
+/** Check JSON bytes, all nested nodes and inert structure without invoking authored getters or toJSON methods. */
+export function graphAdmissionErrors(input: unknown, nodeLimit: number = DEFAULT_GRAPH_BUDGET.nodes): string[] {
+  type Entry = { value: unknown; depth: number; nodes: boolean } | { leave: object };
+  const pending: Entry[] = [{ value: input, depth: 0, nodes: false }], active = new Set<object>(), encoder = new TextEncoder();
+  let bytes = 0, nodes = 0;
+  // printable ASCII with no quote or backslash serializes as itself in quotes: its byte count without encoding a copy
+  // (G639: the encode per string was most of each first-lookup graph validation, ~30 ms a Nalati entry frame)
+  // Node keys, ops and references repeat within a graph. Cache only their immutable encoded lengths for this call;
+  // every occurrence still spends its complete byte count, and no result or source survives into another admission.
+  const stringSizes = new Map<string, number>();
+  const stringBytes = (value: string): number => {
+    const known = stringSizes.get(value);
+    if (known !== undefined) return known;
+    const size = value.length > GRAPH_ADMISSION_LIMITS.bytes ? GRAPH_ADMISSION_LIMITS.bytes + 1
+      : plainJsonString(value) ? value.length + 2 : encoder.encode(JSON.stringify(value)).length;
+    stringSizes.set(value, size); return size;
+  };
+  while (pending.length > 0) {
+    const entry = pending.pop(); if (entry === undefined) break;
+    if ('leave' in entry) { active.delete(entry.leave); continue; }
+    const { value, depth } = entry;
+    if (depth > GRAPH_ADMISSION_LIMITS.depth) return ['graph: JSON depth exceeds admission cap'];
+    if (typeof value === 'string') bytes += stringBytes(value);
+    else if (value === null || typeof value === 'boolean') bytes += value === null ? 4 : value ? 4 : 5;
+    else if (typeof value === 'number') {
+      if (!Number.isFinite(value) || Object.is(value, -0)) return ['graph: finite JSON numbers required'];
+      bytes += JSON.stringify(value).length;
+    } else if (typeof value === 'object') {
+      if (active.has(value)) return ['graph: JSON cycle refused'];
+      const prototype: unknown = Object.getPrototypeOf(value), array = Array.isArray(value);
+      if ((array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) || Object.getOwnPropertySymbols(value).length > 0) return ['graph: plain JSON data required'];
+      // Every own string key still participates, including hidden properties.
+      // Read its descriptor only as visited instead of allocating a second
+      // object holding descriptors for the entire container.
+      const keys = Object.getOwnPropertyNames(value);
+      // Array length is bookkeeping, never an entry in its JSON representation.
+      const count = keys.length - Number(array);
+      if (entry.nodes) { nodes += count; if (nodes > nodeLimit) return [`budget: ${nodes} nodes (at most ${nodeLimit}); all nested nodes counted`]; }
+      bytes += 2 + Math.max(0, count - 1);
+      if (array && value.length !== count) return ['graph: sparse JSON arrays refused'];
+      active.add(value); pending.push({ leave: value });
+      for (const key of keys) {
+        if (array && key === 'length') continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || descriptor.get !== undefined || descriptor.set !== undefined || !descriptor.enumerable) return ['graph: JSON accessors and hidden properties refused'];
+        if (!array) bytes += stringBytes(key) + 1;
+        const child: unknown = descriptor.value;
+        pending.push({ value: child, depth: depth + 1, nodes: key === 'nodes' });
+      }
+    } else return ['graph: plain JSON data required'];
+    if (bytes > GRAPH_ADMISSION_LIMITS.bytes) return ['graph: JSON byte size exceeds admission cap'];
+  }
+  return [];
+}
+
+/** what a valid graph costs: counted over every node a stage reaches, a loop's body times its count */
+export interface GraphCost {
+  readonly nodes: number;
+  readonly samplers: number;
+  readonly instructions: number;
+}
+
+/**
+ * where a node may run: `vertex` (the offset stage), `fragment` (surface), `post` (a screen pass), the lighting
+ * stage's three: `sun` (per directional light), `ambient` (the indirect term) and `grade` (after lighting), and the
+ * outline's two: `outlineVertex` (its hull offset) and `outline` (its ink; its own program, so counted apart), and
+ * `fog` (a fog graph's stage, run in the fog epilogue of each material that selects it)
+ */
+type GraphPlace = 'vertex' | 'fragment' | 'post' | 'sun' | 'ambient' | 'grade' | 'outlineVertex' | 'outline' | 'fog';
+
+/** how an op types its inputs */
+type TypeRule =
+  | 'input' | 'const' | 'param' | 'same' | 'unary' | 'vecUnary' | 'length' | 'dot' | 'mix' | 'compare' | 'logic' | 'not'
+  | 'cross' | 'gerstner' | 'select' | 'swizzle' | 'combine' | 'noise' | 'texture' | 'loop' | 'acc' | 'index' | 'point3' | 'pointPair' | 'dir3' | 'sceneTap'
+  | 'fogSample' | 'instanceTransform' | 'windField' | 'varying' | 'attribute' | 'arrayElement' | 'cameraBillboard';
+/** one op of the vocabulary */
+export interface GraphOpSpec {
+  /** the number of inputs (min, max) */
+  readonly arity: readonly [number, number];
+  readonly rule: TypeRule;
+  /** an estimate of the instructions it emits */
+  readonly cost: number;
+  /** an input op's type */
+  readonly type?: GraphValueType;
+  /** the places it may run (all when absent) */
+  readonly places?: readonly GraphPlace[];
+}
+
+/** `viewRay`'s estimate: two multiply-adds of the camera's basis and a normalise */
+const VIEW_RAY_COST = 8;
+/** An input op's arity, both ends */
+const NO_INPUTS = 0;
+/** the lighting stage's places (fragment work, like the surface) */
+const LIT: readonly GraphPlace[] = ['sun', 'ambient', 'grade'];
+const FRAG: readonly GraphPlace[] = ['fragment', 'outline', 'post', ...LIT];
+const MESH: readonly GraphPlace[] = ['vertex', 'outlineVertex', 'fragment', 'outline', ...LIT];
+/** the vertex places (an object's own transform is read there) */
+const VERT: readonly GraphPlace[] = ['vertex', 'outlineVertex'];
+/**
+ * The version 1 vocabulary (the starter set of §4): inputs, constants and params, arithmetic and safe maths, comparisons
+ * and a branch-light `select`, swizzles and vector construction, MaterialX noise, an admitted texture's sample and a
+ * constant-count loop. Nothing here can name a three.js node or carry source.
+ */
+export const GRAPH_OPS: Readonly<Record<string, GraphOpSpec>> = {
+  // inputs
+  windTime: { arity: [0, 0], rule: 'input', cost: 0, type: 'float' },
+  windGust: { arity: [0, 0], rule: 'input', cost: 0, type: 'float' },
+  windDirection: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec2' },
+  windGustAt: { arity: [1, 1], rule: 'windField', cost: 64, places: MESH },
+  frontFacing: { arity: [0, 0], rule: 'input', cost: 0, type: 'bool', places: FRAG },
+  uv: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec2', places: MESH },
+  positionLocal: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: MESH },
+  // SF59 step 7: the geometry's own vertex position, before an instance's transform (the painterly sway's height)
+  positionGeometry: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: VERT },
+  // SF59 step 7: the world position of the object's origin, the instance's own for an instanced mesh (a per-object phase)
+  instanceTransform: { arity: [1, 1], rule: 'instanceTransform', cost: 16, type: 'vec4', places: VERT },
+  objectOrigin: { arity: [0, 0], rule: 'input', cost: 4, type: 'vec3', places: VERT },
+  positionWorld: { arity: [0, 0], rule: 'input', cost: 1, type: 'vec3', places: [...MESH, 'fog'] },
+  // a fog graph's inputs (O11): the colour reaching the fog (after the output transform), the engine fog's result for it,
+  // and the material's fog share (`vertex.scale.fog`, else 1)
+  fogInput: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['fog'] },
+  engineFogged: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['fog'] },
+  fogScale: { arity: [0, 0], rule: 'input', cost: 0, type: 'float', places: ['fog'] },
+  positionView: { arity: [0, 0], rule: 'input', cost: 1, type: 'vec3', places: MESH },
+  normalLocal: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: MESH },
+  normalWorld: { arity: [0, 0], rule: 'input', cost: 1, type: 'vec3', places: MESH },
+  cameraPosition: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3' },
+  // the drawing camera's near plane (m): with the view depth, the inverse depth a renderer keeps in its target's alpha
+  cameraNear: { arity: [0, 0], rule: 'input', cost: 0, type: 'float' },
+  time: { arity: [0, 0], rule: 'input', cost: 0, type: 'float' },
+  // the day's sun as the engine's atmosphere holds it (Atmosphere.ts `fogUniforms`, read by reference like the fog
+  // epilogue): the unit world direction toward the sun and its colour (linear), so an unlit graph shades with the clock
+  // The active material/page colour ramp's live zenith, else the scene fog colour (black if unfogged).
+  fogZenithColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3' },
+  fogColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3' },
+  atmosphereSunDirection: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3' },
+  atmosphereSunColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3' },
+  skyLightDirection: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: MESH },
+  skyLightColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: MESH },
+  instanceHash: { arity: [0, 0], rule: 'input', cost: 4, type: 'float', places: MESH },
+  vertexColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: MESH }, // the geometry's `color` attribute (rgb, linear); white where it has none
+  vertexColourAlpha: { arity: [0, 0], rule: 'input', cost: 0, type: 'float', places: MESH }, // original vertex alpha; 1 for RGB or absent colour
+  // the material's own colour and emissive × intensity (linear): the ports a runtime drives per material (a creature's
+  // per-animal tint, its hit flash), read live like three's own material colour
+  materialColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: FRAG },
+  materialEmissive: { arity: [0, 0], rule: 'input', cost: 1, type: 'vec3', places: FRAG },
+  fogSample: { arity: [5, 5], rule: 'fogSample', cost: 1, type: 'vec4', places: ['post'] },
+  screenUV: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec2', places: ['post'] },
+  // The world-space unit direction from the scene camera through this pixel (LF2-3): a post graph's sky detail (clouds, a
+  // sun glow against `atmosphereSunDirection`) keyed to it holds still in the world as the camera turns, where `screenUV` swims
+  viewRay: { arity: [NO_INPUTS, NO_INPUTS], rule: 'input', cost: VIEW_RAY_COST, type: 'vec3', places: ['post'] },
+  // the pixel's window coordinate in pixels (`gl_FragCoord.xy`, from the top left as three's node back-end gives it): a
+  // screen-space dither or clip on a mesh, never a full-screen pass (that is `screenUV`)
+  pointCoord: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec2', places: ['fragment'] },
+  // Absolute model-space billboard position. Geometry coordinates are world metres; object/instance origins stay fixed.
+  viewBillboard: { arity: [0, 0], rule: 'input', cost: 32, type: 'vec3', places: VERT },
+  // Absolute model-space Y-axis billboard, retaining the model's X/Y scale; subtract positionLocal for vertex.offset.
+  // Model-space position of a camera-relative card. Inputs: world direction,
+  // distance, card-local vec2 (already sized/rotated by graph arithmetic).
+  cameraRelativeBillboard: { arity: [3, 3], rule: 'cameraBillboard', cost: 80, type: 'vec3', places: VERT },
+  cylindricalBillboard: { arity: [0, 0], rule: 'input', cost: 48, type: 'vec3', places: VERT },
+  // World-space lengths of the model matrix's X, Y and Z axes (positive, including parent transforms).
+  modelScale: { arity: [0, 0], rule: 'input', cost: 9, type: 'vec3', places: VERT },
+  // Camera-space forward distance and projected motion; vary the direction into a point fragment.
+  viewDepth: { arity: [1, 1], rule: 'point3', cost: 16, type: 'float', places: VERT },
+  screenDirection: { arity: [2, 2], rule: 'pointPair', cost: 72, type: 'vec2', places: VERT },
+  fragCoord: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec2', places: ['fragment', 'outline'] },
+  // a declared geometry attribute (`name`, `type`): a shard's own per-vertex or per-instance data
+  attribute: { arity: [0, 0], rule: 'attribute', cost: 0, places: MESH },
+  // a value computed per vertex and interpolated to the fragment: its input is typed (and costed) in the vertex place
+  varying: { arity: [1, 1], rule: 'varying', cost: 1, places: ['fragment', 'outline', ...LIT] },
+  // the lighting stage's inputs (SF59 step 6): view space, unit vectors; the engine supplies them from its own lights
+  normalView: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: LIT }, // the shading normal (the face's under flatShading)
+  viewDirection: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: LIT }, // toward the camera
+  albedo: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: LIT }, // the surface colour × (1 − metalness)
+  sunDirection: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['sun'] }, // toward the light
+  sunColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['sun'] }, // the light's colour × intensity, unshadowed
+  sunShadow: { arity: [0, 0], rule: 'input', cost: 4, type: 'float', places: ['sun'] }, // 1 lit … 0 in cast shadow (the families' ratio)
+  irradiance: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['ambient'] }, // the indirect irradiance (hemisphere, ambient)
+  // the environment's own light at the shading point, beside `irradiance`: its prefiltered radiance along the reflected view
+  // ray at the surface's roughness, and its irradiance (× π, as three keeps it) for the shading normal. Reading either
+  // makes `ambient` own the whole indirect term: the physical model adds no environment diffuse or specular of its own
+  radiance: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['ambient'] },
+  environmentIrradiance: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['ambient'] },
+  // Diffuse PMREM at a normalized world direction (same intensity and × π as environmentIrradiance).
+  environmentIrradianceAt: { arity: [1, 1], rule: 'dir3', cost: 32, places: ['ambient'] },
+  litColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: ['grade'] }, // the lit colour, emissive included
+  sceneColour: { arity: [0, 0], rule: 'input', cost: 2, type: 'vec4', places: ['post'] },
+  // SF59 (2b), the post inputs, each its own sampler once a graph reads it (however many taps): the scene colour at a uv
+  // (`sceneColourAt`, a tap: an edge or blur kernel), the scene depth (linear view distance in metres, from the engine's
+  // depth target) and the scene normal (view space, unit, from the normal pre-pass the engine draws only for a post stack
+  // that reads it: `postInputs` names it so the stack's cost carries it). Each samples at `screenUV` without an input.
+  sceneColourAt: { arity: [1, 1], rule: 'sceneTap', cost: 4, type: 'vec4', places: ['post'] },
+  sceneDepth: { arity: [0, 1], rule: 'sceneTap', cost: 6, type: 'float', places: ['post'] },
+  sceneNormal: { arity: [0, 1], rule: 'sceneTap', cost: 6, type: 'vec3', places: ['post'] },
+  const: { arity: [0, 0], rule: 'const', cost: 0 },
+  param: { arity: [0, 0], rule: 'param', cost: 0 },
+  // Float index is floored and clamped to the declared fixed-capacity list.
+  arrayElement: { arity: [1, 1], rule: 'arrayElement', cost: 4 },
+  // Fixed CPU ocean coefficients: rest XZ, seconds, damping.
+  gerstnerNormal: { arity: [3, 3], rule: 'gerstner', cost: 200, type: 'vec3' },
+  gerstner: { arity: [3, 3], rule: 'gerstner', cost: 120, type: 'vec3' },
+  // arithmetic (a float broadcasts to a vector)
+  add: { arity: [2, 2], rule: 'same', cost: 1 },
+  sub: { arity: [2, 2], rule: 'same', cost: 1 },
+  mul: { arity: [2, 2], rule: 'same', cost: 1 },
+  div: { arity: [2, 2], rule: 'same', cost: 2 }, // safe: a non-literal divisor is kept off zero
+  min: { arity: [2, 2], rule: 'same', cost: 1 },
+  max: { arity: [2, 2], rule: 'same', cost: 1 },
+  mod: { arity: [2, 2], rule: 'same', cost: 3 }, // a − b·floor(a / b)
+  pow: { arity: [2, 2], rule: 'same', cost: 4 }, // safe: the base is clamped at 0
+  step: { arity: [2, 2], rule: 'same', cost: 1 },
+  abs: { arity: [1, 1], rule: 'unary', cost: 1 },
+  floor: { arity: [1, 1], rule: 'unary', cost: 1 },
+  // Quantize numeric post values with native half packing; render-target store rounding may differ.
+  float16: { arity: [1, 1], rule: 'unary', cost: 4, places: ['post'] },
+  fract: { arity: [1, 1], rule: 'unary', cost: 1 },
+  sin: { arity: [1, 1], rule: 'unary', cost: 4 },
+  cos: { arity: [1, 1], rule: 'unary', cost: 4 },
+  exp: { arity: [1, 1], rule: 'unary', cost: 4 }, // e^x (the emissive family's halo falloff)
+  atan: { arity: [2, 2], rule: 'same', cost: 8 }, // atan(y, x): the angle of (x, y), −π … π (GLSL's two-argument atan)
+  negate: { arity: [1, 1], rule: 'unary', cost: 1 },
+  oneMinus: { arity: [1, 1], rule: 'unary', cost: 1 },
+  saturate: { arity: [1, 1], rule: 'unary', cost: 1 },
+  // Screen derivatives are fragment-only, including lighting/post stages.
+  dFdx: { arity: [1, 1], rule: 'unary', cost: 1, places: FRAG },
+  dFdy: { arity: [1, 1], rule: 'unary', cost: 1, places: FRAG },
+  cross: { arity: [2, 2], rule: 'cross', cost: 3 },
+  fwidth: { arity: [1, 1], rule: 'unary', cost: 3, places: FRAG },
+  normalize: { arity: [1, 1], rule: 'vecUnary', cost: 3 },
+  // SF59 step 7: space changes for a vec3 direction. `viewToWorld` turns a view-space direction (`normalView`, faceted
+  // under flatShading) into a unit world one; `worldToLocal` turns a world direction into the model space
+  // `vertex.offset` is added in (the transpose of the model's 3 × 3 world matrix, unnormalised, as the families do it)
+  viewToWorld: { arity: [1, 1], rule: 'dir3', cost: 6, places: MESH },
+  // Full local direction through object and instance scale/rotation (no translation).
+  // A custom local direction through the mesh's current skeleton; rigid draws retain it.
+  skinDirection: { arity: [1, 1], rule: 'dir3', cost: 64, places: VERT },
+  localToWorldVector: { arity: [1, 1], rule: 'dir3', cost: 8, places: VERT },
+  // The renderer's instance tint, or white for an ordinary/uncoloured instance.
+  instanceOrigin: { arity: [0, 0], rule: 'input', cost: 4, type: 'vec3', places: VERT },
+  instanceColour: { arity: [0, 0], rule: 'input', cost: 0, type: 'vec3', places: VERT },
+  worldToLocal: { arity: [1, 1], rule: 'dir3', cost: 3, places: VERT },
+  length: { arity: [1, 1], rule: 'length', cost: 3 },
+  dot: { arity: [2, 2], rule: 'dot', cost: 2 },
+  mix: { arity: [3, 3], rule: 'mix', cost: 2 },
+  clamp: { arity: [3, 3], rule: 'same', cost: 2 },
+  smoothstep: { arity: [3, 3], rule: 'same', cost: 5 },
+  // comparisons and the branch-light select
+  lt: { arity: [2, 2], rule: 'compare', cost: 1 },
+  lte: { arity: [2, 2], rule: 'compare', cost: 1 },
+  gt: { arity: [2, 2], rule: 'compare', cost: 1 },
+  gte: { arity: [2, 2], rule: 'compare', cost: 1 },
+  eq: { arity: [2, 2], rule: 'compare', cost: 1 },
+  and: { arity: [2, 2], rule: 'logic', cost: 1 },
+  or: { arity: [2, 2], rule: 'logic', cost: 1 },
+  not: { arity: [1, 1], rule: 'not', cost: 1 },
+  select: { arity: [3, 3], rule: 'select', cost: 2 },
+  // vectors
+  swizzle: { arity: [1, 1], rule: 'swizzle', cost: 0 },
+  combine: { arity: [2, 4], rule: 'combine', cost: 0 },
+  // MaterialX noise and textures
+  noise: { arity: [1, 1], rule: 'noise', cost: 40 },
+  meshMap: { arity: [0, 0], rule: 'input', cost: 4, type: 'vec4', places: ['fragment'] },
+  texture: { arity: [1, 1], rule: 'texture', cost: 4 },
+  textureArray: { arity: [2, 2], rule: 'texture', cost: 6 },
+  // Explicit mip and screen gradients keep painted panoramas continuous at a wrap.
+  // Trilinear volume read; a lent Data3DTexture, coordinates in [0,1].
+  texture3D: { arity: [1, 1], rule: 'texture', cost: 4, places: [...MESH, 'post'] },
+  textureLod: { arity: [2, 2], rule: 'texture', cost: 4, places: MESH },
+  textureGrad: { arity: [3, 3], rule: 'texture', cost: 4, places: FRAG },
+  // the constant-count loop
+  loop: { arity: [1, 1], rule: 'loop', cost: 1 },
+  acc: { arity: [0, 0], rule: 'acc', cost: 0 },
+  index: { arity: [0, 0], rule: 'index', cost: 0 },
+};
+
+/** the ops whose value is one directional light's (a node reading one is built per light, and counted per cascade) */
+export const SUN_OPS: ReadonlySet<string> = new Set(['sunDirection', 'sunColour', 'sunShadow']);
+
+/**
+ * the scene inputs a post graph reads (SF59 (2b)): each is one sampler in its cost; `normal` also needs the engine's
+ * normal pre-pass, which a post stack pays once (`POST_NORMAL_PREPASS_COST`) whichever of its passes read it
+ */
+export interface PostInputs { readonly colour: boolean; readonly depth: boolean; readonly normal: boolean }
+/** the outcome of validation: the graph (typed) and its cost, or every reason it is refused */
+export type GraphValidation =
+  | { readonly ok: true; readonly graph: GraphIr; readonly cost: GraphCost; readonly types: ReadonlyMap<string, GraphValueType>; readonly inputs: PostInputs }
+  | { readonly ok: false; readonly errors: readonly string[] };
+
+/** what validation checks bindings and the budget against */
+export interface GraphValidationOptions {
+  /** the day-key channels a param may bind to (any name when absent) */
+  readonly dayKeys?: readonly string[];
+  /** the shard's declared public numeric state fields a param may bind to (any name when absent) */
+  readonly stateFields?: readonly string[];
+  readonly budget?: GraphBudget;
+  /** Host authority to use an explicit declaration; content cannot grant this. */
+  readonly trustedBudget?: boolean;
+  /** the directional lights a `sun` sub-graph is built for (1 … SUN_CASCADES_MAX; SUN_CASCADES when absent) */
+  readonly cascades?: number;
+}
+
+const VEC_LEN: Readonly<Record<GraphValueType, number>> = { float: 1, vec2: 2, vec3: 3, vec4: 4, bool: 1 };
+const vecOf = (n: number): GraphValueType | null => (n === 1 ? 'float' : n === 2 ? 'vec2' : n === 3 ? 'vec3' : n === 4 ? 'vec4' : null);
+const isNumeric = (t: GraphValueType): boolean => t !== 'bool';
+const ID = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const SURFACE_TYPES: Readonly<Record<string, GraphValueType>> = { colour: 'vec3', alpha: 'float', targetAlpha: 'float', emissive: 'vec3', roughness: 'float', metalness: 'float', occlusion: 'float', discard: 'bool', normal: 'vec3' };
+/** an `attribute` node's name: `a` and a capital (`aSeed`), so it never names one of three's own attributes */
+export const GRAPH_ATTRIBUTE_NAME: GraphIdentifierPattern = /^a[A-Z][A-Za-z0-9]{0,31}$/;
+/** where a `varying`'s input runs: the vertex program of the place reading it */
+const VARYING_SOURCE: Readonly<Partial<Record<GraphPlace, GraphPlace>>> = { fragment: 'vertex', sun: 'vertex', ambient: 'vertex', grade: 'vertex', outline: 'outlineVertex' };
+
+/** an object read from content, with the fields this module looks at named (each still unknown) */
+interface Raw {
+  readonly interpolation?: unknown;
+  readonly [k: string]: unknown;
+  readonly version?: unknown; readonly kind?: unknown; readonly model?: unknown; readonly doubleSided?: unknown; readonly flipBackfaceNormals?: unknown; readonly toonCaustics?: unknown; readonly flatShading?: unknown;
+  readonly primitive?: unknown; readonly effectState?: unknown; readonly blend?: unknown; readonly fog?: unknown; readonly output?: unknown;
+  readonly depthWrite?: unknown; readonly singlePass?: unknown; readonly depthBias?: unknown; readonly factor?: unknown; readonly units?: unknown; readonly size?: unknown; readonly points?: unknown;
+  readonly budget?: unknown; readonly arrays?: unknown; readonly params?: unknown; readonly nodes?: unknown; readonly stages?: unknown;
+  readonly type?: unknown; readonly value?: unknown; readonly min?: unknown; readonly max?: unknown; readonly bind?: unknown; readonly role?: unknown;
+  readonly day?: unknown; readonly state?: unknown;
+  readonly op?: unknown; readonly in?: unknown; readonly param?: unknown; readonly mask?: unknown; readonly count?: unknown;
+  readonly body?: unknown; readonly out?: unknown; readonly name?: unknown; readonly discard?: unknown;
+  readonly position?: unknown; readonly offset?: unknown; readonly shadow?: unknown; readonly surface?: unknown; readonly post?: unknown;
+  readonly lighting?: unknown; readonly colour?: unknown; readonly outline?: unknown;
+  readonly sun?: unknown; readonly sunSpecular?: unknown; readonly ambient?: unknown; readonly grade?: unknown;
+}
+const isRecord = (v: unknown): v is Raw => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isFiniteNumber = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+function literalType(v: unknown): GraphValueType | null {
+  if (isFiniteNumber(v)) return 'float';
+  if (Array.isArray(v) && v.length >= 2 && v.length <= 4 && v.every(isFiniteNumber)) return vecOf(v.length);
+  return null;
+}
+/** the common type of numeric inputs where a float broadcasts, or null when two vectors differ */
+function broadcast(types: readonly GraphValueType[]): GraphValueType | null {
+  let out: GraphValueType = 'float';
+  for (const t of types) {
+    if (!isNumeric(t)) return null;
+    if (t === 'float') continue;
+    if (out !== 'float' && out !== t) return null;
+    out = t;
+  }
+  return out;
+}
+
+/** one scope of nodes: the graph's own, or a loop body's (which reads its parent's) */
+interface Scope {
+  readonly nodes: Readonly<Record<string, unknown>>;
+  readonly parent: Scope | null;
+  readonly loop: { readonly acc: GraphValueType; readonly accDep: boolean } | null;
+  readonly path: string;
+}
+
+/**
+ * Validate a graph read from content (`unknown`): its shape, every op against the vocabulary, every input's type, no
+ * cycles, params and bindings, stage placement, and the budget. A valid graph comes back typed with its cost; otherwise
+ * every reason it is refused.
+ */
+export function validateGraph(input: unknown, opts: GraphValidationOptions = {}): GraphValidation {
+  const rawErrors = graphAdmissionErrors(input, opts.trustedBudget === true ? MAX_GRAPH_BUDGET.nodes : opts.budget?.nodes ?? DEFAULT_GRAPH_BUDGET.nodes);
+  if (rawErrors.length > 0) return { ok: false, errors: rawErrors };
+  const errors: string[] = [];
+  const fail = (msg: string): null => { errors.push(msg); return null; };
+  let budget = opts.budget ?? DEFAULT_GRAPH_BUDGET;
+  const cascades = opts.cascades ?? SUN_CASCADES;
+  if (!Number.isInteger(cascades) || cascades < 1 || cascades > SUN_CASCADES_MAX) return { ok: false, errors: [`graph: cascades ${cascades} (1–${SUN_CASCADES_MAX})`] };
+  if (!isRecord(input)) return { ok: false, errors: ['graph: not an object'] };
+  if (input.budget !== undefined) {
+    const declared = input.budget;
+    if (!isRecord(declared) || Object.keys(declared).some(key => !['nodes', 'samplers', 'instructions'].includes(key))) return { ok: false, errors: ['graph: budget requires only nodes, samplers and instructions'] };
+    for (const key of ['nodes', 'samplers', 'instructions'] as const) {
+      const value = declared[key];
+      if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > MAX_GRAPH_BUDGET[key]) return { ok: false, errors: [`graph: declared budget ${key} must be 1–${MAX_GRAPH_BUDGET[key]}`] };
+    }
+    if (opts.trustedBudget !== true) return { ok: false, errors: ['graph: declared budget requires trusted runtime authority'] };
+    budget = { nodes: Number(declared.nodes), samplers: Number(declared['samplers']), instructions: Number(declared['instructions']) };
+  }
+  if (input.version !== GRAPH_IR_VERSION) fail(`graph: version ${String(input.version)} (this engine reads ${GRAPH_IR_VERSION})`);
+  const kind = input.kind, primitive = input.primitive;
+  if (kind !== 'material' && kind !== 'post' && kind !== 'fog') fail(`graph: kind ${String(kind)} (material, post or fog)`);
+  if (kind === 'fog') for (const k of ['model', 'primitive', 'effectState', 'doubleSided', 'flipBackfaceNormals', 'toonCaustics', 'flatShading'] as const) if (input[k] !== undefined) fail(`graph: a fog graph has no ${k}`);
+  let postFog: GraphIr['postFog'], postFogCost: GraphCost | undefined;
+  const dependency = input['postFog'];
+  if (dependency !== undefined) {
+    if (kind !== 'post') fail('graph: postFog belongs to a post graph only');
+    else if (!isRecord(dependency) || Object.keys(dependency).some(key => key !== 'name' && key !== 'graph')
+      || typeof dependency.name !== 'string' || !GRAPH_FOG_ID.test(dependency.name)
+      || !isRecord(dependency['graph']) || dependency['graph'].kind !== 'fog') fail('graph: postFog needs a named fog graph');
+    else {
+      const checked = validateGraph(dependency['graph'], opts);
+      if (!checked.ok) for (const error of checked.errors) fail(`postFog: ${error}`);
+      else if (checked.graph.stages.fog?.transmission === undefined) fail('postFog: explicit transmission is required');
+      else {
+        postFog = { name: dependency.name, graph: checked.graph }; postFogCost = checked.cost;
+        const own = new Set([...Object.keys(isRecord(input.params) ? input.params : {}), ...Object.keys(isRecord(input.arrays) ? input.arrays : {})]);
+        for (const name of [...Object.keys(checked.graph.params ?? {}), ...Object.keys(checked.graph.arrays ?? {})]) if (own.has(name)) fail(`postFog: duplicate parameter ${name}`);
+      }
+    }
+  }
+  if (input.model !== undefined && input.model !== 'standard' && input.model !== 'unlit' && input.model !== 'toon') fail(`graph: model ${JSON.stringify(input.model)} (standard, unlit or toon)`);
+  if (input.model === 'toon' && input.kind !== 'material') fail('graph: toon is a material lighting model');
+  if (input.doubleSided !== undefined && typeof input.doubleSided !== 'boolean') fail('graph: doubleSided is not a boolean');
+  if (input.flipBackfaceNormals !== undefined && typeof input.flipBackfaceNormals !== 'boolean') fail('graph: flipBackfaceNormals is not a boolean');
+  if (input.flipBackfaceNormals !== undefined && (kind !== 'material' || primitive === 'points')) fail('graph: flipBackfaceNormals requires a mesh material');
+  if (input.toonCaustics !== undefined && typeof input.toonCaustics !== 'boolean') fail('graph: toonCaustics is not a boolean');
+  if (input.toonCaustics !== undefined && input.model !== 'toon') fail('graph: toonCaustics requires the toon model');
+  if (input.flatShading !== undefined && typeof input.flatShading !== 'boolean') fail('graph: flatShading is not a boolean');
+  for (const k of Object.keys(input)) if (!['version', 'kind', 'model', 'primitive', 'effectState', 'doubleSided', 'flipBackfaceNormals', 'toonCaustics', 'flatShading', 'budget', 'params', 'arrays', 'nodes', 'stages', 'postFog'].includes(k)) fail(`graph: unknown field ${k}`);
+
+  if (input.primitive !== undefined && input.primitive !== 'mesh' && input.primitive !== 'points') fail('graph: primitive must be mesh or points');
+  if (kind === 'post' && (input.primitive !== undefined || input.effectState !== undefined)) fail('graph: post graphs have no effect state or primitive');
+  const effect = input.effectState;
+  if (effect !== undefined) {
+    if (!isRecord(effect)) fail('graph: effectState is not an object');
+    else {
+      for (const k of Object.keys(effect)) if (!['blend', 'fog', 'depthWrite', 'depthBias', 'singlePass', 'output'].includes(k)) fail(`effectState: unknown field ${k}`);
+      if (effect.output !== undefined && (effect.output !== 'colour' || kind !== 'material' || input.model !== 'unlit' || primitive === 'points' || effect.blend !== undefined || effect.depthWrite === false)) fail('effectState: colour output requires an opaque depth-writing unlit mesh');
+      if (effect.blend !== undefined && effect.blend !== 'alpha' && effect.blend !== 'additive' && effect.blend !== 'premultiplied') fail('effectState: unsupported blend');
+      if (effect.fog !== undefined && effect.fog !== false && !(typeof effect.fog === 'string' && GRAPH_FOG_ID.test(effect.fog))) fail('effectState: fog must be false or a fog graph\'s catalogue id');
+      if (effect.depthWrite !== undefined && typeof effect.depthWrite !== 'boolean') fail('effectState: depthWrite must be boolean');
+      if (effect.singlePass !== undefined && effect.singlePass !== true) fail('effectState: singlePass must be true');
+      const bias = effect.depthBias;
+      if (bias !== undefined) {
+        if (!isRecord(bias)) fail('effectState: depthBias is not an object');
+        else {
+          for (const k of Object.keys(bias)) if (k !== 'factor' && k !== 'units') fail(`effectState.depthBias: unknown field ${k}`);
+          for (const k of ['factor', 'units']) if (!isFiniteNumber(bias[k]) || Math.abs(bias[k]) > 16) fail(`effectState.depthBias.${k}: needs a finite number within -16 … 16`);
+        }
+      }
+    }
+  }
+
+  const arrayTypes = new Map<string, GraphArrayParam['type']>();
+  const rawArrays = input.arrays ?? {};
+  let arraySlots = 0;
+  if (!isRecord(rawArrays)) fail('graph: arrays is not an object');
+  else for (const [name, row] of Object.entries(rawArrays)) {
+    const at = `arrays.${name}`;
+    if (!ID.test(name) || !isRecord(row)) { fail(`${at}: a named uniform list is required`); continue; }
+    for (const key of Object.keys(row)) if (key !== 'type' && key !== 'value') fail(`${at}: unknown field ${key}`);
+    const type = row.type;
+    if (type !== 'float' && type !== 'vec2' && type !== 'vec3' && type !== 'vec4') { fail(`${at}: numeric element type required`); continue; }
+    const values = row.value;
+    if (!Array.isArray(values) || values.length === 0 || values.length > GRAPH_ARRAY_MAX) fail(`${at}: needs 1–${GRAPH_ARRAY_MAX} elements`);
+    else {
+      arraySlots += values.length;
+      if (values.some(value => literalType(value) !== type)) fail(`${at}: every element must be a ${type}`);
+    }
+    arrayTypes.set(name, type);
+  }
+  arraySlots += Object.values(postFog?.graph.arrays ?? {}).reduce((sum, row) => sum + row.value.length, 0);
+  if (arraySlots > GRAPH_ARRAY_SLOTS_MAX) fail(`arrays: exceeds ${GRAPH_ARRAY_SLOTS_MAX} padded vector slots`);
+
+  // params
+  const paramTypes = new Map<string, GraphParamType>();
+  const rawParams = input.params ?? {};
+  if (!isRecord(rawParams)) fail('graph: params is not an object');
+  else for (const [name, p] of Object.entries(rawParams)) {
+    const at = `params.${name}`;
+    if (!ID.test(name)) { fail(`${at}: not an identifier`); continue; }
+    if (!isRecord(p)) { fail(`${at}: not an object`); continue; }
+    const type = p.type;
+    if (type !== 'float' && type !== 'vec2' && type !== 'vec3' && type !== 'vec4' && type !== 'colour' && type !== 'texture') { fail(`${at}: type ${String(type)}`); continue; }
+    if (p.role !== undefined && (type !== 'texture' || (p.role !== 'colour' && p.role !== 'data' && p.role !== 'lent'))) fail(`${at}: role is colour, data or lent on a texture only`);
+    if (type === 'texture') {
+      if (typeof p.value !== 'string' || p.value.length === 0) fail(`${at}: a texture names an admitted file`);
+      if (p.bind !== undefined) fail(`${at}: a texture cannot be bound (a binding moves a uniform value)`);
+    } else {
+      const lt = literalType(p.value), want = type === 'colour' ? 'vec3' : type;
+      if (lt !== want) fail(`${at}: value is not a ${want}`);
+      for (const bound of ['min', 'max'] as const) if (p[bound] !== undefined && !isFiniteNumber(p[bound])) fail(`${at}: ${bound} is not a number`);
+      const vals = isFiniteNumber(p.value) ? [p.value] : Array.isArray(p.value) ? p.value.filter(isFiniteNumber) : [];
+      const lo = p.min, hi = p.max;
+      if (isFiniteNumber(lo) && vals.some((v) => v < lo)) fail(`${at}: value below min`);
+      if (isFiniteNumber(hi) && vals.some((v) => v > hi)) fail(`${at}: value above max`);
+      if (p.bind !== undefined) {
+        const b = p.bind;
+        if (!isRecord(b) || Object.keys(b).length !== 1) fail(`${at}: bind is { day } or { state }`);
+        else if (typeof b.day === 'string') { if (opts.dayKeys && !opts.dayKeys.includes(b.day)) fail(`${at}: unknown day key ${b.day}`); }
+        else if (typeof b.state === 'string') { if (opts.stateFields && !opts.stateFields.includes(b.state)) fail(`${at}: undeclared state field ${b.state}`); }
+        else fail(`${at}: bind is { day } or { state }`);
+      }
+    }
+    paramTypes.set(name, type);
+  }
+
+  if (!isRecord(input.nodes)) return { ok: false, errors: [...errors, 'graph: nodes is not an object'] };
+  const root: Scope = { nodes: input.nodes, parent: null, loop: null, path: 'nodes' };
+  const types = new Map<string, GraphValueType>(); // `<scope path>/<id>` → type
+  const visiting = new Set<string>();
+  const textures = new Set<string>();
+  const textureDimensions = new Map<string, '2d' | 'array' | '3d'>();
+  const sampled = { scene: false, depth: false, normal: false, mesh: false }; // set while typing (a post graph reads a scene input)
+  const counted = new Set<string>();
+  /** `<scope path>/<id>` → whether the node reads a sun input (directly, through its inputs or a loop body) */
+  const lightDep = new Map<string, boolean>();
+  let loopDep = false; // set by the loop rule for the loop node being typed
+  let nodeCount = 0, instructions = 0;
+
+  const find = (scope: Scope, id: string): { scope: Scope; node: unknown } | null => {
+    for (let s: Scope | null = scope; s !== null; s = s.parent) if (Object.hasOwn(s.nodes, id)) return { scope: s, node: s.nodes[id] };
+    return null;
+  };
+
+  /** type a reference from `scope`, at `place`, adding its cost once (times `mult` inside loops) */
+  /** whether a typed reference reads a sun input */
+  const refDep = (ref: unknown, scope: Scope): boolean => {
+    if (typeof ref !== 'string') return false;
+    const hit = find(scope, ref);
+    return hit !== null && lightDep.get(`${hit.scope.path}/${ref}`) === true;
+  };
+
+  function typeRef(ref: unknown, scope: Scope, place: GraphPlace, at: string, mult: number): GraphValueType | null {
+    if (typeof ref !== 'string') return literalType(ref) ?? fail(`${at}: not a node id or a 1–4 number literal`);
+    const hit = find(scope, ref);
+    if (hit === null) return fail(`${at}: unknown node ${ref}`);
+    return typeNode(ref, hit.node, hit.scope, place, mult);
+  }
+
+  function typeNode(id: string, raw: unknown, scope: Scope, place: GraphPlace, mult: number): GraphValueType | null {
+    const key = `${scope.path}/${id}`, at = `${scope.path}.${id}`;
+    const known = types.get(key);
+    if (known !== undefined && counted.has(`${key}@${place}`)) return known;
+    if (visiting.has(key)) return fail(`${at}: cycle`);
+    if (!isRecord(raw)) return fail(`${at}: not an object`);
+    const op = raw.op;
+    if (typeof op !== 'string' || !Object.hasOwn(GRAPH_OPS, op)) return fail(`${at}: unknown op ${String(op)}`);
+    const spec = GRAPH_OPS[op];
+    if (spec === undefined) return fail(`${at}: unknown op ${op}`);
+    if (raw['default'] !== undefined && op !== 'attribute') return fail(`${at}: default belongs to an attribute only`);
+    if (raw.interpolation !== undefined && (op !== 'varying' || raw.interpolation !== 'flat')) return fail(`${at}: interpolation is flat on a varying only`);
+    if (spec.places && !spec.places.includes(place)) return fail(`${at}: ${op} cannot run in the ${place} stage`);
+    if (op === 'pointCoord' && primitive !== 'points') return fail(`${at}: pointCoord needs a points primitive`);
+    const ins = raw.in ?? [];
+    if (!Array.isArray(ins)) return fail(`${at}: in is not a list`);
+    if (ins.length < spec.arity[0] || ins.length > spec.arity[1]) return fail(`${at}: ${op} takes ${spec.arity[0] === spec.arity[1] ? spec.arity[0] : spec.arity.join('–')} inputs, got ${ins.length}`);
+    visiting.add(key);
+    const inputPlace = spec.rule === 'varying' ? VARYING_SOURCE[place] ?? place : place;
+    const inner = spec.rule === 'loop' ? [] : ins.map((r, i) => typeRef(r, scope, inputPlace, `${at}.in[${i}]`, mult));
+    const t = inner.some((x) => x === null) ? null : resolve(op, spec, raw, inner.filter((x): x is GraphValueType => x !== null), scope, place, at, ins, mult);
+    visiting.delete(key);
+    if (t !== null) {
+      types.set(key, t);
+      const dep = spec.rule === 'input' ? SUN_OPS.has(op)
+        : spec.rule === 'acc' ? scope.loop?.accDep === true
+          : spec.rule === 'loop' ? loopDep
+            : ins.some((r) => refDep(r, scope));
+      lightDep.set(key, dep);
+      if (!counted.has(`${key}@${place}`)) {
+        counted.add(`${key}@${place}`);
+        nodeCount += mult;
+        // a component-wise op costs once per component; a light-dependent node of the sun sub-graph once per cascade
+        const lanes = spec.rule === 'same' || spec.rule === 'unary' ? VEC_LEN[t] : 1;
+        instructions += (spec.cost + (op === 'fogSample' ? postFogCost?.instructions ?? 0 : 0)) * mult * lanes * (place === 'sun' && dep ? cascades : 1);
+      }
+    }
+    return t;
+  }
+
+  function resolve(op: string, spec: GraphOpSpec, raw: Raw, ins: readonly GraphValueType[], scope: Scope, place: GraphPlace, at: string, rawIns: readonly unknown[], mult: number): GraphValueType | null {
+    switch (spec.rule) {
+      case 'fogSample':
+        if (postFog === undefined || raw.name !== postFog.name) return fail(`${at}: fogSample needs its declared postFog name`);
+        return ins.length === 5 && ins.slice(0, 4).every(type => type === 'vec3') && ins[4] === 'float' ? 'vec4' : fail(`${at}: fogSample takes four vec3 values and a float`);
+      case 'input':
+        if (op === 'sceneColour') sampled.scene = true;
+        if (op === 'meshMap') {
+          if (kind !== 'material' || primitive === 'points') return fail(`${at}: meshMap requires a mesh material`);
+          if (raw.name !== undefined && raw.name !== 'bump' && raw.name !== 'colourOrVertex') return fail(`${at}: meshMap name ${JSON.stringify(raw.name)} (bump, colourOrVertex or none)`);
+          sampled.mesh = true;
+        }
+        return spec.type ?? null;
+      case 'const': return literalType(raw.value) ?? fail(`${at}: const value is not a 1–4 number literal`);
+      case 'param': {
+        const name = raw.param;
+        if (typeof name !== 'string') return fail(`${at}: param names a param`);
+        const pt = paramTypes.get(name);
+        if (pt === undefined) return fail(`${at}: unknown param ${name}`);
+        if (pt === 'texture') return fail(`${at}: a texture param is read by a texture node`);
+        return pt === 'colour' ? 'vec3' : pt;
+      }
+      case 'arrayElement': {
+        const type = typeof raw.param === 'string' ? arrayTypes.get(raw.param) : undefined;
+        if (type === undefined) return fail(`${at}: arrayElement names a numeric uniform list`);
+        return ins[0] === 'float' ? type : fail(`${at}: arrayElement index must be a float`);
+      }
+      case 'same': return broadcast(ins) ?? fail(`${at}: ${op} inputs ${ins.join(', ')} do not match`);
+      case 'unary': return isNumeric(ins[0] ?? 'bool') ? (ins[0] ?? null) : fail(`${at}: ${op} takes a number`);
+      case 'vecUnary': return ins[0] !== undefined && VEC_LEN[ins[0]] > 1 && isNumeric(ins[0]) ? ins[0] : fail(`${at}: ${op} takes a vector`);
+      case 'length': return ins[0] !== undefined && isNumeric(ins[0]) ? 'float' : fail(`${at}: length takes a number`);
+      case 'cross': return ins[0] === 'vec3' && ins[1] === 'vec3' ? 'vec3' : fail(`${at}: cross takes two vec3 values`);
+      case 'windField': return ins[0] === 'vec2' ? 'float' : fail(`${at}: windGustAt takes world xz (vec2)`);
+      case 'instanceTransform': return ins[0] === 'vec4' ? 'vec4' : fail(`${at}: instanceTransform takes a vec4`);
+      case 'gerstner': return ins[0] === 'vec2' && ins[1] === 'float' && ins[2] === 'float' ? 'vec3' : fail(`${at}: gerstner takes vec2, float, float`);
+      case 'dot': return ins[0] !== undefined && ins[0] === ins[1] && VEC_LEN[ins[0]] > 1 && isNumeric(ins[0]) ? 'float' : fail(`${at}: dot takes two vectors of one size`);
+      case 'mix': {
+        const t = broadcast([ins[0] ?? 'bool', ins[1] ?? 'bool']);
+        if (t === null) return fail(`${at}: mix inputs ${ins.join(', ')} do not match`);
+        return ins[2] === 'float' || ins[2] === t ? t : fail(`${at}: mix factor is ${String(ins[2])}`);
+      }
+      case 'compare': return ins[0] === 'float' && ins[1] === 'float' ? 'bool' : fail(`${at}: ${op} compares two floats`);
+      case 'logic': return ins[0] === 'bool' && ins[1] === 'bool' ? 'bool' : fail(`${at}: ${op} takes two bools`);
+      case 'not': return ins[0] === 'bool' ? 'bool' : fail(`${at}: not takes a bool`);
+      case 'select': {
+        if (ins[0] !== 'bool') return fail(`${at}: select's condition is ${String(ins[0])}, not a bool`);
+        if (ins[1] === 'bool' && ins[2] === 'bool') return 'bool';
+        return broadcast([ins[1] ?? 'bool', ins[2] ?? 'bool']) ?? fail(`${at}: select sides ${String(ins[1])}, ${String(ins[2])} do not match`);
+      }
+      case 'swizzle': {
+        const mask = raw.mask, src = ins[0];
+        if (src === undefined || !isNumeric(src)) return fail(`${at}: swizzle takes a number`);
+        if (typeof mask !== 'string' || !/^[xyzw]{1,4}$/.test(mask)) return fail(`${at}: swizzle mask ${String(mask)}`);
+        if (mask.split('').some((c) => 'xyzw'.indexOf(c) >= VEC_LEN[src])) return fail(`${at}: mask ${mask} reads past a ${src}`);
+        return vecOf(mask.length);
+      }
+      case 'combine': {
+        if (ins.some((t) => !isNumeric(t))) return fail(`${at}: combine takes numbers`);
+        const n = ins.reduce((s, t) => s + VEC_LEN[t], 0);
+        return n >= 2 && n <= 4 ? vecOf(n) : fail(`${at}: combine makes ${n} components (2–4)`);
+      }
+      case 'noise': return ins[0] === 'vec2' || ins[0] === 'vec3' ? 'float' : fail(`${at}: noise takes a vec2 or vec3`);
+      case 'cameraBillboard': return ins[0] === 'vec3' && ins[1] === 'float' && ins[2] === 'vec2'
+        ? 'vec3' : fail(`${at}: ${op} needs world direction vec3, distance float and card-local vec2`);
+      case 'pointPair': return ins.every(t => t === 'vec3') ? spec.type ?? null : fail(`${at}: ${op} takes two vec3 points`);
+      case 'point3': return ins[0] === 'vec3' ? spec.type ?? null : fail(`${at}: ${op} takes a vec3 point`);
+      case 'dir3': return ins[0] === 'vec3' ? 'vec3' : fail(`${at}: ${op} takes a vec3 direction`);
+      case 'varying': return ins[0] !== undefined && isNumeric(ins[0]) ? ins[0] : fail(`${at}: a varying carries a number`);
+      case 'attribute': {
+        const name = raw.name, type = raw.type;
+        if (typeof name !== 'string' || !GRAPH_ATTRIBUTE_NAME.test(name)) return fail(`${at}: attribute name ${String(name)} (a, then a capital: aSeed)`);
+        if (type !== 'float' && type !== 'vec2' && type !== 'vec3' && type !== 'vec4') return fail(`${at}: attribute type ${String(type)} (float, vec2, vec3 or vec4)`);
+        if (raw['default'] !== undefined && literalType(raw['default']) !== type) return fail(`${at}: attribute default must be a finite ${type}`);
+        return type;
+      }
+      case 'sceneTap':
+        if (ins.length === 1 && ins[0] !== 'vec2') return fail(`${at}: ${op} samples at a vec2`);
+        if (op === 'sceneDepth') sampled.depth = true; else if (op === 'sceneNormal') sampled.normal = true; else sampled.scene = true;
+        return spec.type ?? null;
+      case 'texture': {
+        const name = raw.param;
+        if (typeof name !== 'string' || paramTypes.get(name) !== 'texture') return fail(`${at}: texture names a texture param`);
+        if (ins[0] !== (op === 'texture3D' ? 'vec3' : 'vec2')) return fail(`${at}: ${op} samples at a ${op === 'texture3D' ? 'vec3' : 'vec2'}`);
+        if (op === 'textureLod' && ins[1] !== 'float') return fail(`${at}: textureLod needs a numeric mip`);
+        if (op === 'textureGrad' && (ins[1] !== 'vec2' || ins[2] !== 'vec2')) return fail(`${at}: textureGrad needs two vec2 gradients`);
+        const dimension = op === 'textureArray' ? 'array' : op === 'texture3D' ? '3d' : '2d';
+        if (dimension === '3d' && (!isRecord(rawParams) || !isRecord(rawParams[name]) || rawParams[name].role !== 'lent')) return fail(`${at}: texture3D needs a lent texture param`);
+        if (dimension === 'array') {
+          const param = isRecord(rawParams) ? rawParams[name] : undefined;
+          if (ins[1] !== 'float' || !isRecord(param) || param.role !== 'lent') return fail(`${at}: textureArray needs a numeric layer and a lent texture param`);
+        }
+        const previous = textureDimensions.get(name);
+        if (previous !== undefined && previous !== dimension) return fail(`${at}: a texture param cannot mix sample dimensions`);
+        textureDimensions.set(name, dimension);
+        textures.add(name);
+        return 'vec4';
+      }
+      case 'acc': return scope.loop?.acc ?? fail(`${at}: acc outside a loop body`);
+      case 'index': return scope.loop !== null ? 'float' : fail(`${at}: index outside a loop body`);
+      case 'loop': {
+        const count = raw.count;
+        if (!Number.isInteger(count) || typeof count !== 'number' || count < 1 || count > LOOP_MAX) return fail(`${at}: loop count ${String(count)} (a constant, 1–${LOOP_MAX})`);
+        const init = typeRef(rawIns[0], scope, place, `${at}.in[0]`, mult);
+        if (init === null) return null;
+        if (init === 'bool') return fail(`${at}: a loop accumulates a number`);
+        const body = raw.body;
+        if (!isRecord(body) || !isRecord(body.nodes)) return fail(`${at}: loop body is { nodes, out }`);
+        const initDep = refDep(rawIns[0], scope);
+        const bodyScope: Scope = { nodes: body.nodes, parent: scope, loop: { acc: init, accDep: initDep }, path: `${at}.body` };
+        const out = typeRef(body.out, bodyScope, place, `${at}.body.out`, mult * count);
+        if (out === null) return null;
+        loopDep = initDep || refDep(body.out, bodyScope);
+        return out === init ? init : fail(`${at}: the body makes a ${out}, the accumulator is a ${init}`);
+      }
+      default: return fail(`${at}: op ${op} has no type rule`);
+    }
+  }
+
+  // stages
+  const stages = input.stages;
+  if (!isRecord(stages)) return { ok: false, errors: [...errors, 'graph: stages is not an object'] };
+  for (const k of Object.keys(stages)) if (!['vertex.offset', 'vertex.position', 'vertex.clip', 'vertex.normal', 'vertex.scale', 'shadow.offset', 'surface', 'lighting', 'outline', 'points', 'post', 'fog'].includes(k)) fail(`stages: unknown stage ${k}`);
+  if (kind !== 'fog' && stages.fog !== undefined) fail('stages.fog: only a fog graph has a fog stage');
+  const want = (ref: unknown, place: GraphPlace, type: GraphValueType, at: string): void => {
+    const t = typeRef(ref, root, place, at, 1);
+    if (t !== null && t !== type && !(t === 'float' && type !== 'bool')) fail(`${at}: is a ${t}, wants a ${type}`);
+  };
+  if (kind === 'material') {
+    if (stages.post !== undefined) fail('stages.post: a material graph has no post stage');
+    const points = stages.points;
+    if (input.primitive === 'points') {
+      if (input.model !== 'unlit') fail('graph: points require an unlit model');
+      if (stages.outline !== undefined) fail('graph: points cannot have a mesh outline');
+      if (!isRecord(points)) fail('stages.points: points need { size }');
+      else {
+        for (const k of Object.keys(points)) if (k !== 'size') fail(`stages.points: unknown output ${k}`);
+        want(points.size, 'vertex', 'float', 'stages.points.size');
+      }
+    } else if (points !== undefined) fail('stages.points: needs a points primitive');
+    const scale = stages['vertex.scale'];
+    if (scale !== undefined) {
+      if (!isRecord(scale)) fail('stages.vertex.scale: not an object');
+      else {
+        if (Object.keys(scale).length === 0) fail('stages.vertex.scale: needs a factor');
+        for (const key of Object.keys(scale)) if (key !== 'sun' && key !== 'fog') fail(`stages.vertex.scale: unknown output ${key}`);
+        for (const key of ['sun', 'fog'] as const) if (scale[key] !== undefined) {
+          if (key === 'sun' && input.model === 'unlit') fail('stages.vertex.scale.sun: needs a lit model');
+          want(scale[key], 'vertex', 'float', `stages.vertex.scale.${key}`);
+        }
+      }
+    }
+    const vn = stages['vertex.normal'];
+    if (vn !== undefined) {
+      if (input.primitive === 'points') fail('stages.vertex.normal: mesh normals only');
+      if (!isRecord(vn)) fail('stages.vertex.normal: not an object');
+      else {
+        for (const key of Object.keys(vn)) if (key !== 'normal') fail(`stages.vertex.normal: unknown output ${key}`);
+        want(vn['normal'], 'vertex', 'vec3', 'stages.vertex.normal.normal');
+      }
+    }
+    const clip = stages['vertex.clip'];
+    if (clip !== undefined) {
+      if (stages['vertex.position'] !== undefined || stages['vertex.offset'] !== undefined) fail('stages: vertex.clip excludes model-space position and offset');
+      if (!isRecord(clip)) fail('stages.vertex.clip: not an object');
+      else {
+        for (const key of Object.keys(clip)) if (key !== 'position') fail(`stages.vertex.clip: unknown output ${key}`);
+        const type = typeRef(clip.position, root, 'vertex', 'stages.vertex.clip.position', 1);
+        if (type !== null && type !== 'vec4') fail('stages.vertex.clip.position: wants a vec4');
+      }
+    }
+    const vp = stages['vertex.position'];
+    if (vp !== undefined) {
+      if (stages['vertex.offset'] !== undefined) fail('stages: vertex.position and vertex.offset are exclusive');
+      if (!isRecord(vp)) fail('stages.vertex.position: not an object');
+      else {
+        for (const key of Object.keys(vp)) if (key !== 'position' && key !== 'shadow') fail(`stages.vertex.position: unknown output ${key}`);
+        if (vp.shadow !== undefined && typeof vp.shadow !== 'boolean') fail('stages.vertex.position.shadow: a boolean');
+        if (vp.shadow === true && input.primitive === 'points') fail('stages.vertex.position.shadow: mesh casters only');
+        if (vp.shadow === true && stages['vertex.clip'] !== undefined) fail('stages.vertex.position.shadow: clip-position has no matching shadow camera');
+        want(vp.position, 'vertex', 'vec3', 'stages.vertex.position.position');
+      }
+    }
+    const vo = stages['vertex.offset'];
+    if (vo !== undefined) {
+      if (!isRecord(vo)) fail('stages.vertex.offset: not an object');
+      else {
+        want(vo.offset, 'vertex', 'vec3', 'stages.vertex.offset.offset');
+        if (vo.shadow !== undefined && typeof vo.shadow !== 'boolean') fail('stages.vertex.offset.shadow: a boolean');
+        if (vo.shadow === true && input.primitive === 'points') fail('stages.vertex.offset.shadow: mesh casters only');
+        if (vo.shadow === true && stages['vertex.clip'] !== undefined) fail('stages.vertex.offset.shadow: clip-position has no matching shadow camera');
+      }
+    }
+    const shadowOffset = stages['shadow.offset'];
+    if (shadowOffset !== undefined) {
+      if (input.primitive === 'points' || input.model === 'unlit') fail('stages.shadow.offset: lit mesh only');
+      if (!isRecord(shadowOffset)) fail('stages.shadow.offset: not an object');
+      else {
+        for (const key of Object.keys(shadowOffset)) if (key !== 'offset') fail(`stages.shadow.offset: unknown output ${key}`);
+        // per vertex, as both back-ends evaluate it: the classic program moves three's per-vertex shadow coordinates by it
+        // (no varying, derivative or facing reads), and TSL's received-shadow position interpolates the same value
+        want(shadowOffset.offset, 'vertex', 'vec3', 'stages.shadow.offset.offset');
+      }
+    }
+    const s = stages.surface;
+    if (s === undefined) fail('stages.surface: a material graph needs a surface');
+    else if (!isRecord(s)) fail('stages.surface: not an object');
+    else for (const [k, v] of Object.entries(s)) {
+      if (k === 'alphaCutoff') { if (!isFiniteNumber(v) || v < 0 || v > 1) fail('stages.surface.alphaCutoff: a number 0–1'); continue; }
+      const t = SURFACE_TYPES[k];
+      if (t === undefined) { fail(`stages.surface: unknown output ${k}`); continue; }
+      if (k === 'normal' && input.model === 'unlit') fail('stages.surface.normal: an unlit graph has no shading normal');
+      want(v, 'fragment', t, `stages.surface.${k}`);
+    }
+    if (isRecord(s) && s['targetAlpha'] !== undefined && (s['alpha'] !== undefined || (isRecord(input.effectState) && input.effectState.blend !== undefined))) fail('stages.surface.targetAlpha: an opaque draw only (no alpha, no blend)');
+    if (isRecord(s) && isRecord(input.effectState) && input.effectState.output === 'colour' && (s['targetAlpha'] !== undefined || s['alpha'] !== undefined)) fail('stages.surface: colour output owns the opaque alpha channel');
+    const lit = stages.lighting;
+    if (lit !== undefined) {
+      if (input.model === 'toon') fail('stages.lighting: toon supplies its family lighting; use standard for an authored lighting stage');
+      if (input.model === 'unlit') fail('stages.lighting: an unlit graph has no lighting model');
+      if (!isRecord(lit)) fail('stages.lighting: not an object');
+      else {
+        for (const k of Object.keys(lit)) if (!['sun', 'sunSpecular', 'ambient', 'grade'].includes(k)) fail(`stages.lighting: unknown output ${k}`);
+        if (lit.sun === undefined) fail('stages.lighting: a lighting model needs sun');
+        else want(lit.sun, 'sun', 'vec3', 'stages.lighting.sun');
+        if (lit.sunSpecular !== undefined) want(lit.sunSpecular, 'sun', 'float', 'stages.lighting.sunSpecular');
+        if (lit.ambient !== undefined) want(lit.ambient, 'ambient', 'vec3', 'stages.lighting.ambient');
+        if (lit.grade !== undefined) want(lit.grade, 'grade', 'vec3', 'stages.lighting.grade');
+      }
+    }
+    const ol = stages.outline;
+    if (ol !== undefined) {
+      if (!isRecord(ol)) fail('stages.outline: not an object');
+      else {
+        for (const k of Object.keys(ol)) if (k !== 'offset' && k !== 'colour') fail(`stages.outline: unknown field ${k} (the render state is fixed: back faces, depth on, opaque, unlit)`);
+        if (ol.offset === undefined || ol.colour === undefined) fail('stages.outline: an outline is { offset, colour }');
+        else {
+          want(ol.offset, 'outlineVertex', 'vec3', 'stages.outline.offset');
+          want(ol.colour, 'outline', 'vec3', 'stages.outline.colour');
+        }
+      }
+    }
+  } else if (kind === 'post') {
+    for (const k of ['vertex.offset', 'vertex.position', 'vertex.clip', 'vertex.normal', 'vertex.scale', 'shadow.offset', 'surface', 'lighting', 'outline', 'points'] as const) if (stages[k] !== undefined) fail(`stages.${k}: a post graph has only a post stage`);
+    const p = stages.post;
+    if (!isRecord(p)) fail('stages.post: a post graph needs { colour }');
+    else {
+      want(p.colour, 'post', 'vec3', 'stages.post.colour');
+      if (p['alpha'] !== undefined) want(p['alpha'], 'post', 'float', 'stages.post.alpha');
+    }
+  } else if (kind === 'fog') {
+    for (const k of Object.keys(stages)) if (k !== 'fog') fail(`stages.${k}: a fog graph has only a fog stage`);
+    const f = stages.fog;
+    if (!isRecord(f) || Object.keys(f).some((k) => k !== 'colour' && k !== 'transmission')) fail('stages.fog: a fog graph needs { colour, transmission? }');
+    else {
+      want(f.colour, 'fog', 'vec3', 'stages.fog.colour');
+      if (f['transmission'] !== undefined) want(f['transmission'], 'fog', 'float', 'stages.fog.transmission');
+    }
+  }
+
+  const cost: GraphCost = { nodes: nodeCount, samplers: textures.size + [sampled.scene, sampled.depth, sampled.normal, sampled.mesh].filter(Boolean).length + (postFogCost?.samplers ?? 0), instructions };
+  if (cost.nodes > budget.nodes) fail(`budget: ${cost.nodes} nodes (at most ${budget.nodes})`);
+  if (cost.samplers > budget.samplers) fail(`budget: ${cost.samplers} samplers (at most ${budget.samplers})`);
+  if (cost.instructions > budget.instructions) fail(`budget: ≈ ${cost.instructions} instructions (at most ${budget.instructions})`);
+  if (errors.length > 0) return { ok: false, errors };
+  const rootTypes = new Map<string, GraphValueType>();
+  for (const [key, t] of types) if (key.startsWith('nodes/')) rootTypes.set(key.slice(6), t);
+  // the shape has been checked field by field above, so the input is the graph
+  return { ok: true, graph: asGraph(input, postFog), cost, types: rootTypes, inputs: { colour: sampled.scene, depth: sampled.depth, normal: sampled.normal } };
+}
+
+/** a checked record as the typed graph (called only once validateGraph found no error) */
+function asGraph(input: Raw, postFog?: GraphIr['postFog']): GraphIr {
+  const graph: GraphIr = {
+    version: GRAPH_IR_VERSION,
+    ...(postFog === undefined ? {} : { postFog }),
+    ...(isRecord(input.budget) ? { budget: { nodes: Number(input.budget.nodes), samplers: Number(input.budget['samplers']), instructions: Number(input.budget['instructions']) } } : {}),
+    kind: input.kind === 'post' ? 'post' : input.kind === 'fog' ? 'fog' : 'material',
+    nodes: isRecord(input.nodes) ? toNodes(input.nodes) : {},
+    stages: isRecord(input.stages) ? toStages(input.stages) : {},
+    ...(input.primitive === 'mesh' || input.primitive === 'points' ? { primitive: input.primitive } : {}),
+    ...(isRecord(input.effectState) ? { effectState: toEffectState(input.effectState) } : {}),
+    ...(input.model === 'standard' || input.model === 'unlit' || input.model === 'toon' ? { model: input.model } : {}),
+    ...(typeof input.doubleSided === 'boolean' ? { doubleSided: input.doubleSided } : {}),
+    ...(typeof input.flipBackfaceNormals === 'boolean' ? { flipBackfaceNormals: input.flipBackfaceNormals } : {}),
+    ...(typeof input.toonCaustics === 'boolean' ? { toonCaustics: input.toonCaustics } : {}),
+    ...(typeof input.flatShading === 'boolean' ? { flatShading: input.flatShading } : {}),
+    ...(isRecord(input.params) ? { params: toParams(input.params) } : {}),
+    ...(isRecord(input.arrays) ? { arrays: toArrays(input.arrays) } : {}),
+  };
+  return graph;
+}
+function toEffectState(raw: Raw): GraphEffectState {
+  const bias = raw.depthBias;
+  return {
+    ...(raw.output === 'colour' ? { output: raw.output } : {}),
+    ...(raw.blend === 'alpha' || raw.blend === 'additive' || raw.blend === 'premultiplied' ? { blend: raw.blend } : {}),
+    ...(raw.fog === false || typeof raw.fog === 'string' ? { fog: raw.fog } : {}),
+    ...(typeof raw.depthWrite === 'boolean' ? { depthWrite: raw.depthWrite } : {}),
+    ...(raw.singlePass === true ? { singlePass: true } : {}),
+    ...(isRecord(bias) && isFiniteNumber(bias.factor) && isFiniteNumber(bias.units) ? { depthBias: { factor: bias.factor, units: bias.units } } : {}),
+  };
+}
+const toRef = (v: unknown): GraphRef => (typeof v === 'string' ? v : isFiniteNumber(v) ? v : Array.isArray(v) ? v.filter(isFiniteNumber) : 0);
+function toNodes(raw: Raw): Record<string, GraphNode> {
+  const out: Record<string, GraphNode> = {};
+  for (const [id, n] of Object.entries(raw)) {
+    if (!isRecord(n) || typeof n.op !== 'string') continue;
+    out[id] = {
+      op: n.op,
+      ...(Array.isArray(n.in) ? { in: n.in.map(toRef) } : {}),
+      ...(n.value !== undefined ? { value: isFiniteNumber(n.value) ? n.value : Array.isArray(n.value) ? n.value.filter(isFiniteNumber) : 0 } : {}),
+      ...(typeof n.param === 'string' ? { param: n.param } : {}),
+      ...(typeof n.mask === 'string' ? { mask: n.mask } : {}),
+      ...(n['default'] !== undefined ? { default: isFiniteNumber(n['default']) ? n['default'] : Array.isArray(n['default']) ? n['default'].filter(isFiniteNumber) : 0 } : {}),
+      ...(n.interpolation === 'flat' ? { interpolation: 'flat' } : {}),
+      ...(typeof n.count === 'number' ? { count: n.count } : {}),
+      ...(typeof n.name === 'string' ? { name: n.name } : {}),
+      ...(n.type === 'float' || n.type === 'vec2' || n.type === 'vec3' || n.type === 'vec4' ? { type: n.type } : {}),
+      ...(isRecord(n.body) && isRecord(n.body.nodes) ? { body: { nodes: toNodes(n.body.nodes), out: toRef(n.body.out) } } : {}),
+    };
+  }
+  return out;
+}
+function toStages(raw: Raw): GraphStages {
+  const scale = raw['vertex.scale'];
+  const vn = raw['vertex.normal'];
+  const clip = raw['vertex.clip'];
+  const vp = raw['vertex.position'], vo = raw['vertex.offset'], s = raw.surface, p = raw.post, l = raw.lighting, o = raw.outline;
+  const surface: Record<string, GraphRef | number> = {};
+  if (isRecord(s)) for (const [k, v] of Object.entries(s)) surface[k] = k === 'alphaCutoff' && isFiniteNumber(v) ? v : toRef(v);
+  return {
+    ...(isRecord(raw['shadow.offset']) ? { 'shadow.offset': { offset: toRef(raw['shadow.offset'].offset) } } : {}),
+    ...(isRecord(raw.points) ? { points: { size: toRef(raw.points.size) } } : {}),
+    ...(isRecord(scale) ? { 'vertex.scale': { ...(scale.sun !== undefined ? { sun: toRef(scale.sun) } : {}), ...(scale.fog !== undefined ? { fog: toRef(scale.fog) } : {}) } } : {}),
+    ...(isRecord(vn) ? { 'vertex.normal': { normal: toRef(vn['normal']) } } : {}),
+    ...(isRecord(clip) ? { 'vertex.clip': { position: toRef(clip.position) } } : {}),
+    ...(isRecord(vp) ? { 'vertex.position': { position: toRef(vp.position), ...(typeof vp.shadow === 'boolean' ? { shadow: vp.shadow } : {}) } } : {}),
+    ...(isRecord(vo) ? { 'vertex.offset': { offset: toRef(vo.offset), ...(typeof vo.shadow === 'boolean' ? { shadow: vo.shadow } : {}) } } : {}),
+    ...(isRecord(s) ? { surface } : {}),
+    ...(isRecord(p) ? { post: { colour: toRef(p.colour), ...(p['alpha'] === undefined ? {} : { alpha: toRef(p['alpha']) }) } } : {}),
+    ...(isRecord(raw.fog) ? { fog: { colour: toRef(raw.fog.colour), ...(raw.fog['transmission'] === undefined ? {} : { transmission: toRef(raw.fog['transmission']) }) } } : {}),
+    ...(isRecord(o) ? { outline: { offset: toRef(o.offset), colour: toRef(o.colour) } } : {}),
+    ...(isRecord(l) ? { lighting: {
+      sun: toRef(l.sun),
+      ...(l.sunSpecular !== undefined ? { sunSpecular: toRef(l.sunSpecular) } : {}),
+      ...(l.ambient !== undefined ? { ambient: toRef(l.ambient) } : {}),
+      ...(l.grade !== undefined ? { grade: toRef(l.grade) } : {}),
+    } } : {}),
+  };
+}
+function toParams(raw: Raw): Record<string, GraphParam> {
+  const out: Record<string, GraphParam> = {};
+  for (const [name, p] of Object.entries(raw)) {
+    if (!isRecord(p)) continue;
+    const t = p.type;
+    if (t !== 'float' && t !== 'vec2' && t !== 'vec3' && t !== 'vec4' && t !== 'colour' && t !== 'texture') continue;
+    const b = p.bind;
+    out[name] = {
+      type: t,
+      ...(p.role === 'colour' || p.role === 'data' || p.role === 'lent' ? { role: p.role } : {}),
+      value: typeof p.value === 'string' ? p.value : toRef(p.value),
+      ...(isFiniteNumber(p.min) ? { min: p.min } : {}),
+      ...(isFiniteNumber(p.max) ? { max: p.max } : {}),
+      ...(isRecord(b) && typeof b.day === 'string' ? { bind: { day: b.day } } : isRecord(b) && typeof b.state === 'string' ? { bind: { state: b.state } } : {}),
+    };
+  }
+  return out;
+}
+
+/** Does an admitted graph read the original mesh colour map, including nested bounded loop bodies? */
+export function graphUsesMeshMap(graph: Pick<GraphIr, 'nodes'>): boolean {
+  const groups = [graph.nodes];
+  for (const nodes of groups) for (const node of Object.values(nodes)) {
+    if (node.op === 'meshMap') return true;
+    if (node.body !== undefined) groups.push(node.body.nodes);
+  }
+  return false;
+}
+
+/** Copy admitted lists so caller mutations cannot resize compiled uniforms. */
+function toArrays(raw: Raw): Record<string, GraphArrayParam> {
+  const out: Record<string, GraphArrayParam> = {};
+  for (const [name, row] of Object.entries(raw)) {
+    if (!isRecord(row) || !Array.isArray(row.value)) continue;
+    const type = row.type;
+    if (type !== 'float' && type !== 'vec2' && type !== 'vec3' && type !== 'vec4') continue;
+    out[name] = { type, value: row.value.map(value => {
+      const literal = toRef(value);
+      if (typeof literal === 'string') throw new Error('Uniform lists require literal values');
+      return literal;
+    }) };
+  }
+  return out;
+}