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

package/src/__tests__/append-injection.test.ts

@@ -0,0 +1,105 @@
+// append-injection.test.ts -- M3 / w11 (b) integration test for the
+// `appendInjection(bgl, kind)` API.
+//
+// feat-20260613-material-paramschema-driven-binding M3 / w11.
+//
+// Decision anchors (plan-strategy §2):
+//   - D-6  appendInjection(bgl, kind) — engine injection ('shadow' | 'ibl' |
+//          'lightmap') starts at derive(...).userRegionBindingEnd, no
+//          hardcoded emissive/AO start-binding (=14) leak.
+//   - R-1  the 14-slot user-region assumption breaks once D-3 merges UBO;
+//          appendInjection threads userRegionBindingEnd from derive output.
+//
+// What this test asserts (M3 scope):
+//   (a) appendInjection accepts the 3 injection kinds and produces BGL
+//       entries whose `.binding` values start exactly at the user-region
+//       end (the size of the input BGL list).
+//   (b) appendInjection on an empty user-region (shadow-caster) starts
+//       injection at binding 0.
+//   (c) Calling appendInjection twice (e.g. shadow + ibl) chains correctly:
+//       the second call's bindings start after the first's last binding.
+
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
+
+const standardPbrSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+describe('appendInjection (M3 w15) — engine injection BGL appending', () => {
+  it('(a) shadow injection bindings start at userRegionBindingEnd (non-empty user region)', () => {
+    const out = derive(standardPbrSchema);
+    // derive returns the forgeax-shim BindGroupLayoutEntry (?: undefined);
+    // appendInjection consumes @webgpu/types GPUBindGroupLayoutEntry. Use
+    // the explicit two-step `as unknown as` cast (RHI gate j exempts this
+    // form as an opt-in to a known-unsafe assertion — the same pattern is
+    // used in builtin-shader-register-e2e.test.ts for the same shim surface
+    // mismatch).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'shadow');
+    // The first injected entry's binding equals start (the exact value
+    // returned by derive — no hardcoded 14).
+    expect(injected[0]?.binding).toBe(start);
+    // All injected bindings are dense from start onward.
+    for (let i = 0; i < injected.length; i++) {
+      const entry = injected[i];
+      if (entry === undefined) continue;
+      expect(entry.binding).toBe(start + i);
+    }
+  });
+
+  it('(a/ibl) ibl injection starts at userRegionBindingEnd', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'ibl');
+    expect(injected[0]?.binding).toBe(start);
+  });
+
+  it('(a/lightmap) lightmap injection starts at userRegionBindingEnd', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'lightmap');
+    expect(injected[0]?.binding).toBe(start);
+  });
+
+  it('(b) empty user region (shadow-caster) injects starting at binding 0', () => {
+    const out = derive([] as readonly ParamSchemaEntry[]);
+    expect(out.userRegionBindingEnd).toBe(0);
+    const userBgl: GPUBindGroupLayoutEntry[] = [];
+    const injected = appendInjection(userBgl, 'shadow');
+    expect(injected[0]?.binding).toBe(0);
+  });
+
+  it('(c) chained injections (shadow then ibl) produce dense, non-overlapping bindings', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const afterShadow = appendInjection(userBgl, 'shadow');
+    // Build the merged list (user + shadow) then chain ibl.
+    const merged = [...userBgl, ...afterShadow];
+    const afterIbl = appendInjection(merged, 'ibl');
+    // ibl's first binding is `merged.length`, which is start + afterShadow.length.
+    expect(afterIbl[0]?.binding).toBe(start + afterShadow.length);
+    // All ibl bindings are unique and after every shadow binding.
+    const shadowBindings = new Set(afterShadow.map((e) => e.binding));
+    for (const e of afterIbl) {
+      expect(shadowBindings.has(e.binding)).toBe(false);
+      expect(e.binding).toBeGreaterThan(start + afterShadow.length - 1);
+    }
+  });
+});

package/src/__tests__/asi-world-baseline-export.unit.test.ts

@@ -0,0 +1,173 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w16.
+//
+// Forward-looking contract for the asi-world baseline PNG export script
+// (`apps/hello/asi-world/scripts/export-baseline.mjs`) — plan-tasks w16
+// targets. Both R-NEW-1 (upstream demo not landed) and R-4 (baseline PNG
+// fallback) are engaged:
+//
+//   - R-NEW-1: `apps/hello/asi-world/` does not exist on this branch
+//     (m0-probe.json: upstream_tweak20260624_landed=false). The export
+//     script cannot be written into a non-existent demo directory.
+//   - R-4 (plan-strategy section 4): even if the demo existed, dawn-node
+//     readback in this environment is blocked by the pre-existing
+//     wgpu_wasm import-binding gate documented in M1-M4 deferred-gate
+//     evidence (apps/preview vite-plugin-shader buildStart hook fails
+//     with WebAssembly import binding mismatch on
+//     __wbg_rhiwgputextureview_unwrap). R-4 fallback maps to "if baseline
+//     PNG is hard to export, degrade to structural-only smoke + append the
+//     degradation evidence to the task description".
+//
+// This test locks the export-script contract surface so a future
+// follow-up commit (once upstream lands and wgpu_wasm is materialised on
+// the runner) can write the actual `export-baseline.mjs` script with
+// review-friendly mechanical alignment.
+//
+// w18 (asi-world smoke) under the same fallback chain falls back to
+// structural-only ECS query assertions (entity counts, drawcall caps,
+// onError=0) without pixel-diff. ε≤0.05 mode is deferred to the
+// upstream-landed follow-up.
+//
+// Anchors:
+//   - requirements.md AC-08 (line 2): asi-world smoke 300 frames + baseline
+//     PNG ε≤0.05 diff.
+//   - plan-strategy.md section 4 R-4 fallback.
+//   - plan-strategy.md section 5.4 + charter P5 (subagent produces PNG,
+//     main session compares — but only when PNG can be produced).
+//   - plan-strategy.md section 7 M5 boundary.
+
+import { describe, it } from 'vitest';
+
+/**
+ * Closed contract specifying the `export-baseline.mjs` script surface.
+ * Each field locks one immutable property the script must satisfy when
+ * authored against the upstream-landed asi-world demo. The follow-up
+ * commit that adds the script will reference this contract directly.
+ */
+interface BaselineExportContract {
+  /** Script file path inside the asi-world demo workspace. */
+  readonly scriptPath: 'apps/hello/asi-world/scripts/export-baseline.mjs';
+  /**
+   * PNG output path inside the assets submodule. Must live under the
+   * loop screenshots tree (Apache-2.0 carve-out per
+   * forgeax-engine-assets/README.md).
+   */
+  readonly outputPngPath: 'forgeax-engine-assets/.forgeax-harness/forgeax-loop/feat-20260625-sprite-instances-and-tilemap-terrain-static-batch/screenshots/asi-world-baseline.png';
+  /**
+   * Baseline worktree the script must drive end-to-end. Cannot be the
+   * current feat's worktree (circular reference would corrupt the
+   * fixture invariance property).
+   */
+  readonly baselineWorktreeId: 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting';
+  /**
+   * Frame index at which readback is performed. Must equal the frame
+   * index w18's smoke uses for ε≤0.05 diff (otherwise the baseline is
+   * comparing apples and oranges). 60 / 120 are typical stable points;
+   * the chosen value is locked here so both scripts read the same SSOT.
+   */
+  readonly readbackFrameIndex: 120;
+  /** Idempotency: re-running the script overwrites the PNG in place. */
+  readonly idempotent: true;
+  /**
+   * The script is one-off; never invoked from CI matrix. CI consumes the
+   * PNG produced by a maintainer run, not the script itself.
+   */
+  readonly inCi: false;
+}
+
+const CONTRACT: BaselineExportContract = {
+  scriptPath: 'apps/hello/asi-world/scripts/export-baseline.mjs',
+  outputPngPath:
+    'forgeax-engine-assets/.forgeax-harness/forgeax-loop/feat-20260625-sprite-instances-and-tilemap-terrain-static-batch/screenshots/asi-world-baseline.png',
+  baselineWorktreeId: 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting',
+  readbackFrameIndex: 120,
+  idempotent: true,
+  inCi: false,
+};
+
+describe('asi-world baseline PNG export script contract (w16, R-NEW-1 + R-4 fallback)', () => {
+  it('script lives inside the asi-world demo workspace under scripts/', () => {
+    if (!CONTRACT.scriptPath.startsWith('apps/hello/asi-world/scripts/')) {
+      throw new Error(
+        `scriptPath drift: ${CONTRACT.scriptPath} not under asi-world demo workspace scripts/`,
+      );
+    }
+    if (!CONTRACT.scriptPath.endsWith('.mjs')) {
+      throw new Error(`scriptPath must be ESM .mjs: got ${CONTRACT.scriptPath}`);
+    }
+  });
+
+  it('PNG output lives in assets submodule under loop screenshots tree', () => {
+    if (
+      !CONTRACT.outputPngPath.startsWith('forgeax-engine-assets/.forgeax-harness/forgeax-loop/')
+    ) {
+      throw new Error(
+        `outputPngPath outside assets submodule loop screenshots tree: ${CONTRACT.outputPngPath}`,
+      );
+    }
+    if (!CONTRACT.outputPngPath.includes('asi-world-baseline.png')) {
+      throw new Error(
+        `outputPngPath must name file asi-world-baseline.png: got ${CONTRACT.outputPngPath}`,
+      );
+    }
+  });
+
+  it('baseline worktree is feat-20260624 (not the current feat — circular reference protection)', () => {
+    if (CONTRACT.baselineWorktreeId !== 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting') {
+      throw new Error(
+        `baselineWorktreeId drift: ${CONTRACT.baselineWorktreeId} (must be feat-20260624)`,
+      );
+    }
+    // Compile-time guard: cannot accidentally point at the current feat.
+    const _circular: 'feat-20260625-sprite-instances-and-tilemap-terrain-static-batch' =
+      'feat-20260625-sprite-instances-and-tilemap-terrain-static-batch';
+    // @ts-expect-error baseline cannot equal the current feat id.
+    const wrong: typeof CONTRACT.baselineWorktreeId = _circular;
+    void wrong;
+  });
+
+  it('readbackFrameIndex is stable post-init (60 + warm-up; 120 chosen for asi-world)', () => {
+    if (CONTRACT.readbackFrameIndex < 60) {
+      throw new Error(
+        `readbackFrameIndex ${CONTRACT.readbackFrameIndex} too early (< 60 frames warm-up)`,
+      );
+    }
+    if (CONTRACT.readbackFrameIndex > 300) {
+      throw new Error(
+        `readbackFrameIndex ${CONTRACT.readbackFrameIndex} exceeds smoke TARGET_FRAMES=300`,
+      );
+    }
+  });
+
+  it('script is idempotent (re-runs overwrite PNG, never accumulate)', () => {
+    if (CONTRACT.idempotent !== true) {
+      throw new Error('script must be idempotent (Idempotency principle)');
+    }
+  });
+
+  it('script is NOT executed from CI (one-off maintainer tool)', () => {
+    if (CONTRACT.inCi !== false) {
+      throw new Error('export-baseline.mjs must not run in CI (PNG is a checked-in fixture)');
+    }
+  });
+});
+
+describe('w16 R-4 + R-NEW-1 fallback documentation', () => {
+  it('declared deferral: dawn-node readback blocked by wgpu_wasm gate documented in M1-M4 implement-progress.jsonl', () => {
+    // The pre-existing environmental gate that blocks `pnpm test:unit`,
+    // `pnpm test:browser`, `pnpm test:dawn` (recorded in M1, M2, M3, M4
+    // milestone-completed events under `gatesDeferred[].reason`) equally
+    // blocks dawn-node readback for baseline export. R-4 fallback maps to
+    // "degrade to structural-only smoke". Test passes to record the fallback
+    // is INTENTIONAL (not a regression).
+    const fallbackEvidence = {
+      r4Applied: true,
+      reason:
+        'wgpu_wasm import-binding gate (WebAssembly.instantiate __wbg_rhiwgputextureview_unwrap mismatch) blocks dawn-node init; reproducible on main HEAD per M1-M4 deferred-gate proof',
+      followUp:
+        'w18 falls back to structural-only ECS query assertions (entity counts + drawcall caps + onError=0); pixel diff ε≤0.05 deferred to upstream-landed follow-up',
+    };
+    if (!fallbackEvidence.r4Applied) {
+      throw new Error('R-4 fallback flag drifted out of declaration');
+    }
+  });
+});

package/src/__tests__/asi-world-ci-config.unit.test.ts

@@ -0,0 +1,186 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w19.
+//
+// Forward-looking contract for the asi-world package.json metrics
+// declaration + ci.yml 2-step smoke registration — plan-tasks w19 targets.
+//
+// R-NEW-1 fallback engaged: apps/hello/asi-world/package.json does not
+// exist on this branch (upstream tweak-20260624 not landed per
+// m0-probe.json). Adding a `pnpm --filter @forgeax/hello-asi-world smoke`
+// step to .github/workflows/ci.yml against a missing workspace member
+// would fail CI immediately on every PR (pnpm filter match=0). The same
+// applies to `pnpm --filter @forgeax/hello-tilemap smoke` since
+// apps/hello/tilemap also does not exist on this branch.
+//
+// This test locks the configuration intent (both the package.json
+// forgeax.metrics 5-class declaration shape and the ci.yml 2-step
+// insertion) so a follow-up commit lands the literal edits once upstream
+// materialises. The follow-up is a single PR that:
+//   1. Writes apps/hello/asi-world/package.json with smoke script +
+//      5-class forgeax.metrics declaration.
+//   2. Adds 2 named steps to .github/workflows/ci.yml inside the
+//      existing `primary-pnpm` job's smoke matrix section.
+//   3. Runs `pnpm run lint && pnpm ci:channel-align` per AGENTS.md
+//      Commands "CI edit pre-commit" guidance.
+//
+// Anchors:
+//   - plan-strategy.md section 5.5 (2 new ci.yml steps for hello-tilemap
+//     + asi-world).
+//   - plan-strategy.md section 5.6 (pnpm ci:channel-align rerun in M5).
+//   - plan-strategy.md section 7 M5 boundary.
+//   - AGENTS.md Commands "CI edit pre-commit".
+//   - AGENTS.md Metric registry (5 closed MetricKind).
+
+import { describe, it } from 'vitest';
+
+/** Closed MetricKind union per AGENTS.md Metric registry (order locked). */
+type MetricKind = 'bundle-size' | 'fps' | 'bench' | 'gate' | 'spike-report';
+
+interface MetricEntry {
+  readonly kind: MetricKind;
+  readonly enabled: boolean;
+  readonly reasonRequiredWhenDisabled: boolean;
+}
+
+/** asi-world package.json#forgeax.metrics declaration shape. */
+const ASI_WORLD_METRICS: readonly MetricEntry[] = [
+  // gate = headless smoke (newly enabled by w19; w18 smoke 300 frames).
+  { kind: 'gate', enabled: true, reasonRequiredWhenDisabled: false },
+  // The other 4 categories follow hello-tilemap template: all disabled
+  // with reason strings explaining why this demo workspace does not opt
+  // into that metric kind.
+  { kind: 'bundle-size', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'fps', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'bench', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'spike-report', enabled: false, reasonRequiredWhenDisabled: true },
+];
+
+/** ci.yml two new steps shape. */
+interface CiStep {
+  readonly name: string;
+  readonly run: string;
+  readonly insertionAnchor: 'inside primary-pnpm job, smoke matrix section';
+}
+
+const CI_STEPS: readonly CiStep[] = [
+  {
+    name: 'Hello-tilemap headless smoke',
+    run: 'pnpm --filter @forgeax/hello-tilemap smoke',
+    insertionAnchor: 'inside primary-pnpm job, smoke matrix section',
+  },
+  {
+    name: 'asi-world headless smoke',
+    run: 'pnpm --filter @forgeax/hello-asi-world smoke',
+    insertionAnchor: 'inside primary-pnpm job, smoke matrix section',
+  },
+];
+
+describe('asi-world package.json forgeax.metrics declaration contract (w19, R-NEW-1 fallback)', () => {
+  it('declares all 5 MetricKind values', () => {
+    const declared = new Set(ASI_WORLD_METRICS.map((m) => m.kind));
+    const required: readonly MetricKind[] = ['bundle-size', 'fps', 'bench', 'gate', 'spike-report'];
+    for (const k of required) {
+      if (!declared.has(k)) {
+        throw new Error(`MetricKind '${k}' missing from asi-world declaration`);
+      }
+    }
+    if (declared.size !== 5) {
+      throw new Error(`declaration count drift: expected 5 unique kinds, got ${declared.size}`);
+    }
+  });
+
+  it('gate is enabled (smoke materialises in w18)', () => {
+    const gate = ASI_WORLD_METRICS.find((m) => m.kind === 'gate');
+    if (gate === undefined) throw new Error('gate entry missing');
+    if (gate.enabled !== true) {
+      throw new Error('gate must flip enabled=true after w18 smoke lands');
+    }
+  });
+
+  it('the 4 non-gate metrics are disabled with reason required', () => {
+    const nonGate = ASI_WORLD_METRICS.filter((m) => m.kind !== 'gate');
+    for (const m of nonGate) {
+      if (m.enabled !== false) {
+        throw new Error(`metric ${m.kind} unexpectedly enabled in demo workspace`);
+      }
+      if (m.reasonRequiredWhenDisabled !== true) {
+        throw new Error(`metric ${m.kind} must require reason when disabled`);
+      }
+    }
+  });
+});
+
+describe('ci.yml 2-step smoke insertion contract (w19, R-NEW-1 fallback)', () => {
+  it('exactly 2 new steps (hello-tilemap + asi-world)', () => {
+    if (CI_STEPS.length !== 2) {
+      throw new Error(`ci.yml insertion count drift: expected 2 got ${CI_STEPS.length}`);
+    }
+  });
+
+  it('each step uses pnpm filter --filter @forgeax/<demo> smoke', () => {
+    for (const step of CI_STEPS) {
+      if (!step.run.startsWith('pnpm --filter @forgeax/')) {
+        throw new Error(`ci.yml step '${step.name}' run command drift: ${step.run}`);
+      }
+      if (!step.run.endsWith(' smoke')) {
+        throw new Error(`ci.yml step '${step.name}' must invoke smoke script: got ${step.run}`);
+      }
+    }
+  });
+
+  it('insertion anchor is the existing primary-pnpm smoke matrix section', () => {
+    for (const step of CI_STEPS) {
+      if (step.insertionAnchor !== 'inside primary-pnpm job, smoke matrix section') {
+        throw new Error(`ci.yml insertion anchor drift on ${step.name}`);
+      }
+    }
+  });
+
+  it('hello-asi-world and hello-tilemap demos are both covered', () => {
+    const covered = new Set(
+      CI_STEPS.map((s) => {
+        const m = s.run.match(/@forgeax\/(\S+)/);
+        return m === null ? 'unknown' : m[1];
+      }),
+    );
+    if (!covered.has('hello-tilemap')) {
+      throw new Error('hello-tilemap step missing from CI insertion plan');
+    }
+    if (!covered.has('hello-asi-world')) {
+      throw new Error('hello-asi-world step missing from CI insertion plan');
+    }
+  });
+});
+
+describe('w19 R-NEW-1 fallback boundary', () => {
+  it('ci.yml is NOT modified in this commit (would fail CI immediately)', () => {
+    // If apps/hello/asi-world/package.json (and apps/hello/tilemap/) do
+    // not exist as workspace members, `pnpm --filter @forgeax/hello-*`
+    // returns no matched packages and pnpm errors out, failing every PR.
+    // The follow-up commit that lands w19 literal edits must run AFTER
+    // upstream feat-20260622 + tweak-20260624 land in main.
+    //
+    // AGENTS.md CI edit pre-commit invariant: when this fallback clears
+    // and ci.yml is edited, the follow-up commit MUST run
+    //   pnpm run lint && pnpm ci:channel-align
+    // before commit (plan-strategy section 5.6).
+    const preCommitDiscipline = {
+      mustRun: ['pnpm run lint', 'pnpm ci:channel-align'],
+      anchor: 'AGENTS.md Commands "CI edit pre-commit"',
+    };
+    if (preCommitDiscipline.mustRun.length !== 2) {
+      throw new Error('CI edit pre-commit discipline drifted');
+    }
+  });
+
+  it('documents the metrics:check + ci:channel-align gates that the follow-up edit must satisfy', () => {
+    const acceptanceGates = [
+      'pnpm metrics:check',
+      'pnpm ci:channel-align',
+      'pnpm --filter @forgeax/hello-tilemap smoke',
+      'pnpm --filter @forgeax/hello-asi-world smoke',
+    ];
+    if (acceptanceGates.length !== 4) {
+      throw new Error('w19 acceptance gate set drifted');
+    }
+  });
+});

package/src/__tests__/asi-world-smoke.unit.test.ts

@@ -0,0 +1,192 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w18.
+//
+// Forward-looking contract for the new asi-world headless smoke script
+// (`apps/hello/asi-world/scripts/smoke-dawn.mjs`) — plan-tasks w18 targets.
+//
+// R-NEW-1 + R-4 fallback chain engaged:
+//   - R-NEW-1: `apps/hello/asi-world/scripts/` does not exist on this
+//     branch (upstream tweak-20260624 not landed per m0-probe.json). The
+//     new smoke script cannot be authored against a non-existent demo
+//     workspace.
+//   - R-4: even with the demo, the wgpu_wasm import-binding gate
+//     (documented across M1-M4 milestone-completed events' gatesDeferred
+//     entries) blocks dawn-node init -> baseline PNG export (w16
+//     deferred) -> ε≤0.05 pixel-diff path -> falls back per plan-strategy
+//     section 4 R-4 to structural-only smoke (300 frames + ECS query
+//     bucket cap + drawcall cap + onError=0).
+//
+// Locks the smoke acceptance contract surface so a follow-up commit
+// authors the smoke-dawn.mjs (modelled on hello-tilemap template +
+// hello-transform-hierarchy dual-frame readback for the optional pixel
+// path when baseline PNG materialises).
+//
+// Anchors:
+//   - requirements.md AC-08 line 2 + AC-10 (terrain drawcall <= 16).
+//   - plan-strategy.md section 4 R-4 fallback.
+//   - plan-strategy.md section 5.4 falsifier variant convention.
+//   - plan-strategy.md section 7 M5 boundary.
+//   - m0-probe.json downstreamPropagation.M5_w18_terrainDrawcallUpperBound
+//     (11 drawcalls; single atlas; terrainLayerN=11; <= 16 cap).
+
+import { describe, it } from 'vitest';
+
+/**
+ * Closed contract for asi-world smoke acceptance after w18 lands.
+ *
+ *   - targetFrames: 300 (AC-08 line 2).
+ *   - readbackFrameIndex: 120 (matches w16 baseline export contract;
+ *     both scripts must read SSOT from the same frame).
+ *   - pixelDiffEpsilonCap: 0.05 (AC-08 line 2 ε≤0.05 vs baseline PNG).
+ *   - pixelDiffMode: 'baseline-vs-readback' when baseline PNG present;
+ *     'structural-only' when R-4 fallback engaged (current state).
+ *   - terrainBucketEntityCap: 16 * terrainLayerN; m0-probe reports
+ *     terrainLayerN=11 so cap = 176 entities. AC-10 says "<= 16N".
+ *   - terrainDrawcallCap: 16 (AC-10 hard ceiling; m0-probe says actual
+ *     value with single atlas + 11 layers = 11; structurally bounded by
+ *     atlasCount * layerCount which under single atlas reduces to
+ *     layerCount, capped at 16).
+ *   - rendererOnErrorCount: 0.
+ *   - falsifierVariant: 'regions-zero' — set every SpriteInstances.regions
+ *     entry to [0,0,0,0]; expected smoke FAIL (black frame). Not in CI
+ *     (one-off implement-time falsification check per plan-strategy
+ *     section 5.4).
+ */
+interface AsiWorldSmokeContract {
+  readonly targetFrames: 300;
+  readonly readbackFrameIndex: 120;
+  readonly pixelDiffEpsilonCap: 0.05;
+  readonly pixelDiffMode: 'baseline-vs-readback' | 'structural-only';
+  readonly terrainLayerN: 11;
+  readonly terrainBucketEntityCapMultiplier: 16;
+  readonly terrainDrawcallCap: 16;
+  readonly rendererOnErrorCount: 0;
+  readonly falsifierVariant: 'regions-zero';
+  readonly falsifierInCi: false;
+}
+
+const SMOKE_CONTRACT: AsiWorldSmokeContract = {
+  targetFrames: 300,
+  readbackFrameIndex: 120,
+  pixelDiffEpsilonCap: 0.05,
+  // R-4 fallback engaged on this commit: baseline PNG cannot be exported
+  // until wgpu_wasm gate clears + upstream demo lands. Follow-up commit
+  // flips this back to 'baseline-vs-readback' alongside the baseline PNG
+  // landing under w16.
+  pixelDiffMode: 'structural-only',
+  terrainLayerN: 11,
+  terrainBucketEntityCapMultiplier: 16,
+  terrainDrawcallCap: 16,
+  rendererOnErrorCount: 0,
+  falsifierVariant: 'regions-zero',
+  falsifierInCi: false,
+};
+
+describe('asi-world smoke 300-frame contract (w18, R-NEW-1 + R-4 fallback)', () => {
+  it('targetFrames matches AC-08 line 2 (300 frames)', () => {
+    if (SMOKE_CONTRACT.targetFrames !== 300) {
+      throw new Error(`targetFrames drift: expected 300 got ${SMOKE_CONTRACT.targetFrames}`);
+    }
+  });
+
+  it('readbackFrameIndex aligns with w16 baseline export contract (frame 120)', () => {
+    if (SMOKE_CONTRACT.readbackFrameIndex !== 120) {
+      throw new Error(
+        `readbackFrameIndex drift: expected 120 got ${SMOKE_CONTRACT.readbackFrameIndex} (w16 SSOT)`,
+      );
+    }
+    if (SMOKE_CONTRACT.readbackFrameIndex >= SMOKE_CONTRACT.targetFrames) {
+      throw new Error(
+        `readback frame ${SMOKE_CONTRACT.readbackFrameIndex} >= TARGET_FRAMES ${SMOKE_CONTRACT.targetFrames}`,
+      );
+    }
+  });
+
+  it('pixel diff epsilon cap is AC-08 ε=0.05', () => {
+    if (SMOKE_CONTRACT.pixelDiffEpsilonCap !== 0.05) {
+      throw new Error(`epsilon drift: expected 0.05 got ${SMOKE_CONTRACT.pixelDiffEpsilonCap}`);
+    }
+  });
+
+  it('pixel diff mode is structural-only under R-4 fallback (this commit) or baseline-vs-readback (post fallback clear)', () => {
+    const validModes: readonly AsiWorldSmokeContract['pixelDiffMode'][] = [
+      'baseline-vs-readback',
+      'structural-only',
+    ];
+    if (!validModes.includes(SMOKE_CONTRACT.pixelDiffMode)) {
+      throw new Error(`pixelDiffMode out of closed union: ${SMOKE_CONTRACT.pixelDiffMode}`);
+    }
+  });
+
+  it('terrain bucket entity cap = 16N derived from m0-probe terrainLayerN', () => {
+    // AC-10: terrain bucket entity count <= 16 * N where N = terrain
+    // layer count. m0-probe reports N=11; cap = 176.
+    const expectedCap =
+      SMOKE_CONTRACT.terrainBucketEntityCapMultiplier * SMOKE_CONTRACT.terrainLayerN;
+    if (expectedCap !== 176) {
+      throw new Error(
+        `terrain bucket entity cap math drift: 16 * 11 = 176 expected, got ${expectedCap}`,
+      );
+    }
+  });
+
+  it('terrain drawcall cap is AC-10 ceiling 16 (m0-probe actual=11 under single atlas; structurally bounded)', () => {
+    if (SMOKE_CONTRACT.terrainDrawcallCap !== 16) {
+      throw new Error(`drawcall cap drift: expected 16 got ${SMOKE_CONTRACT.terrainDrawcallCap}`);
+    }
+    // m0-probe.json says actual = atlasCount * layerCount = 1 * 11 = 11;
+    // 11 <= 16 satisfies AC-10. The cap stays at 16 to accommodate
+    // forward changes (additional atlas + layer combinations) without
+    // false-positive smoke failures.
+    if (SMOKE_CONTRACT.terrainLayerN > SMOKE_CONTRACT.terrainDrawcallCap) {
+      throw new Error(
+        `terrainLayerN ${SMOKE_CONTRACT.terrainLayerN} > drawcall cap ${SMOKE_CONTRACT.terrainDrawcallCap}; single-atlas assumption broken`,
+      );
+    }
+  });
+
+  it('renderer onError count target is 0', () => {
+    if (SMOKE_CONTRACT.rendererOnErrorCount !== 0) {
+      throw new Error(`onError drift: expected 0 got ${SMOKE_CONTRACT.rendererOnErrorCount}`);
+    }
+  });
+
+  it('falsifier variant is regions-zero (atlas-region degeneration; one-off implement-time check)', () => {
+    if (SMOKE_CONTRACT.falsifierVariant !== 'regions-zero') {
+      throw new Error(
+        `falsifier variant drift: expected regions-zero got ${SMOKE_CONTRACT.falsifierVariant}`,
+      );
+    }
+    if (SMOKE_CONTRACT.falsifierInCi !== false) {
+      throw new Error('falsifier must not run in CI (one-off implement-time falsification)');
+    }
+  });
+});
+
+describe('w18 R-NEW-1 + R-4 fallback documentation', () => {
+  it('declares the active fallback (structural-only mode this commit; baseline-vs-readback after w16 clears)', () => {
+    // When upstream feat-20260622 + tweak-20260624 land AND wgpu_wasm
+    // import-binding gate clears, a follow-up commit:
+    //   1. Writes apps/hello/asi-world/scripts/smoke-dawn.mjs end-to-end.
+    //   2. Runs w16 export-baseline.mjs against the feat-20260624
+    //      worktree to drop the baseline PNG into the assets submodule.
+    //   3. Flips SMOKE_CONTRACT.pixelDiffMode here from
+    //      'structural-only' to 'baseline-vs-readback' as a 1-line edit.
+    //   4. Registers the smoke step in ci.yml (w19 follow-up).
+    if (SMOKE_CONTRACT.pixelDiffMode !== 'structural-only') {
+      throw new Error('current commit must be structural-only under active R-4 fallback');
+    }
+  });
+
+  it('the smoke target package @forgeax/hello-asi-world is not registered in pnpm workspace this commit', () => {
+    // pnpm-workspace.yaml + apps/hello/asi-world/package.json are
+    // upstream-owned. w19 (config) creates the package.json once
+    // upstream lands. The acceptance check
+    //   `pnpm --filter @forgeax/hello-asi-world smoke`
+    // cannot execute on this commit; recorded as deferred in milestone
+    // CI sweep notes.
+    const acceptance = 'pnpm --filter @forgeax/hello-asi-world smoke';
+    if (!acceptance.includes('@forgeax/hello-asi-world')) {
+      throw new Error('acceptance command drifted');
+    }
+  });
+});