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

package/src/__tests__/render-system-fold-fallback.unit.test.ts

@@ -0,0 +1,151 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M2 / w9 — fold-bucket
+// uniform-cap fallback functional unit tests.
+//
+// AC-05 (b) runtime behaviour: when caps.storageBuffer===false and a fold
+// bucket carries more than 128 instances, the engine fires a structured
+// `RhiError(code='instancing-exceeds-uniform-cap')` AND falls the bucket
+// back to per-entity drawIndexed (no identity-buffer collapse — see
+// research F-4 / R-4 + plan-decisions D-9).
+//
+// Boundary matrix (plan-strategy 4 R-4):
+//   storageBuffer=false, count=129 (just over cap)         -> error + fallback
+//   storageBuffer=false, count=128 (at cap)                -> no error, fold
+//   storageBuffer=false, count=129 scope='tilemap-chunk'   -> error + fallback
+//   storageBuffer=true,  count=10000                       -> no error, fold
+//   storageBuffer=false, singleton bucket (count=1)        -> no error path
+//
+// The fallback path is exposed as the pure helper
+// `evaluateFoldBucketUniformCap(bucket, caps, scope)` co-located with
+// `foldDispatchBuckets` in record/mesh-ssbo.ts: keeping it next to the
+// bucket type definition lets the record-stage dispatch site (w11) call
+// one branch instead of inlining the cap arithmetic, and lets this unit
+// test drive the decision without booting recordFrame (D-9: shared
+// fallback exit with the mode-gate bypass means the helper output is
+// the SSOT for "should this bucket fold or fall back?").
+
+import { RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  evaluateFoldBucketUniformCap,
+  type FoldBucket,
+} from '../../../render/src/record/mesh-ssbo';
+import type { DispatchEntry } from '../../../render/src/render-system-extract';
+
+const FOLD_UNIFORM_CAP = 128;
+
+function mockBucket(count: number, materialHandle = 7, layer = 0): FoldBucket {
+  const transforms = new Float32Array(count * 16);
+  // Each instance: identity mat4 (only matters for runtime stride; assertion
+  // is on bucket count, not transform values).
+  for (let i = 0; i < count; i++) {
+    transforms[i * 16 + 0] = 1;
+    transforms[i * 16 + 5] = 1;
+    transforms[i * 16 + 10] = 1;
+    transforms[i * 16 + 15] = 1;
+  }
+  const entries: DispatchEntry[] = [];
+  for (let i = 0; i < count; i++) {
+    entries.push({
+      entityIndex: i,
+      materialHandle,
+      renderableIndex: i,
+      passIndex: 0,
+      queue: 3000,
+      layer,
+      tags: {},
+      renderState: undefined,
+      defines: undefined,
+      vertexEntry: undefined,
+      fragmentEntry: undefined,
+      materialShaderId: undefined,
+      paramSnapshot: undefined,
+    });
+  }
+  return {
+    entries,
+    bucketSize: count,
+    transforms,
+    materialHandle,
+    layer,
+    sortKey: 0,
+  };
+}
+
+describe('M2 / w9 — fold-bucket uniform-cap fallback decision', () => {
+  it('storageBuffer=false + count > 128 -> fallback=true with RhiError carrying detail', () => {
+    const bucket = mockBucket(200);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    expect(decision.fallback).toBe(true);
+    expect(decision.error).toBeInstanceOf(RhiError);
+    expect(decision.error?.code).toBe('instancing-exceeds-uniform-cap');
+    if (decision.error?.code === 'instancing-exceeds-uniform-cap') {
+      const d = decision.error.detail as
+        | { requested: number; limit: 128; scope: 'sprite' | 'tilemap-chunk' }
+        | undefined;
+      expect(d?.requested).toBe(200);
+      expect(d?.limit).toBe(FOLD_UNIFORM_CAP);
+      expect(d?.scope).toBe('sprite');
+    }
+    expect(decision.error?.expected.length).toBeGreaterThan(0);
+    expect(decision.error?.hint.length).toBeGreaterThan(0);
+  });
+
+  it('storageBuffer=false + count = 128 -> no fallback, no error (cap inclusive)', () => {
+    const bucket = mockBucket(128);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    expect(decision.fallback).toBe(false);
+    expect(decision.error).toBeUndefined();
+  });
+
+  it('storageBuffer=false + count = 129 -> fallback fires (boundary just above cap)', () => {
+    const bucket = mockBucket(129);
+    const decision = evaluateFoldBucketUniformCap(
+      bucket,
+      { storageBuffer: false },
+      'tilemap-chunk',
+    );
+    expect(decision.fallback).toBe(true);
+    expect(decision.error?.code).toBe('instancing-exceeds-uniform-cap');
+    if (decision.error?.code === 'instancing-exceeds-uniform-cap') {
+      const d = decision.error.detail as
+        | { requested: number; limit: 128; scope: 'sprite' | 'tilemap-chunk' }
+        | undefined;
+      expect(d?.scope).toBe('tilemap-chunk');
+      expect(d?.requested).toBe(129);
+    }
+  });
+
+  it('storageBuffer=true + count = 10_000 -> no fallback (WebGPU has no UBO cap)', () => {
+    const bucket = mockBucket(10000);
+    const decision = evaluateFoldBucketUniformCap(bucket, { storageBuffer: true }, 'sprite');
+    expect(decision.fallback).toBe(false);
+    expect(decision.error).toBeUndefined();
+  });
+
+  it('singleton bucket (bucketSize=1) -> no fallback regardless of caps', () => {
+    const bucket = mockBucket(1);
+    const decisionFalse = evaluateFoldBucketUniformCap(bucket, { storageBuffer: false }, 'sprite');
+    const decisionTrue = evaluateFoldBucketUniformCap(bucket, { storageBuffer: true }, 'sprite');
+    expect(decisionFalse.fallback).toBe(false);
+    expect(decisionFalse.error).toBeUndefined();
+    expect(decisionTrue.fallback).toBe(false);
+    expect(decisionTrue.error).toBeUndefined();
+  });
+
+  it('scope is reflected verbatim in detail (no remapping)', () => {
+    const bucketSprite = mockBucket(200);
+    const bucketTilemap = mockBucket(200);
+    const dSprite = evaluateFoldBucketUniformCap(bucketSprite, { storageBuffer: false }, 'sprite');
+    const dTilemap = evaluateFoldBucketUniformCap(
+      bucketTilemap,
+      { storageBuffer: false },
+      'tilemap-chunk',
+    );
+    if (dSprite.error?.code === 'instancing-exceeds-uniform-cap') {
+      expect((dSprite.error.detail as { scope: string }).scope).toBe('sprite');
+    }
+    if (dTilemap.error?.code === 'instancing-exceeds-uniform-cap') {
+      expect((dTilemap.error.detail as { scope: string }).scope).toBe('tilemap-chunk');
+    }
+  });
+});

package/src/__tests__/render-system-fold-material.unit.test.ts

@@ -0,0 +1,143 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w2 — AC-10 multi-material.
+//
+// Drives the pure fold helper for the AC-10 boundary: a single chunk
+// spanning multiple atlas/material handles. Same Layer.value + same posZ +
+// 2 different materialHandle values must produce 2 separate buckets — the
+// fold must NOT merge them into one bucket (would render with the wrong
+// texture, requirements AC-10).
+//
+// Bucket key is the three-tuple (Layer.value, posZ, materialHandle). The
+// fold's correctness on the materialHandle leg is what this test pins.
+
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { foldDispatchBuckets } from '../../../render/src/record/mesh-ssbo';
+import type { DispatchEntry } from '../../../render/src/render-system-extract';
+import { TRANSPARENT_SORT_MODE_LAYER_Z } from '../../../render/src/systems/transparent-sort-config';
+
+function mockEntry(opts: {
+  renderableIndex: number;
+  materialHandle: number;
+  layer: number;
+}): DispatchEntry {
+  return {
+    entityIndex: opts.renderableIndex,
+    materialHandle: opts.materialHandle,
+    renderableIndex: opts.renderableIndex,
+    passIndex: 0,
+    queue: RenderQueue.Transparent,
+    layer: opts.layer,
+    tags: {},
+    renderState: undefined,
+    defines: undefined,
+    vertexEntry: undefined,
+    fragmentEntry: undefined,
+    materialShaderId: undefined,
+    paramSnapshot: undefined,
+  };
+}
+
+function mockRenderable(tz: number): {
+  transform: { world: Float32Array };
+  material: { transparent?: true | undefined };
+} {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[14] = tz;
+  // PR #502 fix + feat-20260625 R2 fix-up: `transparent: true` preserves the
+  // fold-eligible behavior these material-keyed tests exercise. The
+  // discriminator migrated from `shadingModel === 'sprite'` to
+  // `transparent === true` (M3 / w15 collapsed the sprite union member).
+  return { transform: { world }, material: { transparent: true } };
+}
+
+describe('foldDispatchBuckets — AC-10 multi-material boundary (w2)', () => {
+  it('2 different materialHandle values with same (layer, posZ) -> 2 separate buckets', () => {
+    // Layout (ordered by mode-0 sort which is stable within (layer, posZ)):
+    // [M1, M1, M1, M2, M2] — 3 entries with materialHandle=11 followed by
+    // 2 with materialHandle=22, all same layer=5 and same posZ=3.0.
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 11, layer: 5 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 11, layer: 5 }),
+      mockEntry({ renderableIndex: 2, materialHandle: 11, layer: 5 }),
+      mockEntry({ renderableIndex: 3, materialHandle: 22, layer: 5 }),
+      mockEntry({ renderableIndex: 4, materialHandle: 22, layer: 5 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+      mockRenderable(3.0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(2);
+    const b0 = buckets[0];
+    const b1 = buckets[1];
+    expect(b0).toBeDefined();
+    expect(b1).toBeDefined();
+    if (b0 === undefined || b1 === undefined) return;
+    expect(b0.materialHandle).toBe(11);
+    expect(b0.bucketSize).toBe(3);
+    expect(b1.materialHandle).toBe(22);
+    expect(b1.bucketSize).toBe(2);
+  });
+
+  it('2 material runs interleaved (M1, M2, M1, M2) -> 4 separate singleton buckets (no string-bucket bug)', () => {
+    // The fold operator walks consecutive runs only; non-consecutive
+    // entries of the same material must NOT be merged into one bucket
+    // (would re-order draws, breaking transparent-sort stability).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 22, layer: 0 }),
+      mockEntry({ renderableIndex: 2, materialHandle: 11, layer: 0 }),
+      mockEntry({ renderableIndex: 3, materialHandle: 22, layer: 0 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(0),
+      mockRenderable(0),
+      mockRenderable(0),
+      mockRenderable(0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    // 4 singleton buckets — consecutive-run fold preserves stable ordering.
+    expect(buckets).toHaveLength(4);
+    for (const b of buckets) {
+      expect(b.bucketSize).toBe(1);
+    }
+  });
+
+  it('two-material run with material key as bucket discriminator: distinct material -> never merged', () => {
+    // Edge: same layer + same posZ + different materialHandle. Even if
+    // (layer, posZ) match, materialHandle is the third key dimension and
+    // must split the bucket. This is the AC-10 essence (multi-atlas chunk).
+    const entries: DispatchEntry[] = [
+      mockEntry({ renderableIndex: 0, materialHandle: 100, layer: 9 }),
+      mockEntry({ renderableIndex: 1, materialHandle: 200, layer: 9 }),
+    ];
+    const renderables: ReturnType<typeof mockRenderable>[] = [
+      mockRenderable(4.0),
+      mockRenderable(4.0),
+    ];
+
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+
+    expect(buckets).toHaveLength(2);
+    const b0 = buckets[0];
+    const b1 = buckets[1];
+    expect(b0).toBeDefined();
+    expect(b1).toBeDefined();
+    if (b0 === undefined || b1 === undefined) return;
+    expect(b0.materialHandle).toBe(100);
+    expect(b1.materialHandle).toBe(200);
+    expect(b0.bucketSize).toBe(1);
+    expect(b1.bucketSize).toBe(1);
+  });
+});

package/src/__tests__/render-system-fold-metrics.unit.test.ts

@@ -0,0 +1,170 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M3 / w12 — fold metric
+// counter unit tests (AC-06).
+//
+// Drives the pure helper `incrementFoldedDrawsMetric(plan, metrics)` co-
+// located in record/mesh-ssbo.ts: every fold-eligible head bucket
+// (bucketSize > 1) in the dispatch plan contributes one
+// `metrics.increment('render.instancing.foldedDraws')` call. The helper is
+// the SSOT for "how many instanced drawIndexed will this frame emit"; the
+// record-stage consumer calls it once per recordFrame after the cap-fallback
+// filter (M2 / w11) so cap-overrun buckets — which have been removed from
+// the plan — do not contribute to the counter.
+//
+// Coverage (AC-06):
+//   (1) mode-0 fold-eligible plan -> increment count == fold head count.
+//   (2) mode-bypass plan (all singletons -> empty headBuckets) -> no
+//       increment (per-entity drawIndexed does not count, plan-strategy
+//       D-3 "instanced draw call" semantics).
+//   (3) cap-fallback filtered plan -> increment count tracks the filtered
+//       count, not the pre-filter bucket count (M2 / w11 cap-overrun
+//       buckets removed from plan upstream).
+//   (4) `metrics.reset()` zeroes the counter; next frame increments start
+//       from 1 again (test isolation hook).
+//   (5) Multi-bucket plan accumulates correctly (3 head buckets -> +3).
+//
+// Constraints from plan-strategy §2 D-3 / research F-5 / N-3:
+//   - Counter key = `render.instancing.foldedDraws` (verbatim).
+//   - Lives on `EngineMetrics` (runtime counter, dot-namespace); does NOT
+//     touch forgeax-metrics.schema.json (N-3: that schema closes the 5
+//     CI MetricKind, unrelated to runtime counters).
+//   - Semantics: count of instanced drawIndexed emitted this frame; not
+//     entity count, not pre-filter bucket count.
+
+import { describe, expect, it, vi } from 'vitest';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import {
+  type FoldBucket,
+  type FoldDispatchPlan,
+  incrementFoldedDrawsMetric,
+} from '../../../render/src/record/mesh-ssbo';
+import type { DispatchEntry } from '../../../render/src/render-system-extract';
+
+const METRIC_KEY = 'render.instancing.foldedDraws';
+
+function mockEntry(renderableIndex: number, materialHandle: number, layer: number): DispatchEntry {
+  return {
+    entityIndex: renderableIndex,
+    materialHandle,
+    renderableIndex,
+    passIndex: 0,
+    queue: 3000,
+    layer,
+    tags: {},
+    renderState: undefined,
+    defines: undefined,
+    vertexEntry: undefined,
+    fragmentEntry: undefined,
+    materialShaderId: undefined,
+    paramSnapshot: undefined,
+  };
+}
+
+function mockBucket(count: number, materialHandle = 7, layer = 0): FoldBucket {
+  const transforms = new Float32Array(count * 16);
+  const entries: DispatchEntry[] = [];
+  for (let i = 0; i < count; i++) {
+    entries.push(mockEntry(i, materialHandle, layer));
+  }
+  return { entries, bucketSize: count, transforms, materialHandle, layer, sortKey: 0 };
+}
+
+function planFromBuckets(headBuckets: ReadonlyMap<number, FoldBucket>): FoldDispatchPlan {
+  let folded = 0;
+  for (const b of headBuckets.values()) {
+    if (b.bucketSize > 1) folded += 1;
+  }
+  return { headBuckets, skipIndices: new Set<number>(), foldedBucketCount: folded };
+}
+
+describe('M3 / w12 — incrementFoldedDrawsMetric (AC-06)', () => {
+  it('fold-eligible plan with 1 head bucket -> metric == 1', () => {
+    const metrics = createEngineMetrics();
+    const plan = planFromBuckets(new Map([[0, mockBucket(5)]]));
+
+    incrementFoldedDrawsMetric(plan, metrics);
+
+    expect(metrics.snapshot()[METRIC_KEY]).toBe(1);
+  });
+
+  it('multi-bucket plan: 3 head buckets -> metric == 3 (accumulation)', () => {
+    const metrics = createEngineMetrics();
+    const plan = planFromBuckets(
+      new Map([
+        [0, mockBucket(4, 1, 0)],
+        [4, mockBucket(3, 2, 0)],
+        [7, mockBucket(2, 3, 1)],
+      ]),
+    );
+
+    incrementFoldedDrawsMetric(plan, metrics);
+
+    expect(metrics.snapshot()[METRIC_KEY]).toBe(3);
+  });
+
+  it('empty plan (mode-bypass, all singletons -> headBuckets empty) -> metric unset', () => {
+    // Mode-bypass (D-5): mode != 0 yields per-entry singleton buckets which
+    // buildFoldDispatchPlan filters out (bucketSize <= 1 skipped). The
+    // resulting plan has empty headBuckets so no instanced drawIndexed
+    // emits, and the per-entity drawIndexed path does NOT count toward the
+    // metric (plan-strategy D-3 / w12 acceptance criterion 2).
+    const metrics = createEngineMetrics();
+    const plan = planFromBuckets(new Map<number, FoldBucket>());
+
+    incrementFoldedDrawsMetric(plan, metrics);
+
+    expect(metrics.snapshot()[METRIC_KEY]).toBeUndefined();
+  });
+
+  it('cap-fallback filtered plan: pre-filter had 3 heads, filter dropped 1 (cap-overrun) -> metric == 2', () => {
+    // Simulates the M2 / w11 cap-fallback exit in render-system-record.ts:
+    // the dispatch site rebuilds the plan with the cap-overrun bucket
+    // removed BEFORE calling this helper. The metric tracks the post-
+    // filter count (acceptance criterion 3 — overrun bucket members get
+    // per-entity drawIndexed, which does not count as an instanced draw).
+    const metrics = createEngineMetrics();
+    const filteredPlan = planFromBuckets(
+      new Map([
+        [0, mockBucket(4)],
+        [10, mockBucket(2)],
+        // pre-filter [20, mockBucket(200)] removed by cap-fallback in record-stage
+      ]),
+    );
+
+    incrementFoldedDrawsMetric(filteredPlan, metrics);
+
+    expect(metrics.snapshot()[METRIC_KEY]).toBe(2);
+  });
+
+  it('reset() zeros the counter; next frame starts from 1 (test isolation hook)', () => {
+    const metrics = createEngineMetrics();
+    const plan = planFromBuckets(new Map([[0, mockBucket(3)]]));
+
+    incrementFoldedDrawsMetric(plan, metrics);
+    expect(metrics.snapshot()[METRIC_KEY]).toBe(1);
+
+    metrics.reset();
+    expect(metrics.snapshot()[METRIC_KEY]).toBeUndefined();
+
+    incrementFoldedDrawsMetric(plan, metrics);
+    expect(metrics.snapshot()[METRIC_KEY]).toBe(1);
+  });
+
+  it('uses metrics.increment() exactly N times for a plan with N head buckets (mock metrics)', () => {
+    // Mock-driven assertion (plan w12: "inject mock metrics into the fold
+    // helper, assert increment call count"). Spy verifies both call count
+    // AND key.
+    const mockMetrics = { increment: vi.fn() };
+    const plan = planFromBuckets(
+      new Map([
+        [0, mockBucket(5)],
+        [5, mockBucket(2)],
+      ]),
+    );
+
+    incrementFoldedDrawsMetric(plan, mockMetrics);
+
+    expect(mockMetrics.increment).toHaveBeenCalledTimes(2);
+    expect(mockMetrics.increment).toHaveBeenNthCalledWith(1, METRIC_KEY);
+    expect(mockMetrics.increment).toHaveBeenNthCalledWith(2, METRIC_KEY);
+  });
+});

package/src/__tests__/render-system-fold-modegate.unit.test.ts

@@ -0,0 +1,166 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w3 — mode-gate (D-5).
+//
+// Drives the pure fold helper for the four transparent-sort modes:
+//   mode 0 (LAYER_Z)   -> fold on posZ (world[14]); equal-key runs collapse.
+//   mode 1 (LAYER_Y)   -> fold on posY (world[13]); same-row tiles collapse.
+//   mode 2 (LAYER_YZ)  -> bypass per-entity (composite foot-Y key).
+//   mode 3 (DISTANCE)  -> bypass per-entity (per-entity camera distance).
+//
+// Bypass semantics (modes 2/3): each DispatchEntry produces its own
+// singleton bucket (bucketSize=1). The fold dispatcher (record-stage)
+// treats singleton buckets identically to per-entity drawIndexed (charter
+// P3 silent fallback — no error, no warning).
+//
+// Mode 1 (LAYER_Y) folds using posY as the sort-axis bucket key: tiles in
+// the same row share posY and consecutive same-material runs collapse into
+// one instanced draw call (D-5 extension).
+
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { foldDispatchBuckets } from '../../../render/src/record/mesh-ssbo';
+import type { DispatchEntry } from '../../../render/src/render-system-extract';
+import {
+  TRANSPARENT_SORT_MODE_DISTANCE,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../../../render/src/systems/transparent-sort-config';
+
+function mockEntry(opts: {
+  renderableIndex: number;
+  materialHandle: number;
+  layer: number;
+}): DispatchEntry {
+  return {
+    entityIndex: opts.renderableIndex,
+    materialHandle: opts.materialHandle,
+    renderableIndex: opts.renderableIndex,
+    passIndex: 0,
+    queue: RenderQueue.Transparent,
+    layer: opts.layer,
+    tags: {},
+    renderState: undefined,
+    defines: undefined,
+    vertexEntry: undefined,
+    fragmentEntry: undefined,
+    materialShaderId: undefined,
+    paramSnapshot: undefined,
+  };
+}
+
+function mockRenderable(
+  tz: number,
+  ty = 0,
+): {
+  transform: { world: Float32Array };
+  material: { transparent?: true | undefined };
+} {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[13] = ty;
+  world[14] = tz;
+  // PR #502 fix + feat-20260625 R2 fix-up: `transparent: true` preserves the
+  // fold-eligible behavior these mode-gate tests exercise; see
+  // record/mesh-ssbo.ts transparent-pass-only gate (the sprite
+  // discriminator was removed in M3 / w15 and replaced with `transparent`).
+  return { transform: { world }, material: { transparent: true } };
+}
+
+describe('foldDispatchBuckets — mode-gate (D-5, w3)', () => {
+  // 5 entries all sharing (layer=0, posZ=0, posY=0, materialHandle=1).
+  // Under mode 0 and 1 they collapse to 1 bucket. Under mode 2/3 they each
+  // get their own singleton bucket (bypass).
+  function makeUniformInputs(N: number): {
+    entries: DispatchEntry[];
+    renderables: ReturnType<typeof mockRenderable>[];
+  } {
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      renderables.push(mockRenderable(0, 0));
+    }
+    return { entries, renderables };
+  }
+
+  it('mode 0 (LAYER_Z) — N equal-key entries collapse to 1 bucket', () => {
+    const { entries, renderables } = makeUniformInputs(5);
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Z, renderables);
+    expect(buckets).toHaveLength(1);
+    const b = buckets[0];
+    expect(b).toBeDefined();
+    if (b === undefined) return;
+    expect(b.bucketSize).toBe(5);
+  });
+
+  it('mode 1 (LAYER_Y) — N equal-posY entries collapse to 1 bucket', () => {
+    const { entries, renderables } = makeUniformInputs(5);
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Y, renderables);
+    expect(buckets).toHaveLength(1);
+    const b = buckets[0];
+    expect(b).toBeDefined();
+    if (b === undefined) return;
+    expect(b.bucketSize).toBe(5);
+  });
+
+  it('mode 1 (LAYER_Y) — distinct posY per entry -> N singleton buckets', () => {
+    // Each tile is in a different row (different posY); no consecutive run
+    // can form, so each entry becomes its own bucket.
+    const N = 4;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      renderables.push(mockRenderable(0, i * 16)); // posY = 0, 16, 32, 48
+    }
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Y, renderables);
+    expect(buckets).toHaveLength(N);
+    for (const b of buckets) expect(b.bucketSize).toBe(1);
+  });
+
+  it('mode 1 (LAYER_Y) — sortKey carries posY (world[13])', () => {
+    // Single bucket from N entries at posY=3.0; sortKey must equal 3.0.
+    const N = 3;
+    const entries: DispatchEntry[] = [];
+    const renderables: ReturnType<typeof mockRenderable>[] = [];
+    for (let i = 0; i < N; i++) {
+      entries.push(mockEntry({ renderableIndex: i, materialHandle: 1, layer: 0 }));
+      renderables.push(mockRenderable(0, 3.0));
+    }
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_Y, renderables);
+    expect(buckets).toHaveLength(1);
+    const b = buckets[0];
+    expect(b).toBeDefined();
+    if (b === undefined) return;
+    expect(b.sortKey).toBeCloseTo(3.0);
+  });
+
+  it('mode 2 (LAYER_YZ) — N entries bypass to N singleton buckets (no fold)', () => {
+    const { entries, renderables } = makeUniformInputs(5);
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_YZ, renderables);
+    expect(buckets).toHaveLength(5);
+    for (const b of buckets) expect(b.bucketSize).toBe(1);
+  });
+
+  it('mode 3 (DISTANCE) — N entries bypass to N singleton buckets (no fold)', () => {
+    const { entries, renderables } = makeUniformInputs(5);
+    const buckets = foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_DISTANCE, renderables);
+    expect(buckets).toHaveLength(5);
+    for (const b of buckets) expect(b.bucketSize).toBe(1);
+  });
+
+  it('mode-gate is silent: bypass modes 2/3 do not throw or fire errors', () => {
+    const { entries, renderables } = makeUniformInputs(3);
+    // The pure helper does not have access to errorRegistry; "silent"
+    // here means no thrown exception. Negative-space assertion.
+    expect(() =>
+      foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_LAYER_YZ, renderables),
+    ).not.toThrow();
+    expect(() =>
+      foldDispatchBuckets(entries, TRANSPARENT_SORT_MODE_DISTANCE, renderables),
+    ).not.toThrow();
+  });
+});

package/src/__tests__/render-system-fold-scene-instances.unit.test.ts

@@ -0,0 +1,51 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M4 / w15 — AC-08
+// guard: `packages/render/src/scene-instances/` directory file set must
+// remain at the feat baseline (no GPU-instancing files added).
+//
+// Why: requirements §4 AC-08 + research F-7 + plan-strategy §3.1 say the
+// `scene-instances/` directory carries **skin joint post-spawn semantics
+// only** (`post-spawn-resolve-joints.ts` + barrel `index.ts`). The naming
+// collision with the new GPU-instancing fold path (this feat) is the
+// SSOT chunk of confusion AGENTS.md warns about: AI users grepping
+// `scene-instances` while debugging GPU instancing would land on the
+// wrong file. AC-08 closes the collision by **forbidding new files into
+// this directory** until the rename tweak (OOS-4) lands separately.
+//
+// Mechanism: snapshot the baseline file set (3 entries: `index.ts`,
+// `post-spawn-resolve-joints.ts`, `__tests__/`) and fail the unit test if
+// `fs.readdirSync` reports any extra entry. This guard runs in CI on every
+// PR via `pnpm test:unit`; an attempt to land a `fold-bucket-builder.ts`
+// or similar GPU-instancing file in this directory trips the guard
+// immediately rather than 8 weeks later when an AI user grep-locates it.
+//
+// Constraints from upstream:
+//   - requirements §3 OOS-4: scene-instances/ rename is a separate
+//     follow-up tweak, not part of this feat. This test enforces the
+//     freeze, not the rename.
+//   - research F-7: positive + negative grep proves the directory's two
+//     files have zero GPU-instancing call sites; baseline set is stable.
+//   - plan-strategy §3.1: targetFiles for this feat do not cross into
+//     `packages/render/src/scene-instances/`.
+//
+// FALSIFY anchor (documented, not in CI): `touch packages/runtime/src/
+// scene-instances/fold-bucket-builder.ts` -> this test goes red.
+
+import { readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// runtime/src/__tests__ -> packages/render/src/scene-instances/
+const SCENE_INSTANCES_DIR = resolve(HERE, '..', '..', '..', 'render', 'src', 'scene-instances');
+
+const BASELINE_ENTRIES: readonly string[] = ['post-spawn-resolve-joints.ts'];
+
+describe('scene-instances/ directory guard (AC-08)', () => {
+  it('contains exactly the baseline file set (no GPU-instancing additions)', () => {
+    const actual = readdirSync(SCENE_INSTANCES_DIR).sort();
+    const expected = [...BASELINE_ENTRIES].sort();
+    expect(actual).toEqual(expected);
+  });
+});