@forgeax/engine-rhi-null 0.0.0-dev.8d955ade1c79

package/src/device.ts

@@ -0,0 +1,258 @@
+// @forgeax/engine-rhi-null/src/device - RhiNullDevice + caps for the headless
+// no-op backend.
+//
+// RhiNullDevice implements the full RhiDevice surface (research Finding A1
+// row 3) as no-ops that mint legal opaque-handle brands and thread them through
+// the per-device Bookkeeper (method A; research Finding A6). The `implements
+// RhiDevice` clause is the completeness guard: a missing method is a tsc -b
+// red, satisfying AC-01 without a hand-maintained member checklist.
+//
+// caps (D-5): backendKind 'null'; the 3 wgpu-native-only reserved flags
+// (multiDrawIndirect / pushConstants / textureBindingArray) are false; every
+// other boolean cap is true and maxColorAttachments is 8, so the headless
+// backend maximizes structural coverage of capability-gated paths.
+//
+// The queue is supplied at construction (the adapter's requestDevice mints the
+// RhiNullQueue, w10) so device.ts carries no dependency on queue.ts.
+//
+// Related: requirements scope row 2 (8 interfaces full method set) + AC-01
+// (implements compiles) + AC-08 (backendKind === 'null'); plan-strategy §2 D-5
+// (caps field-level) + §4 R-3; research Finding A1 + A6.
+
+import type {
+  BindGroup,
+  BindGroupDescriptor,
+  BindGroupLayout,
+  BindGroupLayoutDescriptor,
+  Buffer,
+  BufferDescriptor,
+  CommandEncoderDescriptor,
+  ComputePipeline,
+  ComputePipelineDescriptor,
+  PipelineLayout,
+  PipelineLayoutDescriptor,
+  QuerySet,
+  QuerySetDescriptor,
+  RenderPipeline,
+  RenderPipelineDescriptor,
+  Result,
+  RhiCaps,
+  RhiCommandEncoder,
+  RhiComputePipelineOps,
+  RhiDevice,
+  RhiError as RhiErrorType,
+  RhiFeatures,
+  RhiLimits,
+  RhiQueue,
+  RhiRenderPipelineOps,
+  Sampler,
+  SamplerDescriptor,
+  Texture,
+  TextureDescriptor,
+  TextureView,
+  TextureViewDescriptor,
+} from '@forgeax/engine-rhi';
+import { RhiError as RhiErrorClass } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { Bookkeeper } from './bookkeeping';
+
+/** Monotonic device-id source so each RhiNullDevice owns a distinct id; the id
+ *  threads into the Bookkeeper for cross-device handle-chain validation. */
+let nextDeviceId = 0;
+
+/**
+ * Factory that builds a command encoder bound to a device's ledger. Injected at
+ * device construction (rather than imported here) so device.ts carries no
+ * dependency on command-encoder.ts; the singleton assembly (index.ts) supplies
+ * the real factory. The Bookkeeper and RhiNullDevice are passed so the encoder
+ * threads draw / dispatch counts + binding validation through the same per-device
+ * ledger AND writes aggregated frame stats to the device for M3 unit-test readback.
+ */
+export type CommandEncoderFactory = (
+  bookkeeper: Bookkeeper,
+  device: RhiNullDevice,
+) => RhiCommandEncoder;
+
+/** A pipeline brand augmented with its no-op `getBindGroupLayout` ops method
+ *  (D-2). createRenderPipeline / createComputePipeline return objects of this
+ *  shape so the auto-layout consumers can call getBindGroupLayout. */
+type PipelineHandle<Brand> = Brand & RhiRenderPipelineOps & RhiComputePipelineOps;
+
+/**
+ * Headless no-op RhiDevice. Every create* mints a legal brand and records it;
+ * every destroy* fail-fasts a double-destroy; caps reports the all-true-except-
+ * reserved profile (D-5).
+ */
+export class RhiNullDevice implements RhiDevice {
+  private readonly internalBookkeeper: Bookkeeper;
+  private readonly nullQueue: RhiQueue;
+  private readonly encoderFactory: CommandEncoderFactory;
+
+  /** Per-frame total draw count across all pass encoders executed this frame
+   *  (aggregated by the command encoder on finish, then reset). M3 unit tests
+   *  (w17) read this to assert draw count >= 1 (AC-06). */
+  totalDrawCount = 0;
+  /** Per-frame total direct and indirect compute dispatch count. */
+  totalDispatchCount = 0;
+  /** Per-frame total bind group set count (AC-06 / AC-05 readback). */
+  totalBindGroupCount = 0;
+  /** Per-frame pass names executed this frame, in schedule order (AC-04). */
+  framePassNames: string[] = [];
+
+  /** The per-device handle ledger — exposed so M3 tests can assert create/destroy
+   *  pairing and BGL/PSO shape counts (AC-05/06/07). */
+  get bookkeeper(): Bookkeeper {
+    return this.internalBookkeeper;
+  }
+
+  constructor(queue: RhiQueue, encoderFactory: CommandEncoderFactory) {
+    this.internalBookkeeper = new Bookkeeper(nextDeviceId++);
+    this.nullQueue = queue;
+    this.encoderFactory = encoderFactory;
+  }
+
+  get caps(): RhiCaps {
+    return {
+      backendKind: 'null',
+      compute: true,
+      timestampQuery: false,
+      timestampPeriodNanoseconds: null,
+      indirectDrawing: true,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      // 3 wgpu-native-only reserved flags stay false on non-native backends
+      // (D-5); the headless backend is not a native runtime.
+      multiDrawIndirect: false,
+      pushConstants: false,
+      textureBindingArray: false,
+      samplerAliasing: true,
+      firstInstanceIndirect: true,
+      storageBuffer: true,
+      storageTexture: true,
+      rgba16floatRenderable: true,
+      rg11b10ufloatRenderable: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+    };
+  }
+
+  get features(): RhiFeatures {
+    return EMPTY_FEATURES;
+  }
+
+  get limits(): RhiLimits {
+    return EMPTY_LIMITS;
+  }
+
+  get queue(): RhiQueue {
+    return this.nullQueue;
+  }
+
+  // forgeax-async-whitelist: dom-native — spec `GPUDevice.lost` Promise
+  // passthrough. The headless backend never loses a device (no GPU), so the
+  // Promise stays unsettled for the lifetime of the device, mirroring a live
+  // device that never transitions to the lost state.
+  get lost(): Promise<{ readonly reason: 'destroyed' | 'unknown'; readonly message: string }> {
+    return NEVER;
+  }
+
+  createBuffer(_desc: BufferDescriptor): Result<Buffer, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('Buffer') as unknown as Buffer);
+  }
+
+  createTexture(_desc: TextureDescriptor): Result<Texture, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('Texture') as unknown as Texture);
+  }
+
+  destroyBuffer(buf: Buffer): Result<void, RhiErrorType> {
+    return this.internalBookkeeper.destroy(buf);
+  }
+
+  destroyQuerySet(querySet: QuerySet): Result<void, RhiErrorType> {
+    return this.internalBookkeeper.destroy(querySet);
+  }
+
+  destroyTexture(tex: Texture): Result<void, RhiErrorType> {
+    return this.internalBookkeeper.destroy(tex);
+  }
+
+  createTextureView(
+    _texture: Texture,
+    _desc: TextureViewDescriptor,
+  ): Result<TextureView, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('TextureView') as unknown as TextureView);
+  }
+
+  createSampler(_desc?: SamplerDescriptor | undefined): Result<Sampler, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('Sampler') as unknown as Sampler);
+  }
+
+  createBindGroupLayout(_desc: BindGroupLayoutDescriptor): Result<BindGroupLayout, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('BindGroupLayout') as unknown as BindGroupLayout);
+  }
+
+  createBindGroup(_desc: BindGroupDescriptor): Result<BindGroup, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('BindGroup') as unknown as BindGroup);
+  }
+
+  createPipelineLayout(_desc: PipelineLayoutDescriptor): Result<PipelineLayout, RhiErrorType> {
+    return ok(this.internalBookkeeper.register('PipelineLayout') as unknown as PipelineLayout);
+  }
+
+  createRenderPipeline(_desc: RenderPipelineDescriptor): Result<RenderPipeline, RhiErrorType> {
+    return ok(this.makePipeline<RenderPipeline>('RenderPipeline'));
+  }
+
+  createComputePipeline(_desc: ComputePipelineDescriptor): Result<ComputePipeline, RhiErrorType> {
+    return ok(this.makePipeline<ComputePipeline>('ComputePipeline'));
+  }
+
+  createQuerySet(desc: QuerySetDescriptor): Result<QuerySet, RhiErrorType> {
+    if (desc.type === 'timestamp') {
+      return err(
+        new RhiErrorClass({
+          code: 'feature-not-enabled',
+          expected: 'caps.timestampQuery === true (timestamp-query feature)',
+          hint: 'RhiNull is structural-only and cannot produce GPU timestamp ticks',
+        }),
+      );
+    }
+    return ok(this.internalBookkeeper.register('QuerySet') as unknown as QuerySet);
+  }
+
+  createCommandEncoder(
+    _desc?: CommandEncoderDescriptor | undefined,
+  ): Result<RhiCommandEncoder, RhiErrorType> {
+    return ok(this.encoderFactory(this.internalBookkeeper, this));
+  }
+
+  /**
+   * Mint a pipeline handle whose object also carries the no-op
+   * `getBindGroupLayout(index)` ops method (D-2). The prod auto-layout path
+   * (debug-draw.ts) and the existing mock unit tests both call
+   * `pipeline.getBindGroupLayout(n)`; returning a legal BindGroupLayout brand
+   * (recorded in the ledger) keeps those consumers from crashing on a missing
+   * method.
+   */
+  private makePipeline<Brand>(kind: string): PipelineHandle<Brand> {
+    const handle = this.internalBookkeeper.register(kind);
+    const getBindGroupLayout = (_index: number): BindGroupLayout =>
+      this.internalBookkeeper.register('BindGroupLayout') as unknown as BindGroupLayout;
+    return Object.assign(handle, { getBindGroupLayout }) as unknown as PipelineHandle<Brand>;
+  }
+}
+
+/** Empty enabled-feature set — headless backend enables nothing beyond the
+ *  always-true caps profile (research Finding A1: features getter returns an
+ *  empty ReadonlySet). */
+const EMPTY_FEATURES: RhiFeatures = new Set() as RhiFeatures;
+
+/** Empty numeric-limits map. The headless backend reports no concrete numeric
+ *  limits; capability planning reads caps booleans instead. */
+const EMPTY_LIMITS: RhiLimits = {} as RhiLimits;
+
+/** A Promise that never settles, mirroring a live GPUDevice.lost that stays
+ *  unsettled while the device is healthy. */
+const NEVER: Promise<{ readonly reason: 'destroyed' | 'unknown'; readonly message: string }> =
+  new Promise(() => {});

package/src/index.ts

@@ -0,0 +1,63 @@
+// @forgeax/engine-rhi-null - headless no-op RHI backend.
+//
+// Single entry for `import { rhi } from '@forgeax/engine-rhi-null'`. The
+// exported `rhi` singleton has the RhiBackendPack-mandated shape
+// `RhiInstance & { acquireCanvasContext }` (research Finding A4 — Channel 1
+// injects this verbatim and calls acquireCanvasContext on the facade, so the
+// method MUST exist on the singleton even though the public renderer options.rhi
+// type does not require it). createShaderModule is exposed at the top level
+// (R-2) for symmetry with rhi-webgpu: createRenderer's ready chain resolves the
+// shader step through `RhiBackendPack.createShaderModule`, otherwise it rejects
+// rhi-not-available.
+//
+// Strict two-step path: rhi.requestAdapter() -> adapter.requestDevice().
+//
+// Related: requirements AC-02 + AC-10 + AC-12 + scope row 4; research Finding
+// A1 row 1 + A4 + A5; plan-strategy §4 R-1 + R-2.
+
+import type {
+  RequestAdapterOptions,
+  Result,
+  RhiAdapter,
+  RhiError as RhiErrorType,
+  RhiInstance,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { RhiNullAdapter } from './adapter';
+import { acquireCanvasContext } from './canvas-context';
+import { createShaderModule } from './shader';
+
+/**
+ * Request a headless adapter. The two-positional-arg signature mirrors the spec
+ * RhiInstance.requestAdapter (the second compatibleSurface arg is accepted and
+ * ignored — there is no GL backend to route it to).
+ */
+function requestAdapter(
+  _opts?: RequestAdapterOptions | undefined,
+  _compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined,
+): Promise<Result<RhiAdapter, RhiErrorType>> {
+  return Promise.resolve(ok(new RhiNullAdapter()));
+}
+
+/**
+ * The `rhi` singleton — RhiBackendPack-shaped entry for Channel 1 injection
+ * (`createRenderer(canvas, { rhi })`). Carries acquireCanvasContext (R-1) so
+ * the facade never crashes on a missing method, and createShaderModule (R-2) so
+ * the ready chain's shader step resolves rather than rejecting.
+ */
+export const rhi: RhiInstance & {
+  acquireCanvasContext: typeof acquireCanvasContext;
+  createShaderModule: typeof createShaderModule;
+} = {
+  requestAdapter,
+  acquireCanvasContext,
+  createShaderModule,
+};
+
+export { RhiNullAdapter } from './adapter';
+export { acquireCanvasContext, RhiNullCanvasContext } from './canvas-context';
+export { RhiNullCommandEncoder } from './command-encoder';
+export { RhiNullDevice } from './device';
+export { RhiNullComputePassEncoder, RhiNullRenderPassEncoder } from './pass-encoders';
+export { RhiNullQueue } from './queue';
+export { createShaderModule } from './shader';

package/src/pass-encoders.ts

@@ -0,0 +1,211 @@
+// @forgeax/engine-rhi-null/src/pass-encoders - headless render / compute pass
+// encoders.
+//
+// Both encoders are no-ops that thread state changes through nothing real; the
+// only side effects are command-stream bookkeeping the M3 unit tests read back:
+//   - draw / drawIndexed / drawIndirect / drawIndexedIndirect bump a draw
+//     counter (AC-06);
+//   - dispatchWorkgroups bumps a dispatch counter;
+//   - setVertexBuffer / setBindGroup validate handle ownership against the
+//     issuing device's ledger (AC-09 handle-chain consistency) and record the
+//     outcome so an assertion can read the most recent validation result
+//     without the call site throwing (the spec method form is void).
+//
+// Counters + last-validation live on the encoder instance (public readonly) so
+// a test holding the pass encoder reads them directly; the per-device ledger
+// (Bookkeeper) supplies cross-device validation.
+//
+// Related: requirements AC-04 (pass sequence) + AC-06 (draw count + binding
+// assembly) + AC-09 (handle-chain consistency); research Finding A1 rows 6/7;
+// plan-strategy §3.1 (pass encoder bookkeeping design) + §2 D-1.
+
+import type {
+  BindGroup,
+  Buffer,
+  ComputePipeline,
+  RenderPipeline,
+  Result,
+  RhiComputePassEncoder,
+  RhiError as RhiErrorType,
+  RhiRenderPassEncoder,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import type { Bookkeeper } from './bookkeeping';
+
+/** Shared counter interface that pass encoders bump so the device can aggregate
+ *  per-frame stats for M3 unit-test readback. */
+export interface PassCounter {
+  recordDraw(): void;
+  recordDispatch(): void;
+  recordBindGroup(): void;
+  recordPassName(name: string): void;
+}
+
+/**
+ * Headless render pass encoder. Records draw counts + the most recent handle
+ * validation outcome; all state-setting methods are no-ops.
+ */
+export class RhiNullRenderPassEncoder implements RhiRenderPassEncoder {
+  /** Number of draw* calls issued on this pass (AC-06 readback). */
+  drawCount = 0;
+  bindGroupCount = 0;
+  /** Most recent setVertexBuffer / setBindGroup ownership validation; ok unless
+   *  a foreign handle was passed (AC-09 readback). */
+  lastValidation: Result<unknown, RhiErrorType> = ok(undefined);
+
+  private readonly bookkeeper: Bookkeeper;
+  private readonly counter: PassCounter | null;
+  readonly passName: string;
+
+  constructor(bookkeeper: Bookkeeper, counter: PassCounter | null, passName: string) {
+    this.bookkeeper = bookkeeper;
+    this.counter = counter;
+    this.passName = passName;
+  }
+
+  setPipeline(_pipeline: RenderPipeline): void {}
+
+  setVertexBuffer(
+    _slot: number,
+    buffer: Buffer,
+    _offset?: number | undefined,
+    _size?: number | undefined,
+  ): void {
+    this.lastValidation = this.bookkeeper.validateOwnership(buffer);
+  }
+
+  setIndexBuffer(
+    _buffer: Buffer,
+    _format: 'uint16' | 'uint32',
+    _offset?: number | undefined,
+    _size?: number | undefined,
+  ): void {}
+
+  setBindGroup(
+    _index: number,
+    bindGroup: BindGroup,
+    _dynamicOffsetsData?: readonly number[] | Uint32Array | undefined,
+    _dynamicOffsetsDataStart?: number | undefined,
+    _dynamicOffsetsDataLength?: number | undefined,
+  ): void {
+    this.bindGroupCount++;
+    this.counter?.recordBindGroup();
+    this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
+  }
+
+  draw(
+    _vertexCount: number,
+    _instanceCount?: number | undefined,
+    _firstVertex?: number | undefined,
+    _firstInstance?: number | undefined,
+  ): void {
+    this.drawCount++;
+    this.counter?.recordDraw();
+  }
+
+  drawIndexed(
+    _indexCount: number,
+    _instanceCount?: number | undefined,
+    _firstIndex?: number | undefined,
+    _baseVertex?: number | undefined,
+    _firstInstance?: number | undefined,
+  ): void {
+    this.drawCount++;
+    this.counter?.recordDraw();
+  }
+
+  end(): void {
+    this.counter?.recordPassName(this.passName);
+  }
+
+  setViewport(
+    _x: number,
+    _y: number,
+    _w: number,
+    _h: number,
+    _minDepth: number,
+    _maxDepth: number,
+  ): void {}
+
+  setScissorRect(_x: number, _y: number, _w: number, _h: number): void {}
+
+  setBlendConstant(_color: GPUColor): void {}
+
+  setStencilReference(_reference: number): void {}
+
+  drawIndirect(_indirectBuffer: Buffer, _indirectOffset: number): void {
+    this.drawCount++;
+    this.counter?.recordDraw();
+  }
+
+  drawIndexedIndirect(_indirectBuffer: Buffer, _indirectOffset: number): void {
+    this.drawCount++;
+    this.counter?.recordDraw();
+  }
+
+  pushDebugGroup(_groupLabel: string): void {}
+
+  popDebugGroup(): void {}
+
+  insertDebugMarker(_markerLabel: string): void {}
+
+  executeBundles(_bundles: Iterable<unknown>): Result<void, RhiErrorType> {
+    // Headless no-op: executing zero bundles against no GPU succeeds vacuously
+    // (plan-strategy §3.1 — pass-encoder Result methods return ok(void)).
+    return ok(undefined);
+  }
+
+  beginOcclusionQuery(_queryIndex: number): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  endOcclusionQuery(): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+}
+
+/**
+ * Headless compute pass encoder. Records dispatch counts; all state-setting
+ * methods are no-ops.
+ */
+export class RhiNullComputePassEncoder implements RhiComputePassEncoder {
+  /** Number of dispatchWorkgroups calls issued on this pass (readback). */
+  dispatchCount = 0;
+  /** Most recent setBindGroup ownership validation (AC-09 readback). */
+  lastValidation: Result<unknown, RhiErrorType> = ok(undefined);
+
+  private readonly bookkeeper: Bookkeeper;
+  private readonly counter: PassCounter | null;
+  readonly passName: string;
+
+  constructor(bookkeeper: Bookkeeper, counter: PassCounter | null, passName: string) {
+    this.bookkeeper = bookkeeper;
+    this.counter = counter;
+    this.passName = passName;
+  }
+
+  setPipeline(_pipeline: ComputePipeline): void {}
+
+  setBindGroup(
+    _index: number,
+    bindGroup: BindGroup,
+    _dynamicOffsets?: readonly number[] | undefined,
+  ): void {
+    this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
+  }
+
+  dispatchWorkgroups(_x: number, _y?: number | undefined, _z?: number | undefined): void {
+    this.dispatchCount++;
+    this.counter?.recordDispatch();
+  }
+
+  dispatchWorkgroupsIndirect(indirectBuffer: Buffer, _indirectOffset: number): void {
+    this.lastValidation = this.bookkeeper.validateOwnership(indirectBuffer);
+    this.dispatchCount++;
+    this.counter?.recordDispatch();
+  }
+
+  end(): void {
+    this.counter?.recordPassName(this.passName);
+  }
+}

package/src/queue.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-rhi-null/src/queue - headless command queue.
+//
+// All write* methods are no-ops returning ok; submit records nothing and
+// returns ok (AC-12). onSubmittedWorkDone resolves immediately so headless
+// read-back idioms never hang (the real GPU resolves after work completes; with
+// no pending work the headless backend resolves synchronously).
+//
+// Related: requirements AC-12 (submit ok + onSubmittedWorkDone resolves);
+// research Finding A1 row 4.
+
+import type {
+  Buffer,
+  CommandBuffer,
+  ExternalImageTextureDestination,
+  Result,
+  RhiError as RhiErrorType,
+  RhiQueue,
+  TextureWriteDestination,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+
+/** Headless no-op queue. */
+export class RhiNullQueue implements RhiQueue {
+  writeBuffer(
+    _buffer: Buffer,
+    _bufferOffset: number,
+    _data: ArrayBufferView | ArrayBuffer,
+    _dataOffset?: number | undefined,
+    _size?: number | undefined,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  writeTexture(
+    _destination: TextureWriteDestination,
+    _data: ArrayBufferView | ArrayBuffer,
+    _dataLayout: Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>,
+    _size: GPUExtent3DStrict,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  copyExternalImageToTexture(
+    _source: Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>,
+    _destination: ExternalImageTextureDestination,
+    _copySize: GPUExtent3DStrict,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  submit(_commandBuffers: readonly CommandBuffer[]): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  // forgeax-async-whitelist: dom-native — spec `GPUQueue.onSubmittedWorkDone`
+  // never rejects. The headless backend has no pending GPU work, so it resolves
+  // immediately (AC-12: read-back idioms must not hang).
+  onSubmittedWorkDone(): Promise<undefined> {
+    return Promise.resolve(undefined);
+  }
+}

package/src/shader.ts

@@ -0,0 +1,37 @@
+// @forgeax/engine-rhi-null/src/shader - headless shader module factory (R-2).
+//
+// createShaderModule is the highest-risk hidden contract: the createRenderer
+// ready chain resolves a shader module through a three-tier fallback
+// (RhiBackendPack.createShaderModule -> RhiDevice.createShaderModule duck-typed
+// -> err('rhi-not-available')). If RhiNull provides neither, createRenderer ->
+// ready REJECTS rhi-not-available and AC-02 / AC-10 / AC-13 all fail. RhiNull
+// exposes the top-level async factory (symmetric with rhi-webgpu) that skips
+// real WGSL compilation and returns a legal ShaderModule brand.
+//
+// Related: requirements AC-10 (shader brand skips compile) + AC-02
+// (createRenderer ready does not reject); research Finding A5 (three-tier
+// fallback, top-level factory recommended) + A6 (brand construction);
+// plan-strategy §4 R-2.
+
+import type {
+  Result,
+  RhiDevice,
+  RhiError as RhiErrorType,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+
+/**
+ * Build a shader module for the headless backend. No WGSL is compiled — the
+ * code is ignored and a legal ShaderModule brand is returned immediately
+ * (<1ms), so the ready chain's shader step always resolves ok (AC-10). Mirrors
+ * the rhi-webgpu top-level `createShaderModule(device, desc)` signature so
+ * Channel 1's RhiBackendPack picks it up via the same `'createShaderModule' in
+ * mod` probe.
+ */
+export function createShaderModule(
+  _device: RhiDevice,
+  _desc: { label?: string | undefined; code: string },
+): Promise<Result<ShaderModule, RhiErrorType>> {
+  return Promise.resolve(ok({} as unknown as ShaderModule));
+}