@forgeax/engine-render 0.1.2

package/src/pipeline/index.ts

@@ -0,0 +1,40 @@
+import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PipelineError } from '../pipeline-errors';
+
+export const pipelineStages = ['extract', 'prepare', 'record'] as const;
+export type PipelineStage = (typeof pipelineStages)[number];
+
+/**
+ * Compose the renderer-owned vertex-color axis from geometry projection facts.
+ * Authored material definitions never participate in this decision.
+ */
+export function variantSetFromVertexLayoutProjection(
+  projection: VertexLayoutProjection | undefined,
+  variantSet: string | undefined,
+): Result<string | undefined, PipelineError> {
+  const authoredColor = variantSet
+    ?.split('+')
+    .find((part) => part.startsWith('VERTEX_COLOR_AVAILABLE='));
+  if (authoredColor !== undefined) {
+    const authoredValue = authoredColor.slice('VERTEX_COLOR_AVAILABLE='.length);
+    const authored = authoredValue === 'true';
+    const hasColor = projection?.attributes.some((attribute) => attribute.key === 'color') ?? false;
+    if ((authoredValue !== 'true' && authoredValue !== 'false') || authored !== hasColor) {
+      return err(
+        new PipelineError({
+          code: 'vertex-color-variant-conflict',
+          detail: { authored, authoredValue, projected: hasColor, variantSet: variantSet ?? '' },
+        }),
+      );
+    }
+  }
+  if (projection === undefined) return ok(variantSet);
+  const hasColor = projection.attributes.some((attribute) => attribute.key === 'color');
+  if (hasColor && variantSet === '') return ok('');
+  const parts = (variantSet ?? '')
+    .split('+')
+    .filter((part) => part.length > 0 && !part.startsWith('VERTEX_COLOR_AVAILABLE='));
+  parts.push(`VERTEX_COLOR_AVAILABLE=${hasColor}`);
+  return ok(parts.sort().join('+'));
+}

package/src/pipeline-builder.ts

@@ -0,0 +1,386 @@
+// pipeline-builder.ts -- runtime-internal helper for building per-MaterialShader
+// render pipelines (feat-20260523-shader-template-instance-split M9-T01).
+//
+// Anchors:
+//   - plan-strategy D-PipelineBuilder: M9 introduces a runtime-internal
+//     pipeline builder helper. `render-system-record` calls it once per
+//     `materialShaderId` cache miss; the cache (M9-T03) is owned by the
+//     record stage, not this helper.
+//   - requirements AC-08: record on cache miss correctly constructs pipeline.
+//   - requirements AC-14: the visible-pulse demo's per-frame values.time
+//     mutation depends on a real GPU pipeline being built for the user
+//     shader (`my-game::pulse-material`).
+//   - plan-strategy R-H: pipeline construction must reuse the existing
+//     4-BindGroupLayout chain so existing PBR-heavy demos do not regress.
+//
+// API shape (per plan-task M9-T01 acceptanceCheck):
+//   buildPipelineForMaterialShader(id, entry, ctx) -> Result<RenderPipeline, RhiError>
+//
+// The helper is intentionally **pure**: it does not cache, does not look up
+// the registry, does not maintain state. The caller (render-system-record's
+// per-MaterialShader pipeline cache, M9-T03) is responsible for both the
+// `ShaderRegistry.findMaterialArtifact(id)` call and the
+// `Map<materialShaderId, RenderPipeline>` cache. Splitting the concerns
+// keeps the helper trivially mockable (M9-T02 covers it with vi.fn-based
+// mocks; no real device required).
+//
+// Pipeline shape:
+//   - layout       = caller-supplied PipelineLayout (forgeax R-H: same
+//                    4-BGL chain `[view, material, mesh-array, instances]`
+//                    reused across all MaterialShader entries; D-5 round-4)
+//   - vertex stage = entry.source compiled as a ShaderModule, entry point
+//                    `vs_main`, vertex buffer layout from ctx
+//   - fragment     = same ShaderModule, entry point `fs_main`, color
+//                    attachment format from ctx
+//   - depth        = ctx.depthFormat with `less` compare + `depthWriteEnabled`
+//   - primitive    = `geometry.topology` (default `triangle-list`) + `back`
+//                    cull + `ccw` front face; strip topologies also bake
+//                    `stripIndexFormat`
+//
+// Capability gating: device.caps deviates only at the call site that
+// computes ctx; the helper consumes the resolved `ctx` without further
+// branching (charter P4 consistent abstraction).
+
+import {
+  err,
+  type PipelineLayout,
+  type RenderPipeline,
+  type Result,
+  type RhiDevice,
+  RhiError,
+  type ShaderModule,
+} from '@forgeax/engine-rhi';
+import type { MaterialShaderEntry } from '@forgeax/engine-shader';
+import {
+  AssetError,
+  type MaterialRenderState,
+  type PassKind,
+  type PrimitiveTopology,
+} from '@forgeax/engine-types';
+import {
+  buildPipelineDescriptor,
+  colorFormatsForPassKind,
+  type PipelineSpec,
+} from './pipeline-spec';
+
+/**
+ * feat-20260604-mesh-topology-debug-draw M3 / w8: per-mesh geometry facts that
+ * are baked into the immutable GPURenderPipeline `primitive` block. Distinct
+ * from {@link MaterialRenderState} (material-authored state); these are
+ * geometry properties of the mesh being drawn (requirements D-2 / D-A3).
+ */
+export interface PipelineGeometry {
+  /** Primitive topology baked into `primitive.topology`. Defaults to 'triangle-list'. */
+  readonly topology?: PrimitiveTopology;
+  /**
+   * Index format for strip topologies (`line-strip` / `triangle-strip`), baked
+   * into `primitive.stripIndexFormat`. WebGPU spec: only valid for strip
+   * topologies; ignored (left undefined in the descriptor) for list topologies.
+   */
+  readonly stripIndexFormat?: 'uint16' | 'uint32';
+}
+
+/**
+ * Sync shader-module factory consumed by `buildPipelineForMaterialShader`.
+ * Mirrors `ShaderRegistryDevice.createShaderModule` (sync Result shape) so
+ * the same `makeShaderDeviceAdapter` in `createRenderer.ts` can satisfy
+ * both surfaces (charter P4 consistent abstraction). The adapter caches
+ * the underlying async `pack.createShaderModule` so subsequent sync calls
+ * return cached modules; first call typically returns
+ * `Result.err('rhi-not-available')` while the async build is in flight,
+ * letting the caller fall back to the existing `standardPipeline` for
+ * one frame and retry on the next (matches `render-system-record`'s
+ * 1-frame-warmup idiom).
+ */
+export interface PipelineBuilderShaderModuleFactory {
+  createShaderModule(desc: {
+    readonly code: string;
+    readonly label?: string | undefined;
+  }): Result<ShaderModule, RhiError>;
+}
+
+/**
+ * Build context for `buildPipelineForMaterialShader`. Caller (createRenderer
+ * + render-system-record) computes this once per renderer and reuses across
+ * cache misses; the values mirror the existing PBR pipeline construction
+ * (createRenderer.ts ~line 2712 standardPipelineResult) so user shaders
+ * land on the same 4-BindGroupLayout chain (charter P4 + plan-strategy
+ * R-H).
+ */
+export interface PipelineBuilderContext {
+  /** RHI device that owns the pipeline allocation. */
+  readonly device: RhiDevice;
+  /**
+   * Sync shader-module factory (see {@link PipelineBuilderShaderModuleFactory}).
+   * In production the engine wires the same `makeShaderDeviceAdapter` it
+   * already uses for `ShaderRegistry.get(hash)`; tests pass a
+   * `vi.fn`-based stub.
+   */
+  readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory;
+  /**
+   * Shared pipeline layout (4 BindGroupLayouts: view + material + mesh-array
+   * + instances). User shaders bind through the same slots as
+   * default-standard-pbr; D-5 round-4 SSOT.
+   */
+  readonly pipelineLayout: PipelineLayout;
+  /**
+   * Color attachment format. The LDR / HDR variants pick `bgra8unorm-srgb` /
+   * `rgba16float` respectively; record-stage gate matches the camera's
+   * tonemap field (M9 keeps the LDR shape; HDR variants are OOS-M9).
+   */
+  readonly colorFormat: GPUTextureFormat;
+  /** Depth attachment format, or `undefined` for a color-only pass. */
+  readonly depthFormat: GPUTextureFormat | undefined;
+  /**
+   * Vertex buffer layout descriptors. Procedural geometry uses the 12-floats
+   * stride (position + normal + uv + tangent); user shaders share this
+   * layout for v1 (OOS-9 leaves alternative vertex layouts for a follow-up
+   * feat).
+   */
+  readonly vertexBuffers: readonly GPUVertexBufferLayout[];
+  /** Pipeline label (for GPU debug captures); defaults to `pbr-pipeline-${id}`. */
+  readonly label?: string | undefined;
+  /**
+   * feat-20260604-mesh-topology-debug-draw w16-b: the shader-MODULE cache
+   * identity, decoupled from the PSO `label` and the `id` arg. The WGSL module
+   * depends ONLY on (source + defines), NOT on topology / renderState / isHdr /
+   * indexFormat -- all of which WebGPU bakes into the immutable PSO, never the
+   * module. `makeShaderDeviceAdapter` keys its `moduleCache` on this label, so
+   * passing a stable per-(shader-source, defines) value here lets every
+   * topology / renderState / HDR pipeline variant of the same shader SHARE one
+   * compiled module: the first variant warms it, every later variant reuses it
+   * synchronously (no per-variant async recompile, no event-loop yield).
+   * Falls back to `shader-${id}` when omitted (pre-w16-b behaviour: the `id`
+   * arg doubled as both PSO cache key and module label). The defines dimension
+   * is NOT folded in here because the engine pre-resolves define variants into
+   * distinct registered `source` strings (createRenderer.ts variant
+   * resolution); callers that thread `defines` directly must include them in
+   * `moduleLabel` so two `#define` prefixes do not collide on one module.
+   */
+  readonly moduleLabel?: string | undefined;
+}
+
+/**
+ * Build a render pipeline for a material shader entry. Returns
+ * `Result.err(RhiError)` on shader-module compile failure or pipeline
+ * descriptor rejection (closed union RhiErrorCode pattern; AGENTS.md
+ * "Errors are structured" + charter P3 explicit failure).
+ *
+ * Caller flow (M9-T03):
+ * ```ts
+ * let pipeline = pipelineCache.get(materialShaderId);
+ * if (pipeline === undefined) {
+ *   const lookup = registry.findMaterialArtifact(materialShaderId);
+ *   if (!lookup.ok) {
+ *     // fallback to default-standard-pbr pipelineState.standardPipeline
+ *   } else {
+ *     const built = buildPipelineForMaterialShader(materialShaderId, lookup.value, ctx);
+ *     if (built.ok) pipelineCache.set(materialShaderId, built.value);
+ *     else if (built.error.code === 'rhi-not-available') {
+ *       // shader module still compiling async; retry next frame.
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function buildPipelineForMaterialShader(
+  id: string,
+  entry: MaterialShaderEntry,
+  ctx: PipelineBuilderContext,
+  renderState?: MaterialRenderState,
+  geometry?: PipelineGeometry,
+  vertexEntry?: string,
+  fragmentEntry?: string,
+  defines?: Record<string, string>,
+  passKind: PassKind = 'forward',
+  // bug-20260615 M2 / m2-1: sampleCount is a CAMERA fact (per-frame antialias
+  // setting) threaded from getMaterialShaderPipeline -> buildAndCachePipeline
+  // -> here. Default 1 produces `multisample: undefined` — byte-identical to
+  // the pre-M2 descriptor for every existing count=1 caller. count > 1 sets
+  // `multisample: { count: sampleCount }` matching the `createMsaaVariant`
+  // shape on the built-in geometry side.
+  sampleCount: number = 1,
+): Result<RenderPipeline, RhiError> {
+  const label = ctx.label ?? `pbr-pipeline-${id}`;
+  const vsEntry = vertexEntry ?? (passKind === 'temporal' ? 'vs_temporal' : 'vs_main');
+  const fsEntry =
+    fragmentEntry ??
+    (passKind === 'deferred' ? 'fs_gbuffer' : passKind === 'temporal' ? 'fs_temporal' : 'fs_main');
+
+  let source = entry.source;
+  if (defines !== undefined && Object.keys(defines).length > 0) {
+    const defineKeyRe = /^[A-Z_][A-Z0-9_]*$/;
+    for (const key of Object.keys(defines)) {
+      if (!defineKeyRe.test(key)) {
+        return err(
+          new AssetError({
+            code: 'asset-invalid-value',
+            expected: `define key matching /^[A-Z_][A-Z0-9_]*$/`,
+            hint: `illegal define key '${key}' — must be uppercase letters, digits, and underscores, starting with a letter or underscore`,
+            detail: { key, legalPattern: '^[A-Z_][A-Z0-9_]*$' },
+          }),
+        ) as unknown as ReturnType<typeof buildPipelineForMaterialShader>;
+      }
+    }
+    const prefix = `${Object.entries(defines)
+      .map(([k, v]) => `#define ${k} ${v}`)
+      .join('\n')}\n`;
+    source = prefix + source;
+  }
+
+  const moduleResult = ctx.shaderModuleFactory.createShaderModule({
+    code: source,
+    label: ctx.moduleLabel ?? `shader-${id}`,
+  });
+  if (!moduleResult.ok) {
+    return moduleResult;
+  }
+  const shaderModule = moduleResult.value;
+
+  // feat-20260609 M4 / R3-fixup: shadow-caster branch.
+  // The shadow render pass beginRenderPass desc is `{ colorAttachments: [],
+  // depthStencilAttachment: { format: 'depth32float', ... } }` (see
+  // recordShadowPass / pipelineState.shadowTexture allocation). The PSO's
+  // attachment state must match exactly — no color targets, depth32float
+  // depth — otherwise WebGPU emits "Attachment state of [pipeline] is not
+  // compatible with [RenderPassEncoder]". Ground truth descriptor was the
+  // hardcoded shadowCasterPipeline removed in T-009 (commit 6416e9de~);
+  // this branch reconstructs that exact shape via the lazy cache path.
+  // Vertex layout is position-only (12-float stride, shaderLocation 0 vec3)
+  // — the shadow_caster.wgsl vs_main reads only @location(0) position.
+  if (passKind === 'shadow-caster') {
+    // bug-20260619-csm RC-3 (AC-10): a material may supply a custom
+    // ShadowCaster pass shader that carries a fragment stage (e.g. an
+    // alpha-test cutout that calls `discard` and returns
+    // `@builtin(frag_depth)`). The built-in `forgeax::default-shadow-caster`
+    // is vertex-only — the GPU writes depth from `gl_Position.z` with no
+    // fragment. To run the cutout discard, the PSO MUST include the
+    // fragment stage when the shader declares one; otherwise the fragment
+    // never executes and the shadow comes out solid. The depth pass has no
+    // color attachments, so the fragment stage targets an empty list (it
+    // only writes `@builtin(frag_depth)`).
+    const hasFragmentStage = source.includes('@fragment');
+    const shadowPipelineResult = ctx.device.createRenderPipeline({
+      label,
+      layout: ctx.pipelineLayout as unknown as GPUPipelineLayout,
+      vertex: {
+        module: shaderModule as unknown as GPUShaderModule,
+        entryPoint: vsEntry,
+        buffers: [
+          {
+            arrayStride: 12 * 4,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
+          },
+        ],
+      } as unknown as GPUVertexState,
+      // Vertex-only depth pass writes `fragment: undefined` (GPU derives
+      // depth from gl_Position.z). A custom ShadowCaster shader with a
+      // fragment stage (cutout discard) gets the empty-target fragment
+      // stage so its `discard` / `@builtin(frag_depth)` actually run.
+      fragment: hasFragmentStage
+        ? ({
+            module: shaderModule as unknown as GPUShaderModule,
+            entryPoint: fsEntry,
+            targets: [],
+          } as unknown as GPUFragmentState)
+        : undefined,
+      primitive: {
+        topology: geometry?.topology ?? 'triangle-list',
+        // Shadow caster matrices are allowed to mirror the view basis. A
+        // default back-face cull therefore can reject every projected face
+        // even though the same mesh is visible in the forward pass. Keep
+        // authored culling when a custom ShadowCaster pass requests it, but
+        // make the built-in depth pass two-sided so it always writes the
+        // actual caster geometry into the shadow map.
+        cullMode: renderState?.cullMode ?? 'none',
+        frontFace: renderState?.frontFace ?? 'ccw',
+      },
+      depthStencil: {
+        // depth32float (matches shadow RT format), NOT ctx.depthFormat
+        // (which is depth24plus-stencil8 for the main pass).
+        format: 'depth32float',
+        depthWriteEnabled: true,
+        depthCompare: 'less',
+      },
+      multisample: sampleCount > 1 ? { count: sampleCount } : undefined,
+    });
+    if (!shadowPipelineResult.ok) {
+      if (shadowPipelineResult.error.code === 'shader-compile-failed') {
+        return shadowPipelineResult;
+      }
+      return err(
+        new RhiError({
+          code: 'shader-compile-failed',
+          expected: `shadow-caster pipeline for material shader '${id}' builds successfully`,
+          hint: `inspect compiler messages on the shader module; verify pipeline layout matches shader bindings (cause: ${shadowPipelineResult.error.code})`,
+        }),
+      );
+    }
+    return shadowPipelineResult;
+  }
+
+  // feat-20260615-pipeline-spec-ssot M2-T3: delegate PSO descriptor assembly
+  // to buildPipelineDescriptor(spec, modules). The spec is derived from the
+  // forward-branch parameters; multisample is derived from sampleCount (1 → absent,
+  // 4 → {count:4}). This replaces the inline literal formerly at :290-344.
+  const forwardSpec: PipelineSpec = {
+    shader: { id, passKind, variantSet: undefined },
+    attachments: {
+      colorFormats: colorFormatsForPassKind(passKind, ctx.colorFormat),
+      depthFormat: ctx.depthFormat,
+      sampleCount: (sampleCount === 4 ? 4 : 1) as 1 | 4,
+    },
+    geometry: {
+      topology: geometry?.topology ?? 'triangle-list',
+      stripIndexFormat: geometry?.stripIndexFormat,
+      vertexLayout: {}, // vertexLayout not used at this layer; caller provides vertexBuffers
+    },
+    renderState,
+  };
+  const baseDesc = buildPipelineDescriptor(forwardSpec, {
+    vertex: shaderModule,
+    fragment: shaderModule,
+  }) as Record<string, unknown>;
+
+  // Merge pipeline-builder-specific fields (label, layout, vertexBuffers, entryPoint names)
+  const pipelineResult = ctx.device.createRenderPipeline({
+    label,
+    layout: ctx.pipelineLayout as unknown as GPUPipelineLayout,
+    vertex: {
+      ...(baseDesc.vertex as Record<string, unknown>),
+      entryPoint: vsEntry,
+      buffers: ctx.vertexBuffers as unknown as GPUVertexBufferLayout[],
+    } as unknown as GPUVertexState,
+    fragment: (baseDesc.fragment !== undefined
+      ? {
+          ...(baseDesc.fragment as Record<string, unknown>),
+          entryPoint: fsEntry,
+        }
+      : undefined) as unknown as GPUFragmentState,
+    primitive: baseDesc.primitive as unknown as GPUPrimitiveState,
+    ...(baseDesc.depthStencil !== undefined
+      ? { depthStencil: baseDesc.depthStencil as unknown as GPUDepthStencilState }
+      : {}),
+    ...(baseDesc.multisample !== undefined
+      ? { multisample: baseDesc.multisample as unknown as GPUMultisampleState }
+      : {}),
+  });
+
+  if (!pipelineResult.ok) {
+    // Wrap the underlying RhiError with a `shader-compile-failed` envelope
+    // when the originating code is not already canonical -- this preserves
+    // the canonical error code consumers expect at the standard-pipeline
+    // build site (createRenderer.ts standardPipelineResult).
+    if (pipelineResult.error.code === 'shader-compile-failed') {
+      return pipelineResult;
+    }
+    return err(
+      new RhiError({
+        code: 'shader-compile-failed',
+        expected: `pipeline for material shader '${id}' builds successfully`,
+        hint: `inspect compiler messages on the shader module; verify pipeline layout matches shader bindings (cause: ${pipelineResult.error.code})`,
+      }),
+    );
+  }
+  return pipelineResult;
+}

package/src/pipeline-errors.ts

@@ -0,0 +1,172 @@
+// @forgeax/engine-runtime - render-pipeline error model
+// (feat-20260601-customizable-render-pipeline-seam-and-dogfood-rend M1 / w4).
+//
+// Closed PipelineErrorCode union + PipelineError discriminated-union class.
+// failure channels split by error nature (charter P3 + plan-strategy D-E):
+//   - 'pipeline-already-registered' (programmer error) -> registerPipeline THROWS a
+//     PipelineError, mirroring ShaderRegistry.installMaterialArtifact's Map.has -> throw
+//     fail-fast (research Finding 3). A second register under the same id is a coding
+//     mistake that must surface immediately.
+//   - 'pipeline-not-found' (runtime path) -> installPipeline returns Result.err with this
+//     code when the supplied handle resolves to no registered pipeline (stale / wrong
+//     handle). AI users branch on `err.code === 'pipeline-not-found'` by property access.
+//
+// D-1: a NEW independent union rather than folding into RuntimeErrorCode /
+// RenderGraphErrorCode (requirements OOS-6). RuntimeErrorCode's members are render / skin
+// / shadow domain; a separate union keeps the pipeline error surface cohesive and
+// additively evolvable (mirrors pick-errors.ts D-1 reasoning verbatim).
+//
+// PipelineError is exposed as a discriminated union (variant per code, AppError pattern)
+// so `if (err.code === 'X')` simultaneously narrows `err.detail` to the per-code payload.
+//
+// Related: requirements M1 item 8 + AC-05 / AC-06; plan-strategy D-E; charter P3 / P4.
+
+/**
+ * Closed union of render-pipeline error codes.
+ *
+ * AI users perform exhaustive `switch (err.code)` without a default and TS guards
+ * completeness (AC-05).
+ *
+ * | code | channel | trigger |
+ * |:--|:--|:--|
+ * | `'pipeline-already-registered'` | throw | a second `registerPipeline(id, impl)` under an already-registered `id` |
+ * | `'pipeline-not-found'` | `Result.err` | `installPipeline(handle)` where the handle resolves to no registered pipeline |
+ */
+export type PipelineErrorCode = keyof typeof PIPELINE_POLICY;
+
+/**
+ * Detail for `'pipeline-already-registered'`: the pipeline id that was already taken.
+ * AI consumers read `.detail.id` by property access (charter P4), no message parsing.
+ */
+export interface PipelinePreviouslyRegisteredDetail {
+  readonly id: string;
+}
+
+/**
+ * Detail for `'pipeline-not-found'`: the raw u32 handle value that resolved to no
+ * registered pipeline. Read via `.detail.handle` after the code guard.
+ */
+export interface PipelineNotFoundDetail {
+  readonly handle: number;
+}
+
+export interface VertexColorVariantConflictDetail {
+  readonly authored: boolean;
+  readonly authoredValue: string;
+  readonly projected: boolean;
+  readonly variantSet: string;
+}
+
+/**
+ * Conditional resolver from `PipelineErrorCode` to its detail payload type. Used by the
+ * constructor signature so `new PipelineError({ code: 'X', detail })` narrows the
+ * `detail` parameter to the variant payload at compile time.
+ */
+export type PipelineErrorDetailFor<C extends PipelineErrorCode> =
+  C extends 'pipeline-already-registered'
+    ? PipelinePreviouslyRegisteredDetail
+    : C extends 'pipeline-not-found'
+      ? PipelineNotFoundDetail
+      : C extends 'vertex-color-variant-conflict'
+        ? VertexColorVariantConflictDetail
+        : never;
+
+/**
+ * Tagged union of `.detail` payloads. The variants are unique by structural fields
+ * (`{ id }` vs `{ handle }`).
+ */
+export type PipelineErrorDetail = PipelineErrorDetailFor<PipelineErrorCode>;
+
+const PIPELINE_POLICY = {
+  'pipeline-already-registered': {
+    expected: 'each pipeline id is registered at most once',
+    hint: (detail) =>
+      `pipeline id '${(detail as PipelinePreviouslyRegisteredDetail).id}' is already ` +
+      'registered; same-id re-register is forbidden. Pick a distinct id ' +
+      '(engine builtins use the forgeax:: prefix; user pipelines use <package>::<id>).',
+  },
+  'pipeline-not-found': {
+    expected: 'installPipeline receives a handle to a registered pipeline',
+    hint: (detail) =>
+      `no pipeline is registered for handle ${(detail as PipelineNotFoundDetail).handle}. ` +
+      'First registerPipeline(id, impl), then register a RenderPipelineAsset ' +
+      '{ kind:"render-pipeline", pipelineId: id } and install the returned handle.',
+  },
+  'vertex-color-variant-conflict': {
+    expected: 'geometry projection and material variant agree on VERTEX_COLOR_AVAILABLE',
+    hint: (detail) =>
+      `authored VERTEX_COLOR_AVAILABLE=${(detail as VertexColorVariantConflictDetail).authoredValue} conflicts with ` +
+      `geometry projection=${(detail as VertexColorVariantConflictDetail).projected} in variant set '${(detail as VertexColorVariantConflictDetail).variantSet}'. ` +
+      'Remove the authored vertex-color axis and let geometry projection derive it.',
+  },
+} satisfies Record<
+  string,
+  {
+    readonly expected: string;
+    readonly hint: (detail: unknown) => string;
+  }
+>;
+
+class PipelineErrorClass extends Error {
+  readonly code: PipelineErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PipelineErrorDetail;
+
+  constructor(args: { code: PipelineErrorCode; detail: PipelineErrorDetail }) {
+    const policy = PIPELINE_POLICY[args.code];
+    const hint = policy.hint(args.detail);
+    super(`pipeline: ${args.code} (${hint})`);
+    this.name = 'PipelineError';
+    this.code = args.code;
+    this.expected = policy.expected;
+    this.hint = hint;
+    this.detail = args.detail;
+  }
+}
+
+/**
+ * Variant intersection: a `PipelineErrorClass` instance whose `code` literal narrows to
+ * `C` and whose `detail` narrows to `PipelineErrorDetailFor<C>`, so `if (err.code === 'X')`
+ * simultaneously narrows `err.detail` (charter P3 + P4 discriminated union).
+ */
+type PipelineErrorVariant<C extends PipelineErrorCode> = PipelineErrorClass & {
+  readonly code: C;
+  readonly detail: PipelineErrorDetailFor<C>;
+};
+
+/**
+ * Public PipelineError type - discriminated union of the 2 variants.
+ *
+ * ```ts
+ * function recover(err: PipelineError): string {
+ *   switch (err.code) {
+ *     case 'pipeline-already-registered': return `id taken: ${err.detail.id}`;
+ *     case 'pipeline-not-found':          return `bad handle: ${err.detail.handle}`;
+ *   }
+ * }
+ * ```
+ */
+export type PipelineError = {
+  [C in PipelineErrorCode]: PipelineErrorVariant<C>;
+}[PipelineErrorCode];
+
+interface PipelineErrorConstructor {
+  new <C extends PipelineErrorCode>(args: {
+    code: C;
+    detail: PipelineErrorDetailFor<C>;
+  }): PipelineErrorVariant<C>;
+  readonly prototype: PipelineErrorClass;
+}
+
+/**
+ * PipelineError constructor - `new PipelineError({ code, detail })`.
+ *
+ * The generic `C` is inferred from the literal `code` argument, which narrows `detail` to
+ * the per-code payload (`PipelineErrorDetailFor<C>`) and narrows the return type to the
+ * corresponding `PipelineErrorVariant<C>` so the call site walks the discriminated union
+ * without manual cast (AppError pattern; TS class declarations cannot directly express
+ * `<C> ... PipelineErrorVariant<C>` polymorphism, hence the typed-cast affordance).
+ */
+export const PipelineError: PipelineErrorConstructor =
+  PipelineErrorClass as unknown as PipelineErrorConstructor;