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

package/dist/pass-encoders.d.ts

@@ -0,0 +1,65 @@
+import type { BindGroup, Buffer, ComputePipeline, RenderPipeline, Result, RhiComputePassEncoder, RhiError as RhiErrorType, RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+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 declare class RhiNullRenderPassEncoder implements RhiRenderPassEncoder {
+    /** Number of draw* calls issued on this pass (AC-06 readback). */
+    drawCount: number;
+    bindGroupCount: number;
+    /** Most recent setVertexBuffer / setBindGroup ownership validation; ok unless
+     *  a foreign handle was passed (AC-09 readback). */
+    lastValidation: Result<unknown, RhiErrorType>;
+    private readonly bookkeeper;
+    private readonly counter;
+    readonly passName: string;
+    constructor(bookkeeper: Bookkeeper, counter: PassCounter | null, passName: string);
+    setPipeline(_pipeline: RenderPipeline): void;
+    setVertexBuffer(_slot: number, buffer: Buffer, _offset?: number | undefined, _size?: number | undefined): void;
+    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;
+    draw(_vertexCount: number, _instanceCount?: number | undefined, _firstVertex?: number | undefined, _firstInstance?: number | undefined): void;
+    drawIndexed(_indexCount: number, _instanceCount?: number | undefined, _firstIndex?: number | undefined, _baseVertex?: number | undefined, _firstInstance?: number | undefined): void;
+    end(): void;
+    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;
+    drawIndexedIndirect(_indirectBuffer: Buffer, _indirectOffset: number): void;
+    pushDebugGroup(_groupLabel: string): void;
+    popDebugGroup(): void;
+    insertDebugMarker(_markerLabel: string): void;
+    executeBundles(_bundles: Iterable<unknown>): Result<void, RhiErrorType>;
+    beginOcclusionQuery(_queryIndex: number): Result<void, RhiErrorType>;
+    endOcclusionQuery(): Result<void, RhiErrorType>;
+}
+/**
+ * Headless compute pass encoder. Records dispatch counts; all state-setting
+ * methods are no-ops.
+ */
+export declare class RhiNullComputePassEncoder implements RhiComputePassEncoder {
+    /** Number of dispatchWorkgroups calls issued on this pass (readback). */
+    dispatchCount: number;
+    /** Most recent setBindGroup ownership validation (AC-09 readback). */
+    lastValidation: Result<unknown, RhiErrorType>;
+    private readonly bookkeeper;
+    private readonly counter;
+    readonly passName: string;
+    constructor(bookkeeper: Bookkeeper, counter: PassCounter | null, passName: string);
+    setPipeline(_pipeline: ComputePipeline): void;
+    setBindGroup(_index: number, bindGroup: BindGroup, _dynamicOffsets?: readonly number[] | undefined): void;
+    dispatchWorkgroups(_x: number, _y?: number | undefined, _z?: number | undefined): void;
+    dispatchWorkgroupsIndirect(indirectBuffer: Buffer, _indirectOffset: number): void;
+    end(): void;
+}
+//# sourceMappingURL=pass-encoders.d.ts.map

package/dist/pass-encoders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-encoders.d.ts","sourceRoot":"","sources":["../src/pass-encoders.ts"],"names":[],"mappings":"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"}

package/dist/queue.d.ts

@@ -0,0 +1,10 @@
+import type { Buffer, CommandBuffer, ExternalImageTextureDestination, Result, RhiError as RhiErrorType, RhiQueue, TextureWriteDestination } from '@forgeax/engine-rhi';
+/** Headless no-op queue. */
+export declare class RhiNullQueue implements RhiQueue {
+    writeBuffer(_buffer: Buffer, _bufferOffset: number, _data: ArrayBufferView | ArrayBuffer, _dataOffset?: number | undefined, _size?: number | undefined): Result<void, RhiErrorType>;
+    writeTexture(_destination: TextureWriteDestination, _data: ArrayBufferView | ArrayBuffer, _dataLayout: Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>, _size: GPUExtent3DStrict): Result<void, RhiErrorType>;
+    copyExternalImageToTexture(_source: Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>, _destination: ExternalImageTextureDestination, _copySize: GPUExtent3DStrict): Result<void, RhiErrorType>;
+    submit(_commandBuffers: readonly CommandBuffer[]): Result<void, RhiErrorType>;
+    onSubmittedWorkDone(): Promise<undefined>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EACb,+BAA+B,EAC/B,MAAM,EACN,QAAQ,IAAI,YAAY,EACxB,QAAQ,EACR,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,4BAA4B;AAC5B,qBAAa,YAAa,YAAW,QAAQ;IAC3C,WAAW,CACT,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,eAAe,GAAG,WAAW,EACpC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,EAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;IAI7B,YAAY,CACV,YAAY,EAAE,uBAAuB,EACrC,KAAK,EAAE,eAAe,GAAG,WAAW,EACpC,WAAW,EAAE,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAC,EACtF,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;IAI7B,0BAA0B,CACxB,OAAO,EAAE,IAAI,CAAC,8BAA8B,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,EAC5E,YAAY,EAAE,+BAA+B,EAC7C,SAAS,EAAE,iBAAiB,GAC3B,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;IAI7B,MAAM,CAAC,eAAe,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;IAO7E,mBAAmB,IAAI,OAAO,CAAC,SAAS,CAAC;CAG1C"}

package/dist/shader.d.ts

@@ -0,0 +1,14 @@
+import type { Result, RhiDevice, RhiError as RhiErrorType, ShaderModule } from '@forgeax/engine-rhi';
+/**
+ * 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 declare function createShaderModule(_device: RhiDevice, _desc: {
+    label?: string | undefined;
+    code: string;
+}): Promise<Result<ShaderModule, RhiErrorType>>;
+//# sourceMappingURL=shader.d.ts.map

package/dist/shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader.d.ts","sourceRoot":"","sources":["../src/shader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,QAAQ,IAAI,YAAY,EACxB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAE7C"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@forgeax/engine-rhi-null",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Headless no-op RHI backend for structural unit tests — implements @forgeax/engine-rhi with zero GPU/DOM dependency.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-rhi": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@webgpu/types": "^0.1.71"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "headless no-op backend has no runtime canvas; no fps to report"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "no-op backend has no hot path; bench focus stays on real backends"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no standalone binary gate; structural assertions provided by runtime dogfood unit tests consuming RhiNull via Channel 1"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,40 @@
+// @forgeax/engine-rhi-null/src/adapter - headless adapter.
+//
+// requestDevice mints a fresh RhiNullDevice, wiring its queue + command-encoder
+// factory. features / limits are empty (the headless backend enables nothing
+// beyond the always-true caps profile); the two-step requestAdapter ->
+// requestDevice path mirrors the spec idiom (research Finding A1 row 2).
+//
+// Related: requirements AC-02 (createRenderer ready chain needs adapter ->
+// device) + AC-12; research Finding A1 row 2.
+
+import type {
+  RequestDeviceOptions,
+  Result,
+  RhiAdapter,
+  RhiDevice,
+  RhiError as RhiErrorType,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { RhiNullCommandEncoder } from './command-encoder';
+import { RhiNullDevice } from './device';
+import { RhiNullQueue } from './queue';
+
+/** Headless adapter. Holds an empty feature set + limits map; requestDevice
+ *  builds a fully-wired RhiNullDevice. */
+export class RhiNullAdapter implements RhiAdapter {
+  readonly features: ReadonlySet<GPUFeatureName> = new Set();
+  readonly limits: Readonly<Record<string, number>> = {};
+
+  // forgeax-async-whitelist is not needed: this returns Promise<Result<...>>
+  // per the spec contract; never rejects.
+  requestDevice(
+    _opts?: RequestDeviceOptions | undefined,
+  ): Promise<Result<RhiDevice, RhiErrorType>> {
+    const device = new RhiNullDevice(
+      new RhiNullQueue(),
+      (bookkeeper, dev) => new RhiNullCommandEncoder(bookkeeper, dev),
+    );
+    return Promise.resolve(ok(device));
+  }
+}

package/src/bookkeeping.ts

@@ -0,0 +1,179 @@
+// @forgeax/engine-rhi-null/src/bookkeeping - method-A handle ledger for the
+// headless no-op backend.
+//
+// RhiNull issues legal opaque-handle brands (each RHI brand is a compile-time
+// `unique symbol` with no runtime field, so any plain object cast via
+// `as unknown as Buffer` satisfies the type contract; research Finding A6). To
+// let M3 command-stream assertions read back create/destroy pairing, draw /
+// dispatch counts and binding assembly, RhiNull threads each issued handle
+// through a per-device Bookkeeper that records a numeric id + kind + destroyed
+// flag + the issuing device id.
+//
+// Error contract (plan-strategy D-1): handle-chain inconsistencies reuse the
+// existing closed RhiErrorCode union with ZERO new members:
+//   - a handle observed on a device other than its issuer -> 'rhi-not-available'
+//   - a destroy / use observed on an already-destroyed handle ->
+//     'destroy-after-destroy'
+// Every RhiError carries the required code / expected / hint triple
+// (charter proposition 3 structured failure).
+//
+// Related: requirements AC-09 (foreign handle returns structured err, no silent
+// pass); plan-strategy §2 D-1; research Finding A3 (RhiErrorCode 20 members,
+// 'rhi-not-available' at errors.ts:113, 'destroy-after-destroy' at errors.ts:127)
+// + Finding A6 (brand construction); charter P3.
+
+import type { Result, RhiError as RhiErrorType } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+
+/**
+ * One ledger row for an issued opaque-handle brand.
+ *
+ * - `id` — per-device monotonic numeric id assigned at register time; the value
+ *   M3 assertions read back to pair create / destroy and count draws.
+ * - `kind` — the handle category (`'Buffer'` / `'Texture'` / `'BindGroupLayout'`
+ *   etc.); free-form so every create* entry can tag what it minted.
+ * - `destroyed` — flipped to `true` by the first destroy; a second destroy
+ *   fail-fasts via `'destroy-after-destroy'`.
+ * - `sourceDeviceId` — the id of the device that issued the handle; cross-device
+ *   use fail-fasts via `'rhi-not-available'`.
+ */
+export interface HandleRecord {
+  readonly id: number;
+  readonly kind: string;
+  destroyed: boolean;
+  readonly sourceDeviceId: number;
+}
+
+/**
+ * The brand attachment RhiNull stamps onto every issued handle object so the
+ * ledger can be recovered from the handle alone (handle-chain validation reads
+ * `handle[BOOKKEEPING_KEY]` rather than holding a side Map keyed on identity,
+ * which would leak across device instances).
+ *
+ * Lives behind a module-private symbol so it never collides with a real RHI
+ * brand symbol and never appears in the public `.d.ts` surface.
+ */
+export const BOOKKEEPING_KEY = Symbol('forgeax-rhi-null-bookkeeping');
+
+/** A handle object as RhiNull mints it: a plain object carrying its ledger row
+ *  under the private bookkeeping symbol, cast to the relevant brand at the
+ *  create* call site. */
+export interface BookkeptHandle {
+  readonly [BOOKKEEPING_KEY]: HandleRecord;
+}
+
+/**
+ * Per-device handle ledger. One Bookkeeper instance lives on each
+ * RhiNullDevice; it assigns the device id at construction and mints monotonic
+ * handle ids thereafter.
+ */
+export class Bookkeeper {
+  readonly deviceId: number;
+  private nextHandleId = 0;
+  private readonly records = new Map<number, HandleRecord>();
+
+  constructor(deviceId: number) {
+    this.deviceId = deviceId;
+  }
+
+  /**
+   * Register a freshly-minted handle of the given kind, returning a plain
+   * object that carries its ledger row. The caller casts the return value to
+   * the concrete brand (`as unknown as Buffer` etc.).
+   */
+  register(kind: string): BookkeptHandle {
+    const id = this.nextHandleId++;
+    const record: HandleRecord = {
+      id,
+      kind,
+      destroyed: false,
+      sourceDeviceId: this.deviceId,
+    };
+    this.records.set(id, record);
+    return { [BOOKKEEPING_KEY]: record };
+  }
+
+  /**
+   * Mark a handle destroyed. Fail-fasts on a second destroy
+   * ('destroy-after-destroy') or on a handle issued by a different device
+   * ('rhi-not-available'); otherwise flips the destroyed flag and returns ok.
+   */
+  destroy(handle: unknown): Result<void, RhiErrorType> {
+    const ownership = this.validateOwnership(handle);
+    if (!ownership.ok) return ownership;
+    const destroyedCheck = isHandleDestroyed(handle);
+    if (!destroyedCheck.ok) return destroyedCheck;
+    ownership.value.destroyed = true;
+    return ok(undefined);
+  }
+
+  /**
+   * Report whether a handle has already been destroyed (true once destroy()
+   * has flipped its flag). Used by command-stream methods that must not
+   * consume a stale handle.
+   */
+  isDestroyed(handle: unknown): boolean {
+    return readRecord(handle)?.destroyed === true;
+  }
+
+  /**
+   * Validate that a handle was issued by THIS device. Returns the ledger row on
+   * success so callers can mutate it (e.g. flip destroyed); returns
+   * 'rhi-not-available' for a foreign handle (AC-09 — no silent pass).
+   */
+  validateOwnership(handle: unknown): Result<HandleRecord, RhiErrorType> {
+    const record = readRecord(handle);
+    if (record === undefined || record.sourceDeviceId !== this.deviceId) {
+      return err(
+        new RhiError({
+          code: 'rhi-not-available',
+          expected: 'handle was issued by this RhiNull device',
+          hint: 'do not pass a handle created on a different RhiNull device into this device; create resources on the device they are used with',
+        }),
+      );
+    }
+    return ok(record);
+  }
+
+  /**
+   * Return all ledger rows as a readonly array. M3 unit tests (w17) read this
+   * to assert create/destroy pairing, BGL/PSO shape counts, and resource
+   * lifecycle coverage (AC-05/06/07). Returns a snapshot of the current Map
+   * so callers can iterate without a stale reference after further mutations.
+   */
+  allRecords(): readonly HandleRecord[] {
+    return [...this.records.values()];
+  }
+
+  /** Report the total number of records in the ledger. */
+  recordCount(): number {
+    return this.records.size;
+  }
+}
+
+/** Recover the ledger row from a handle object, or undefined if the object
+ *  carries no RhiNull bookkeeping (foreign / non-RhiNull handle). */
+function readRecord(handle: unknown): HandleRecord | undefined {
+  if (handle === null || typeof handle !== 'object') return undefined;
+  const tagged = handle as Partial<BookkeptHandle>;
+  return tagged[BOOKKEEPING_KEY];
+}
+
+/**
+ * Validation function: has this handle already been destroyed? Returns ok(void)
+ * for a live handle; returns 'destroy-after-destroy' for a handle whose ledger
+ * row is flagged destroyed (charter P3 fail-fast over silent idempotency).
+ */
+export function isHandleDestroyed(handle: unknown): Result<void, RhiErrorType> {
+  if (readRecord(handle)?.destroyed === true) {
+    return err(
+      new RhiError({
+        code: 'destroy-after-destroy',
+        expected: 'GPU buffer/texture handle has not been destroyed yet',
+        hint: 'object already destroyed; track lifecycle in caller or check isDestroyed before re-destroy',
+      }),
+    );
+  }
+  return ok(undefined);
+}

package/src/canvas-context.ts

@@ -0,0 +1,71 @@
+// @forgeax/engine-rhi-null/src/canvas-context - headless canvas context (R-1).
+//
+// The headless backend has no real canvas. RhiNullCanvasContext satisfies the
+// RhiCanvasContext interface as no-ops: configure returns ok (a headless
+// configure is vacuously successful), unconfigure is void, getConfiguration
+// returns undefined (no real configuration).
+//
+// getCurrentTexture returns a legal Texture brand so the swap-chain
+// acquisition path succeeds — without this the entire render-frame path fails
+// at the first swap-chain access, blocking all dogfood testing of
+// render-graph-to-RhiNull command-flow. The returned Texture carries no real
+// pixels; it is opaque-handle syntactically valid and structurally sound for
+// CI structural unit tests.
+//
+// acquireCanvasContext (mounted on the rhi singleton, R-1) accepts any
+// canvas / null / undefined and returns ok(canvasContext) so the facade
+// never crashes and canvas-dependent paths exercise through to the
+// render-graph level.
+//
+// Related: requirements AC-11 (canvas ctx structured behaviour) — the
+// context itself succeeds; AC-11 verify tests confirm the getCurrentTexture
+// brand is a valid opaque handle and downstream consumption doesn't crash.
+// Research Finding A4 (acquireCanvasContext on singleton) + A3
+// (rhi-not-available legal); plan-strategy §4 R-1; charter P3.
+
+import type {
+  CanvasConfiguration,
+  Result,
+  RhiCanvasContext,
+  RhiError as RhiErrorType,
+  Texture,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+
+/**
+ * Headless canvas context. configure succeeds vacuously; getCurrentTexture
+ * mints a legal opaque-handle Texture brand so the swap-chain acquisition path
+ * never blocks frame rendering in headless CI.
+ */
+export class RhiNullCanvasContext implements RhiCanvasContext {
+  configure(_desc: CanvasConfiguration): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  unconfigure(): void {}
+
+  getConfiguration(): CanvasConfiguration | undefined {
+    return undefined;
+  }
+
+  getCurrentTexture(): Result<Texture, RhiErrorType> {
+    // A brand is a compile-time unique symbol with no runtime field, so a plain
+    // object cast is a structurally valid Texture (research Finding A6). No real
+    // pixels; the command-stream path only needs a legal handle to thread on.
+    return ok({} as unknown as Texture);
+  }
+}
+
+/**
+ * Acquire a canvas context. The headless backend returns ok(context) so the
+ * createRenderer context-acquisition step succeeds. The context's
+ * getCurrentTexture mints a legal Texture brand once a bookkeeper is attached.
+ *
+ * R-1: this is mounted on the rhi singleton so Channel 1's facade never
+ * crashes on a missing acquireCanvasContext.
+ */
+export function acquireCanvasContext(
+  _canvas?: HTMLCanvasElement | OffscreenCanvas | null | undefined,
+): Result<RhiCanvasContext, RhiErrorType> {
+  return ok(new RhiNullCanvasContext());
+}

package/src/command-encoder.ts

@@ -0,0 +1,146 @@
+// @forgeax/engine-rhi-null/src/command-encoder - headless command encoder.
+//
+// RhiNullCommandEncoder is a no-op recorder: begin*Pass returns a fresh
+// pass-encoder bound to the same per-device ledger; copy* / clear* / debug* /
+// writeTimestamp are no-ops; resolveQuerySet / finish return ok. finish() mints
+// a legal CommandBuffer brand through the ledger so submit-side bookkeeping
+// (AC-12) can read it back.
+//
+// Each beginRenderPass / beginComputePass reads the `label` from the descriptor
+// and threads it as the pass name to the per-device counters so M3 unit tests
+// (w17 AC-04) can assert per-frame pass scheduling order.
+//
+// Related: requirements AC-04 (pass sequence) + AC-06 (draw count via pass
+// encoders); research Finding A1 row 5; plan-strategy §3.1.
+
+import type {
+  Buffer,
+  CommandBuffer,
+  ComputePassDescriptor,
+  QuerySet,
+  RenderPassDescriptor,
+  Result,
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiError as RhiErrorType,
+  RhiRenderPassEncoder,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import type { Bookkeeper } from './bookkeeping';
+import type { RhiNullDevice } from './device';
+import {
+  type PassCounter,
+  RhiNullComputePassEncoder,
+  RhiNullRenderPassEncoder,
+} from './pass-encoders';
+
+/**
+ * Internal counter that writes per-frame stats back to the owning device.
+ */
+class DeviceCounter implements PassCounter {
+  constructor(private readonly device: RhiNullDevice) {}
+
+  recordDraw(): void {
+    this.device.totalDrawCount++;
+  }
+
+  recordDispatch(): void {
+    this.device.totalDispatchCount++;
+  }
+
+  recordBindGroup(): void {
+    this.device.totalBindGroupCount++;
+  }
+
+  recordPassName(name: string): void {
+    this.device.framePassNames.push(name);
+  }
+}
+
+/**
+ * Read the `label` field from a GPURenderPassDescriptor (or undefined if not
+ * set). The engine sets `label` on the render pass descriptor; the graph's
+ * compile path doesn't always thread a per-pass label, so we fall back to the
+ * RenderPassDescriptor's generic label (or '<unnamed>').
+ */
+function readPassLabel(desc: { readonly label?: string | undefined } | undefined): string {
+  if (desc && typeof desc.label === 'string' && desc.label.length > 0) {
+    return desc.label as string;
+  }
+  return '<unnamed>';
+}
+
+/**
+ * Headless command encoder. begin*Pass returns a no-op pass encoder bound to
+ * the issuing device's ledger; recording methods are no-ops; finish mints a
+ * CommandBuffer brand.
+ */
+export class RhiNullCommandEncoder implements RhiCommandEncoder {
+  private readonly bookkeeper: Bookkeeper;
+  private readonly counter: PassCounter;
+
+  constructor(bookkeeper: Bookkeeper, device: RhiNullDevice) {
+    this.bookkeeper = bookkeeper;
+    this.counter = new DeviceCounter(device);
+  }
+
+  beginRenderPass(desc: RenderPassDescriptor): RhiRenderPassEncoder {
+    const label = readPassLabel(desc);
+    return new RhiNullRenderPassEncoder(this.bookkeeper, this.counter, label);
+  }
+
+  beginComputePass(desc?: ComputePassDescriptor | undefined): RhiComputePassEncoder {
+    const label = readPassLabel(desc);
+    return new RhiNullComputePassEncoder(this.bookkeeper, this.counter, label);
+  }
+
+  copyBufferToBuffer(
+    _source: Buffer,
+    _sourceOffsetOrDestination: number | Buffer,
+    _destinationOrSize?: Buffer | number | undefined,
+    _destinationOffset?: number | undefined,
+    _size?: number | undefined,
+  ): void {}
+
+  copyBufferToTexture(
+    _source: GPUTexelCopyBufferInfo,
+    _destination: GPUTexelCopyTextureInfo,
+    _copySize: GPUExtent3DStrict,
+  ): void {}
+
+  copyTextureToBuffer(
+    _source: GPUTexelCopyTextureInfo,
+    _destination: GPUTexelCopyBufferInfo,
+    _copySize: GPUExtent3DStrict,
+  ): void {}
+
+  copyTextureToTexture(
+    _source: GPUTexelCopyTextureInfo,
+    _destination: GPUTexelCopyTextureInfo,
+    _copySize: GPUExtent3DStrict,
+  ): void {}
+
+  clearBuffer(_buffer: Buffer, _offset?: number | undefined, _size?: number | undefined): void {}
+
+  resolveQuerySet(
+    _querySet: QuerySet,
+    _firstQuery: number,
+    _queryCount: number,
+    _destination: Buffer,
+    _destinationOffset: number,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  writeTimestamp(_querySet: QuerySet, _queryIndex: number): void {}
+
+  pushDebugGroup(_groupLabel: string): void {}
+
+  popDebugGroup(): void {}
+
+  insertDebugMarker(_markerLabel: string): void {}
+
+  finish(): Result<CommandBuffer, RhiErrorType> {
+    return ok(this.bookkeeper.register('CommandBuffer') as unknown as CommandBuffer);
+  }
+}