@forgeax/engine-naga 0.0.0-dev.8d955ade1c79

package/src/errors.ts

@@ -0,0 +1,208 @@
+// @forgeax/engine-naga/errors — ShaderError + Result<T, E> + wrapShaderError helper.
+//
+// Form invariants (plan-strategy §D-P4 / requirements MVP-2.3 + AC-09):
+// - ShaderErrorCode (closed 4-member union) is imported from @forgeax/engine-types as
+//   the SSOT. This package does **not** redefine the union — +0 breaking points
+//   to the error model (AC-09; charter proposition 5 consistent abstraction).
+// - The ShaderError class shape + 4 factory helpers + Result<T, E> shape are
+//   byte-for-byte equivalent to @forgeax/engine-shader-compiler/src/errors.ts; that
+//   package will re-export from here in w7 after the import switch lands
+//   (charter proposition 5 + plan-strategy D-P4 byte-for-byte form recovery).
+// - wrapShaderError is the JsError -> ShaderError adapter for the parse /
+//   validate / emit_reflection wrappers in index.ts: it tries to JSON.parse the
+//   wasm-side ParseErrorPayload (message / summary / line_num / line_pos)
+//   first, falls back to the prose message for validator / reflection failures.
+
+/// <reference types="@webgpu/types" />
+
+import type { ShaderErrorCode, ShaderErrorDetail } from '@forgeax/engine-types';
+
+export type { ShaderErrorCode, ShaderErrorDetail };
+
+interface ShaderErrorInit {
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly message: string;
+  readonly lineNum?: number | undefined;
+  readonly linePos?: number | undefined;
+  readonly detail?: ShaderErrorDetail | undefined;
+}
+
+/**
+ * Structured shader error.
+ *
+ * **5 surface fields** (MVP-2.3 top-level surface, AI consumer path):
+ * - `.code` — member of the closed `ShaderErrorCode` union (4 variants)
+ * - `.message` — display text (the base `Error` field, populated by the constructor)
+ * - `.hint` — actionable recovery guidance (charter proposition 3: machine-readable hint over prose)
+ * - `.lineNum` / `.linePos` — error source location (mandatory for compile-failed; undefined on other paths)
+ *
+ * **3 internal fields**:
+ * - `.name` = `'ShaderError'` (debug tag)
+ * - `.expected` — description of the expected state (symmetric with RhiError)
+ * - `.detail` — path-specific extra info (e.g. all 6 fields of GPUCompilationMessage[])
+ *
+ * **Do not new directly** — construct via the 4 factories (compileFailed /
+ * initFailed / manifestMalformed / shaderNotFound) to avoid ad-hoc arguments
+ * bypassing union narrowing.
+ */
+export class ShaderError extends Error {
+  override readonly name: 'ShaderError' = 'ShaderError';
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly lineNum: number | undefined;
+  readonly linePos: number | undefined;
+  readonly detail: ShaderErrorDetail | undefined;
+
+  constructor(init: ShaderErrorInit) {
+    super(init.message);
+    this.code = init.code;
+    this.expected = init.expected;
+    this.hint = init.hint;
+    this.lineNum = init.lineNum;
+    this.linePos = init.linePos;
+    this.detail = init.detail;
+  }
+}
+
+// === 4 factory helpers (plan-strategy §D-P4 closed union with 4 members) ===========
+
+/** `shader-compile-failed`: naga parse_str or Validator::validate failure. */
+export function compileFailed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly lineNum?: number | undefined;
+  readonly linePos?: number | undefined;
+  readonly compilerMessages?: readonly GPUCompilationMessage[] | undefined;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'shader-compile-failed',
+    expected: 'WGSL source parses + validates against naga IR',
+    message: args.message,
+    hint: args.hint,
+    ...(args.lineNum !== undefined ? { lineNum: args.lineNum } : {}),
+    ...(args.linePos !== undefined ? { linePos: args.linePos } : {}),
+    ...(args.compilerMessages !== undefined
+      ? {
+          detail: {
+            code: 'shader-compile-failed',
+            compilerMessages: args.compilerMessages,
+            ...(args.reason !== undefined ? { reason: args.reason } : {}),
+          },
+        }
+      : {}),
+  });
+}
+
+/** `compiler-init-failed`: wasm loading or init() failure (cold start / missing wasm artifact). */
+export function initFailed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'compiler-init-failed',
+    expected: '@forgeax/engine-wgpu-wasm ensureReady() resolves with naga raw bindings available',
+    message: args.message,
+    hint: args.hint,
+    detail: {
+      code: 'compiler-init-failed',
+      ...(args.reason !== undefined ? { reason: args.reason } : {}),
+    },
+  });
+}
+
+/** `manifest-malformed`: manifest.json schema validation failure (a required field is missing or JSON is not parseable). */
+export function manifestMalformed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'manifest-malformed',
+    expected: 'manifest.json parses + every entry has {hash, wgsl, glsl, bindings}',
+    message: args.message,
+    hint: args.hint,
+    detail: {
+      code: 'manifest-malformed',
+      ...(args.reason !== undefined ? { reason: args.reason } : {}),
+    },
+  });
+}
+
+/** `shader-not-found`: ShaderRegistry.get(hash) hash miss. */
+export function shaderNotFound(args: {
+  readonly hash: string;
+  readonly hint: string;
+}): ShaderError {
+  return new ShaderError({
+    code: 'shader-not-found',
+    expected: `manifest.entries contains entry with hash '${args.hash}'`,
+    message: `ShaderRegistry: hash '${args.hash}' not present in manifest`,
+    hint: args.hint,
+  });
+}
+
+// === wrapShaderError: JsError -> ShaderError adapter ================================
+
+/**
+ * Translate a thrown wasm-bindgen JsError to a structured ShaderError.
+ *
+ * The Rust side serializes `ParseErrorPayload { message, summary, line_num,
+ * line_pos }` to a JSON string and uses it as the JsError message. We attempt
+ * JSON.parse first; on success the lineNum/linePos are extracted as top-level
+ * surface fields (MVP-2.3). On failure (validator errors, reflection errors,
+ * non-JSON messages) we fall back to the prose message — hint is always
+ * populated so AI consumers always have an actionable recovery signal
+ * (charter proposition 4 explicit failure + proposition 3 machine-readable hint).
+ */
+export function wrapShaderError(e: unknown, hint?: string): ShaderError {
+  if (e instanceof Error) {
+    try {
+      const payload = JSON.parse(e.message) as {
+        message?: string;
+        summary?: string;
+        line_num?: number | null;
+        line_pos?: number | null;
+      };
+      return compileFailed({
+        message: payload.summary ?? payload.message ?? e.message,
+        hint:
+          hint ??
+          'fix the WGSL source at the indicated line/column; see ShaderError.detail.compilerMessages for full diagnostic frame',
+        ...(typeof payload.line_num === 'number' ? { lineNum: payload.line_num } : {}),
+        ...(typeof payload.line_pos === 'number' ? { linePos: payload.line_pos } : {}),
+      });
+    } catch {
+      return compileFailed({
+        message: e.message,
+        hint: hint ?? 'check WGSL syntax + validation rules; consult naga error output for details',
+      });
+    }
+  }
+  return compileFailed({
+    message: String(e),
+    hint:
+      hint ??
+      'unknown error type from @forgeax/engine-wgpu-wasm; report as @forgeax/engine-naga bug',
+  });
+}
+
+// === Result<T, E> ====================================================================
+//
+// Result<T, E> + ok / err + ResultOk / ResultErr live in `@forgeax/engine-types`
+// (tweak-20260612-result-into-types). They were duplicated here as a lite
+// (plain-object, no `unwrap`) variant; consolidated upstream into the same
+// shape used by rhi / ecs. The barrel here re-exports them so existing
+// `import { err, ok, Result, ResultOk, ResultErr } from '@forgeax/engine-naga'`
+// consumers stay unchanged.
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-types';

package/src/index.ts

@@ -0,0 +1,384 @@
+// @forgeax/engine-naga — TS-only thin shell over @forgeax/engine-wgpu-wasm raw naga bindings.
+//
+// Form invariants (locked by plan-strategy D-P3 / D-P4 + research F-4):
+//
+// - snake_case three-phase functions byte-for-byte aligned with naga upstream
+//   naming (this package replaces the legacy wasm-pack shim archived in
+//   feat-20260511-naga-rhi-wgpu-merge M5 — charter proposition 2 industry
+//   analogy + proposition 5 consistent abstraction).
+// - Each public function awaits ensureReady() from @forgeax/engine-wgpu-wasm before
+//   calling the raw wasm-bindgen export — one wasm boundary crossing per page
+//   lifecycle, shared with @forgeax/engine-rhi-wgpu (research F-4 ensureReady SSOT).
+// - Throws are caught at the wrapper boundary and translated to
+//   Result.err(ShaderError) — never throw for expected failures
+//   (AGENTS.md "Errors are structured" + charter proposition 4 explicit failure).
+// - The opaque handle types ParsedModule / ValidatedModule are re-exported
+//   so downstream consumers (@forgeax/engine-shader-compiler) can hold the handle
+//   between phases without inspecting the underlying naga IR
+//   (plan-strategy §S-1 opaque handle invariant).
+
+import { ensureReady } from '@forgeax/engine-wgpu-wasm';
+import {
+  err,
+  initFailed,
+  manifestMalformed,
+  ok,
+  type Result,
+  ShaderError,
+  type ShaderError as ShaderErrorType,
+  wrapShaderError,
+} from './errors.js';
+
+export {
+  compileFailed,
+  err,
+  initFailed,
+  manifestMalformed,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+  ShaderError,
+  type ShaderErrorCode,
+  type ShaderErrorDetail,
+  shaderNotFound,
+} from './errors.js';
+
+// === Opaque handle types ============================================================
+
+/**
+ * Handle for the `parse` output. The underlying type is a wasm-bindgen exported
+ * struct: JS can only hold the handle — it cannot inspect naga IR fields
+ * directly (charter proposition 4 + opaque handle invariant). Pass through to
+ * `validate` to advance to phase 2.
+ *
+ * Surface type uses `unknown` to keep this layer math-free and opaque-handle
+ * pure (no direct dependency on @forgeax/engine-wgpu-wasm/pkg ABI types). Downstream
+ * consumers should not inspect the handle.
+ */
+export type ParsedModule = unknown;
+
+/**
+ * Handle for the `validate` output (Module + ModuleInfo); pass through to
+ * `emit_reflection` for the reflection JSON emit.
+ */
+export type ValidatedModule = unknown;
+
+export interface ShaderReflectionMember {
+  readonly name: string;
+  readonly type: string;
+  readonly offset: number;
+  readonly size: number;
+  readonly alignment: number;
+}
+
+export interface ShaderReflectionBoundGlobal {
+  readonly group: number;
+  readonly binding: number;
+  readonly addressSpace: string;
+  readonly resourceKind: string;
+  readonly visibility: number;
+  readonly name?: string;
+  readonly members?: readonly ShaderReflectionMember[];
+  readonly span?: number;
+}
+
+export interface ShaderReflection {
+  readonly schemaVersion: 'shader-reflection/2';
+  readonly boundGlobals: readonly ShaderReflectionBoundGlobal[];
+  readonly uvSetCount: number;
+}
+
+type ReflectionRecord = Record<string, unknown>;
+
+function reflectionMalformed(reason: string): ShaderError {
+  return manifestMalformed({
+    message: `shader-reflection/2 is malformed: ${reason}`,
+    hint: 'rebuild the shader with the current Naga/WASM producer and preserve every bound-global fact',
+    reason,
+  });
+}
+
+function isRecord(value: unknown): value is ReflectionRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requiredNonNegativeInteger(record: ReflectionRecord, key: string): number {
+  const value = record[key];
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+    throw reflectionMalformed(`boundGlobals entry requires non-negative integer '${key}'`);
+  }
+  return value;
+}
+
+function readMember(value: unknown, index: number): ShaderReflectionMember {
+  if (!isRecord(value)) throw reflectionMalformed(`member ${index} is not an object`);
+  const name = value.name;
+  const type = value.type;
+  if (
+    typeof name !== 'string' ||
+    name.length === 0 ||
+    typeof type !== 'string' ||
+    type.length === 0
+  ) {
+    throw reflectionMalformed(`member ${index} requires name and type`);
+  }
+  return {
+    name,
+    type,
+    offset: requiredNonNegativeInteger(value, 'offset'),
+    size: requiredNonNegativeInteger(value, 'size'),
+    alignment: requiredNonNegativeInteger(value, 'alignment'),
+  };
+}
+
+function readBoundGlobal(value: unknown, index: number): ShaderReflectionBoundGlobal {
+  if (!isRecord(value)) throw reflectionMalformed(`boundGlobals entry ${index} is not an object`);
+  const addressSpace = value.addressSpace;
+  const resourceKind = value.resourceKind;
+  if (typeof addressSpace !== 'string' || addressSpace.length === 0) {
+    throw reflectionMalformed(`boundGlobals entry ${index} requires addressSpace`);
+  }
+  if (typeof resourceKind !== 'string' || resourceKind.length === 0) {
+    throw reflectionMalformed(`boundGlobals entry ${index} requires resourceKind`);
+  }
+  const visibility = requiredNonNegativeInteger(value, 'visibility');
+  const membersValue = value.members;
+  const hasMembers = membersValue !== undefined;
+  if (hasMembers && !Array.isArray(membersValue)) {
+    throw reflectionMalformed(`boundGlobals entry ${index} members must be an array`);
+  }
+  const hasSpan = value.span !== undefined;
+  if (resourceKind === 'buffer' || resourceKind === 'storage-buffer') {
+    if (!hasMembers || !hasSpan) {
+      throw reflectionMalformed(`buffer boundGlobals entry ${index} requires members and span`);
+    }
+  } else if (hasMembers !== hasSpan) {
+    throw reflectionMalformed(`boundGlobals entry ${index} members and span must be paired`);
+  }
+  if (value.name !== undefined && typeof value.name !== 'string') {
+    throw reflectionMalformed(`boundGlobals entry ${index} diagnostic name must be a string`);
+  }
+  return {
+    group: requiredNonNegativeInteger(value, 'group'),
+    binding: requiredNonNegativeInteger(value, 'binding'),
+    addressSpace,
+    resourceKind,
+    visibility,
+    ...(value.name !== undefined ? { name: value.name as string } : {}),
+    ...(hasMembers
+      ? {
+          members: (membersValue as unknown[]).map((member, memberIndex) =>
+            readMember(member, memberIndex),
+          ),
+          span: requiredNonNegativeInteger(value, 'span'),
+        }
+      : {}),
+  };
+}
+
+/** Parse and validate the business-neutral shader-reflection/2 wire. */
+export function parseReflectionWire(json: string): ShaderReflection {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (cause) {
+    throw reflectionMalformed(cause instanceof Error ? cause.message : 'JSON.parse failed');
+  }
+  if (!isRecord(parsed) || parsed.schemaVersion !== 'shader-reflection/2') {
+    throw reflectionMalformed("schemaVersion must equal 'shader-reflection/2'");
+  }
+  if ('material' in parsed) throw reflectionMalformed('legacy material projection is not accepted');
+  if (!Array.isArray(parsed.boundGlobals)) {
+    throw reflectionMalformed('boundGlobals must be an array');
+  }
+  if (
+    typeof parsed.uvSetCount !== 'number' ||
+    !Number.isSafeInteger(parsed.uvSetCount) ||
+    parsed.uvSetCount < 0
+  ) {
+    throw reflectionMalformed('uvSetCount must be a non-negative integer');
+  }
+  const boundGlobals = parsed.boundGlobals.map((global, index) => readBoundGlobal(global, index));
+  const coordinates = new Set<string>();
+  for (const global of boundGlobals) {
+    const coordinate = `${global.group}:${global.binding}`;
+    if (coordinates.has(coordinate))
+      throw reflectionMalformed(`duplicate bound-global coordinate ${coordinate}`);
+    coordinates.add(coordinate);
+  }
+  return { schemaVersion: 'shader-reflection/2', boundGlobals, uvSetCount: parsed.uvSetCount };
+}
+
+/** Result-form reader for callers that need an explicit unavailable/malformed branch. */
+export function readReflectionWire(
+  json: string | undefined,
+): Result<ShaderReflection, ShaderErrorType> {
+  if (json === undefined) {
+    return err(
+      initFailed({
+        message: 'shader-reflection/2 is unavailable before the Naga producer emits a wire',
+        hint: 'run the validated compose -> reflect path and retain its raw reflection bytes',
+        reason: 'reflection wire unavailable',
+      }),
+    );
+  }
+  try {
+    return ok(parseReflectionWire(json));
+  } catch (error) {
+    return err(error instanceof ShaderError ? error : reflectionMalformed(String(error)));
+  }
+}
+
+// === Phase 1: parse =================================================================
+
+/**
+ * WGSL source -> `ParsedModule`.
+ *
+ * On failure returns `Result.err(ShaderError code='shader-compile-failed')`
+ * whose `lineNum` / `linePos` carry the source position (from the wasm-side
+ * `ParseErrorPayload`). The hint defaults to actionable WGSL fix guidance.
+ *
+ * Wasm boundary: awaits ensureReady() on first call (shared singleton with
+ * @forgeax/engine-rhi-wgpu); subsequent calls take the cached path.
+ */
+export async function parse(source: string): Promise<Result<ParsedModule, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const parsed = wasm.parse(source);
+    return ok(parsed as ParsedModule);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+
+// === Phase 2: validate ==============================================================
+
+/**
+ * `ParsedModule` -> `ValidatedModule` (Module + ModuleInfo).
+ *
+ * **Ownership transfer** — wasm-bindgen consumes the `parsed` handle. Do not
+ * reuse the handle after this call; passing a consumed handle is undefined
+ * behaviour on the wasm side (research Finding 6 ownership semantics).
+ *
+ * On failure returns `Result.err(ShaderError code='shader-compile-failed')`.
+ * Validator errors have no source position attached on the wasm side, so
+ * `lineNum` / `linePos` remain undefined.
+ */
+export async function validate(
+  parsed: ParsedModule,
+): Promise<Result<ValidatedModule, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const validated = (wasm.validate as (p: unknown) => unknown)(parsed);
+    return ok(validated as ValidatedModule);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+
+// === Composer passthrough ===========================================================
+
+/**
+ * naga_oil Composer passthrough — `#import` + `#ifdef` composition over WGSL.
+ *
+ * Thin TS wrap over `@forgeax/engine-wgpu-wasm`'s raw `compose_shader` export
+ * (feat-20260512 M1 compose.rs). Three-argument surface:
+ *
+ * - `entry` — the entry-point WGSL source (may contain `#import` directives
+ *   and `#ifdef` guards).
+ * - `imports` — `moduleId -> wgslSource` map; each value is a companion
+ *   module whose header declares `#define_import_path <moduleId>` so the
+ *   upstream composer can register it. The map is JSON.stringified at the
+ *   wasm boundary.
+ * - `defines` — `name -> boolean` map driving `#ifdef` branch elimination
+ *   (plan-strategy D-06: non-boolean values are rejected at the TS layer by
+ *   the shader-compiler wrapper; this wrap takes booleans verbatim). Also
+ *   JSON.stringified at the boundary.
+ *
+ * Return: the composed WGSL string (entry + inlined imports, `#ifdef` branches
+ * resolved).
+ *
+ * Errors: the raw wasm export throws `JsError` whose message carries a
+ * `shader-import-not-found: ...` or `shader-compile-failed: ...` prefix
+ * (feat-20260512 M1 compose.rs convention). This wrap does **not** translate
+ * the prefix into a structured `ShaderError`; that splitting happens one layer
+ * up at `@forgeax/engine-shader-compiler` (feat-20260512 M3), which is where
+ * the three-argument `compileShader(src, { imports, defines, id })` entry lives.
+ * Callers of this raw passthrough should `try / catch` the thrown error.
+ *
+ * Wasm boundary: awaits `ensureReady()` on first call (shared singleton with
+ * `@forgeax/engine-rhi-wgpu` + other naga phases); subsequent calls take the
+ * cached path.
+ */
+export async function composeShader(
+  entry: string,
+  imports: Record<string, string>,
+  defines: Record<string, boolean>,
+): Promise<string> {
+  const wasm = await ensureReady();
+  const compose = (wasm as { compose_shader: (e: string, i: string, d: string) => string })
+    .compose_shader;
+  return compose(entry, JSON.stringify(imports), JSON.stringify(defines));
+}
+
+// === Phase 3: emit_reflection =======================================================
+
+/**
+ * `ValidatedModule` + options JSON -> `BindGroupLayoutDescriptor[]` JSON string.
+ *
+ * `options_json` shape: `{ "dynamicOffsets": [{ "group": u32, "binding": u32 }, ...] }`.
+ * The naga IR does not express the dynamic-offset dimension (research Finding 2
+ * footnote), so it is injected via this JS-side options string. Pass an empty
+ * `{}` (or a JSON-encoded object without `dynamicOffsets`) for the no-dynamic-
+ * offset path.
+ *
+ * The validator's borrowed reference is **not** consumed — the same
+ * `ValidatedModule` handle can be reused for repeated emits with different
+ * options (e.g. for variant generation).
+ */
+export async function emit_reflection(
+  validated: ValidatedModule,
+  options_json: string,
+): Promise<Result<string, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const reflectionJson = (wasm.emit_reflection as (v: unknown, o: string) => string)(
+      validated,
+      options_json,
+    );
+    return ok(reflectionJson);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}