`validateUniformLayout()` — dev-time schema ↔ WGSL struct validation via `Reflection.hostShareableLayouts`

// ── @vgpu/wgsl (new: runtime/structLayout.ts; wired into runtime/reflect.ts) ──

interface StructMemberLayout {
  readonly name: string;
  readonly type: string;      // WGSL source type text, e.g. "vec4f", "mat4x4<f32>"
  readonly offset: number;    // WGSL uniform layout rules, honoring @align/@size
  readonly size: number;
  readonly align: number;
}

interface StructLayout {
  readonly name: string;      // source-level name (pre-minify)
  readonly module: string;    // module path — disambiguates duplicate struct names
  readonly byteSize: number;
  readonly members: readonly StructMemberLayout[];
  /** false when the struct uses constructs the layout table doesn't model
   *  (nested structs, runtime-sized arrays, f16, atomics). Members computed
   *  up to the first unmodeled one are still reported. */
  readonly complete: boolean;
}

// Reflection.hostShareableLayouts: readonly StructLayout[]   (was: readonly [] — reserved, reflect.ts:8)
// v1 scope: scalars, vectors, matrices (the 15 WgslUniformType names) + array<T, N> of those.

// Moved from @vgpu/render/domain/wgsl-alignment.ts (re-exported there, unchanged):
export { alignUniforms, wgslType, isWgslUniformType, type WgslUniformType, type UniformLayoutInfo };

// ── validateUniformLayout — LIVES IN @vgpu/wgsl, re-exported by @vgpu/render ──
// Parameter types are structural: no @vgpu/render import; usable from node build scripts.

interface UniformLayoutLike {                       // structural match of UniformLayoutInfo
  readonly fields: readonly { name: string; type: string; offset: number; size: number }[];
  readonly byteSize: number;
}

function validateUniformLayout(
  uniform: UniformLayoutLike | { readonly layout: UniformLayoutLike },  // StructuredUniform matches via .layout
  shader: { readonly reflection: { readonly hostShareableLayouts: readonly StructLayout[] } }, // ResolvedShader matches
  opts: {
    readonly struct: string;
    /** Module path (or unambiguous suffix). REQUIRED when `struct` matches >1 module —
     *  ambiguity throws, listing candidates. */
    readonly module?: string;
    /** "layout" (default): compares BYTE SPANS, not names. Valid iff byteSize matches and
     *  every WGSL member span is exactly tiled by schema field spans (a schema may subdivide
     *  a WGSL vec4f into 4 named f32s); where spans coincide 1:1, types must match.
     *  "names": additionally requires 1:1 name equality in order — catches same-type
     *  reorders (e.g. fov/aspect swap) that layout mode provably cannot see. */
    readonly mode?: "layout" | "names";
  },
): void;
// Throws ValidationError with a field-by-field offset diff table (below).
// Throws a DISTINCT error if the struct's layout is complete: false — never silently passes.

import { resolveShader } from "@vgpu/wgsl/runtime";
import { validateUniformLayout } from "@vgpu/render"; // re-export of @vgpu/wgsl's

const shader = await resolveShader({ entry: "./shaders/glass/front.wgsl" });

if (process.env.NODE_ENV !== "production") {
  validateUniformLayout(sceneParams, shader, {
    struct: "Params",
    module: "shared/glass-common.wgsl", // two `Params` exist in Eve's graph — suffix disambiguates
  });
}
// On drift, thrown at startup:
// ValidationError: struct 'Params' (shared/glass-common.wgsl) is 192 B; schema is 176 B.
//   offset   WGSL member            schema field(s)
//   0..64    viewProj: mat4x4f      viewProj: mat4x4f          ok
//   64..76   cameraPos: vec3f       cameraPos: vec3f           ok
//   ...
//   144..160 lightTint: vec4f       — no schema fields —       MISSING
//   160..176 ascii0: vec4f          ascii0: vec4f              shifted (schema: 144)

// The entirety of today's protection (render.ts, eve-colored-lights branch):
// INVARIANT: 176 bytes / 44 f32; field order must match shaders/shared/glass-common.wgsl

// A reviewer must, by hand, on every schema or WGSL edit:
//  1. recompute every field offset under WGSL uniform alignment rules
//     (vec3f aligns to 16 — the rule everyone forgets),
//  2. recount PARAMS_BYTE_SIZE (this step produced the 144 B vs 176 B cross-branch
//     drift and hours of debugging garbage pixels),
//  3. visually diff TS field order against the WGSL struct member order.
// There is no failure signal. The GPU reads whatever bytes are there.