@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/lod-occlusion-inspection.integration.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest';
+import { resolveInspectionBuild } from '../render-system';
+import { inspectLodOcclusion } from '../scene/visibility/inspection';
+
+describe('LOD occlusion inspection lifecycle', () => {
+  it('uses the build-tool revision for inspection submits', () => {
+    expect(resolveInspectionBuild({ build: 'merge-ref-123' })).toBe('merge-ref-123');
+    expect(resolveInspectionBuild({ build: undefined })).toBe('render-system');
+  });
+
+  it('publishes one detached row per World attachment for a single submit', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'world-a', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false },
+      degradation: { active: false },
+      samples: [],
+      submit: { frameId: 10, build: 'test-build', deviceGeneration: 2 },
+      budget: {
+        configuredQueryBudget: 2048,
+        effectiveQueryBudget: 2048,
+        settleSubmits: 98,
+        retestSubmits: 44,
+        expirySubmits: 88,
+      },
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          rows: [
+            {
+              root: {
+                guid: '018e7a4d-1234-7abc-8def-000000000002',
+                sourceKey: 'assets/lod-scene.gltf',
+              },
+              view: {
+                attachmentId: 'world-a',
+                cameraEntity: 1,
+                viewRole: 'main',
+                viewGeneration: 4,
+              },
+              slot: { primitiveSlot: 2, slotGeneration: 9 },
+              generation: 10,
+              count: { candidates: 2, visible: 1, occluded: 1 },
+              lodHistogram: [{ level: 0, count: 2 }],
+              queryLatencyUs: { median: 4, p95: 8, last: 3 },
+              pagePressure: { used: 1, capacity: 3 },
+              fallback: { active: false },
+              degradation: { active: false },
+              samples: [],
+            },
+          ],
+        },
+        {
+          attachmentId: 'world-b',
+          rows: [],
+        },
+      ],
+    });
+
+    expect(inspection.schema).toBe('forgeax::lod-occlusion-inspection::v2');
+    expect(inspection.submit).toEqual({ frameId: 10, build: 'test-build', deviceGeneration: 2 });
+    expect(inspection.budget.effectiveQueryBudget).toBe(2048);
+    expect(inspection.worlds.map((world) => world.attachmentId)).toEqual(['world-a', 'world-b']);
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'unavailable',
+      reason: 'projection-only',
+    });
+    expect(inspection.worlds[0]?.rows[0]?.count).toEqual({
+      candidates: 2,
+      visible: 1,
+      occluded: 1,
+    });
+    expect(Object.isFrozen(inspection.worlds)).toBe(true);
+    expect(Object.isFrozen(inspection.worlds[0]?.rows)).toBe(true);
+  });
+
+  it('only accepts same-submit World attribution with the parent submit identity', () => {
+    const submit = { frameId: 12, build: 'test-build', deviceGeneration: 2 };
+    const row = {
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: {
+        attachmentId: 'world-a',
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 4,
+      },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 12,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    };
+    const inspection = inspectLodOcclusion({
+      ...row,
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row],
+        },
+      ],
+    });
+
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+    expect(() =>
+      inspectLodOcclusion({
+        ...row,
+        submit,
+        worlds: [
+          {
+            attachmentId: 'world-a',
+            attribution: {
+              status: 'same-submit',
+              submit: { ...submit, frameId: submit.frameId + 1 },
+            },
+            rows: [row],
+          },
+        ],
+      }),
+    ).toThrow('world attribution must reference the parent inspection submit');
+  });
+
+  it('joins reordered World rows by attachment identity, not array position', () => {
+    const submit = { frameId: 20, build: 'test-build', deviceGeneration: 3 };
+    const row = (attachmentId: string, primitiveSlot: number, candidates: number) => ({
+      root: { guid: `asset-${attachmentId}`, sourceKey: `world:${attachmentId}` },
+      view: {
+        attachmentId,
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 7,
+      },
+      slot: { primitiveSlot, slotGeneration: 11 },
+      generation: 20,
+      count: { candidates, visible: candidates - 1, occluded: 1 },
+      lodHistogram: [{ level: 1, count: candidates }],
+      queryLatencyUs: { median: 3, p95: 5, last: 2 },
+      pagePressure: { used: 2, capacity: 12 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    });
+    const inspection = inspectLodOcclusion({
+      ...row('world-a', 4, 3),
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-b',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-b', 9, 5)],
+        },
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-a', 4, 3)],
+        },
+      ],
+    });
+
+    const byAttachment = new Map(
+      inspection.worlds.map((world) => [world.attachmentId, world] as const),
+    );
+    expect(byAttachment.get('world-a')?.rows[0]?.slot).toEqual({
+      primitiveSlot: 4,
+      slotGeneration: 11,
+    });
+    expect(byAttachment.get('world-b')?.rows[0]?.count.candidates).toBe(5);
+    expect(byAttachment.get('world-b')?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+  });
+
+  it('keeps identity and generation attached to a failed publication without suppressing draw', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'main', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 100_000, visible: 100_000, occluded: 0 },
+      lodHistogram: [{ level: 0, count: 100_000 }],
+      queryLatencyUs: { median: 0, p95: 0, last: 0 },
+      pagePressure: { used: 3, capacity: 3 },
+      fallback: {
+        active: true,
+        reason: 'page-exhausted',
+        error: {
+          code: 'occlusion-query-unavailable',
+          expected: 'a bounded query page reservation',
+          hint: 'keep the candidate visible and retry on the next submitted frame',
+          detail: { capacity: 3 },
+        },
+      },
+      degradation: { active: true, reason: 'all-visible' },
+      samples: [],
+    });
+
+    expect(inspection.fallback.active).toBe(true);
+    expect(inspection.degradation).toEqual({ active: true, reason: 'all-visible' });
+    expect(inspection.count.visible).toBe(inspection.count.candidates);
+    expect(inspection.generation).toBe(10);
+  });
+});

package/src/__tests__/lod-occlusion-inspection.schema.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, test } from 'vitest';
+import type { LodOcclusionInspection } from '../scene/visibility/inspection';
+
+test('LOD occlusion inspection is detached JSON-safe POD', () => {
+  const inspection = {} as LodOcclusionInspection;
+  expectTypeOf(inspection.root.guid).toEqualTypeOf<string>();
+  expectTypeOf(inspection.samples).toEqualTypeOf<
+    readonly LodOcclusionInspection['samples'][number][]
+  >();
+  // @ts-expect-error live GPU handles must not cross the inspection boundary
+  inspection.device;
+  // @ts-expect-error mutable renderer state must not cross the inspection boundary
+  inspection.mutableState;
+});

package/src/__tests__/lod-occlusion-inspection.unit.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import {
+  consumeLodOcclusionInspection,
+  inspectLodOcclusion,
+  LOD_OCCLUSION_INSPECTION_MAX_BYTES,
+  serializeLodOcclusionInspection,
+} from '../scene/visibility/inspection';
+
+const baseInput = {
+  root: { guid: '018e7a4d-1234-7abc-8def-000000000001', sourceKey: 'assets/lod-scene.gltf' },
+  view: { attachmentId: 'main', cameraEntity: 7, viewRole: 'main' as const, viewGeneration: 3 },
+  slot: { primitiveSlot: 11, slotGeneration: 2 },
+  generation: 9,
+  count: { candidates: 100_000, visible: 10_000, occluded: 90_000 },
+  lodHistogram: [
+    { level: 0, count: 5_000 },
+    { level: 1, count: 4_000 },
+    { level: 2, count: 1_000 },
+  ],
+  queryLatencyUs: { median: 42, p95: 91, last: 37 },
+  pagePressure: { used: 1, capacity: 3 },
+  fallback: { active: false as const },
+  degradation: { active: false as const },
+  samples: Array.from({ length: 80 }, (_, index) => ({
+    primitiveSlot: index,
+    level: index % 3,
+    visible: index % 2 === 0,
+  })),
+};
+
+describe('LOD occlusion inspection projection', () => {
+  it('publishes bounded identity, histogram, timing, pressure and stable samples', () => {
+    const inspection = inspectLodOcclusion(baseInput);
+
+    expect(inspection.schema).toBe('forgeax::lod-occlusion-inspection::v2');
+    expect(inspection.root).toEqual(baseInput.root);
+    expect(inspection.view).toEqual(baseInput.view);
+    expect(inspection.slot).toEqual(baseInput.slot);
+    expect(inspection.count).toEqual(baseInput.count);
+    expect(inspection.samples).toHaveLength(64);
+    expect(inspection.samples[0]?.primitiveSlot).toBe(0);
+    expect(inspection.samples[63]?.primitiveSlot).toBe(63);
+    expect(JSON.stringify(inspection).length).toBeLessThanOrEqual(
+      LOD_OCCLUSION_INSPECTION_MAX_BYTES,
+    );
+  });
+
+  it('serializes as detached POD and exposes a CLI recovery branch', () => {
+    const inspection = inspectLodOcclusion({
+      ...baseInput,
+      fallback: {
+        active: true,
+        reason: 'producer-failed',
+        error: {
+          code: 'asset-ddc-failed',
+          expected: 'a published DDC payload',
+          hint: 'inspect producer output, rebuild the source package, then retry',
+          detail: { sourceKey: baseInput.root.sourceKey },
+        },
+      },
+    });
+
+    const serialized = serializeLodOcclusionInspection(inspection);
+    expect(JSON.parse(serialized)).toEqual(inspection);
+    expect(consumeLodOcclusionInspection(inspection)).toEqual({
+      action: 'rebuild',
+      sourceKey: baseInput.root.sourceKey,
+      reason: 'producer-failed',
+    });
+    expect(serialized).not.toMatch(/handle|encoder|queue|mutable/i);
+  });
+});

package/src/__tests__/lod-occlusion-visual-evidence.ts

@@ -0,0 +1,91 @@
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+import { runOcclusionQueryDawnEvidence } from './occlusion-query.evidence';
+
+export interface LodOcclusionVisualEvidence {
+  readonly status: 'available' | 'unavailable';
+  readonly backend: 'dawn' | 'browser';
+  readonly identity: { readonly commit: string; readonly view: string };
+  readonly expectations: readonly string[];
+  readonly observed: readonly string[];
+  readonly verdict: 'pass' | 'unavailable';
+  readonly confidence: 'high' | 'none';
+  readonly reason?: string;
+}
+
+function identity(): { readonly commit: string; readonly view: string } {
+  return {
+    commit: resolveEvidenceCommitIdentity(),
+    view: 'lod-occlusion-visual:main:1',
+  };
+}
+
+const EXPECTATIONS = [
+  'occlusion-off preserves the full silhouette',
+  'two zero results suppress only after the confidence threshold',
+  'a positive retest makes the silhouette visible again',
+  'device-loss and stale results remain all-visible',
+] as const;
+
+export async function runLodOcclusionDawnVisualEvidence(): Promise<LodOcclusionVisualEvidence> {
+  const evidence = await runOcclusionQueryDawnEvidence();
+  if (evidence.status === 'unavailable') {
+    return {
+      status: 'unavailable',
+      backend: 'dawn',
+      identity: identity(),
+      expectations: EXPECTATIONS,
+      observed: [],
+      verdict: 'unavailable',
+      confidence: 'none',
+      reason: evidence.reason ?? 'Dawn evidence unavailable',
+    };
+  }
+  const observed = [
+    `zero-samples:${evidence.zeroSamples}`,
+    `positive-samples:${evidence.positiveSamples}`,
+    `out-of-order:${evidence.outOfOrder}`,
+    `stale-visible:${evidence.staleVisible}`,
+    `fault-visible:${evidence.faultVisible}`,
+  ];
+  return {
+    status: 'available',
+    backend: 'dawn',
+    identity: identity(),
+    expectations: EXPECTATIONS,
+    observed,
+    verdict:
+      evidence.zeroSamples === 0 &&
+      evidence.positiveSamples > 0 &&
+      evidence.outOfOrder &&
+      evidence.staleVisible &&
+      evidence.faultVisible
+        ? 'pass'
+        : 'unavailable',
+    confidence: 'high',
+  };
+}
+
+export function runLodOcclusionBrowserVisualEvidence(): LodOcclusionVisualEvidence {
+  if (typeof navigator === 'undefined' || navigator.gpu === undefined) {
+    return {
+      status: 'unavailable',
+      backend: 'browser',
+      identity: identity(),
+      expectations: EXPECTATIONS,
+      observed: [],
+      verdict: 'unavailable',
+      confidence: 'none',
+      reason: 'navigator.gpu unavailable; compositor capture was not attempted',
+    };
+  }
+  return {
+    status: 'unavailable',
+    backend: 'browser',
+    identity: identity(),
+    expectations: EXPECTATIONS,
+    observed: [],
+    verdict: 'unavailable',
+    confidence: 'none',
+    reason: 'browser compositor capture requires the visual runner',
+  };
+}

package/src/__tests__/lod-occlusion.browser.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { runLodOcclusionBrowserVisualEvidence } from './lod-occlusion-visual-evidence';
+
+describe('LOD occlusion Browser visual evidence', () => {
+  it('publishes compositor evidence or an explicit unavailable result', () => {
+    const evidence = runLodOcclusionBrowserVisualEvidence();
+    expect(evidence.backend).toBe('browser');
+    expect(evidence.identity.commit.length).toBeGreaterThan(0);
+    if (evidence.status === 'unavailable') {
+      expect(evidence.verdict).toBe('unavailable');
+      expect(evidence.confidence).toBe('none');
+      expect(evidence.reason).toContain('visual');
+    }
+  });
+});

package/src/__tests__/lod-occlusion.dawn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { runLodOcclusionDawnVisualEvidence } from './lod-occlusion-visual-evidence';
+
+describe('LOD occlusion Dawn visual evidence', () => {
+  it('proves matching-identity zero/positive readback and recovery invariants', async () => {
+    const evidence = await runLodOcclusionDawnVisualEvidence();
+    expect(evidence.status).toBe('available');
+    expect(evidence.verdict).toBe('pass');
+    expect(evidence.confidence).toBe('high');
+    expect(evidence.identity.commit.length).toBeGreaterThan(0);
+    expect(evidence.observed).toEqual(
+      expect.arrayContaining([
+        'zero-samples:0',
+        'out-of-order:true',
+        'stale-visible:true',
+        'fault-visible:true',
+      ]),
+    );
+  });
+});

package/src/__tests__/lod-selector.profile.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { projectedHeight, selectLod } from '../scene/visibility/lod-selector';
+
+describe('LOD selector profile evidence', () => {
+  it('records stable fixture identity with projected height and selected level', () => {
+    const fixture = 'lod-three-level-perspective';
+    const build = process.env.FORGEAX_BUILD_ID ?? 'workspace';
+    const height = projectedHeight({
+      radius: 1,
+      depth: 10,
+      projection: 'perspective',
+      fov: Math.PI / 2,
+    });
+    const selection = selectLod({
+      levels: [{ screenCoverage: 0.5 }, { screenCoverage: 0.2 }],
+      projectedHeight: height,
+      previousLevel: 0,
+      hysteresis: 0.1,
+      ready: [true, true, true],
+      historyValid: false,
+    });
+
+    expect({
+      fixture,
+      build,
+      projectedHeight: Math.round(height * 1e6) / 1e6,
+      selectedLevel: selection.level,
+    }).toEqual({
+      fixture,
+      build,
+      projectedHeight: 0.2,
+      selectedLevel: 1,
+    });
+  });
+});

package/src/__tests__/lod-selector.unit.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type LodSelectorInput,
+  projectedHeight,
+  selectLod,
+} from '../scene/visibility/lod-selector';
+
+const levels = [{ screenCoverage: 0.5 }, { screenCoverage: 0.2 }, { screenCoverage: 0.08 }];
+
+const input = (overrides: Partial<LodSelectorInput> = {}): LodSelectorInput => ({
+  levels,
+  projectedHeight: 0.3,
+  previousLevel: 0,
+  hysteresis: 0.1,
+  ready: [true, true, true, true],
+  historyValid: true,
+  ...overrides,
+});
+
+describe('LOD projected-height selector', () => {
+  it('uses perspective depth and scale without allocating a camera-specific state table', () => {
+    expect(
+      projectedHeight({ radius: 1, depth: 10, projection: 'perspective', fov: Math.PI / 2 }),
+    ).toBeCloseTo(0.2);
+    expect(
+      projectedHeight({ radius: 1, depth: 10, projection: 'orthographic', orthoHeight: 10 }),
+    ).toBeCloseTo(0.2);
+  });
+
+  it('selects across multiple levels from absolute coverage in one frame', () => {
+    expect(selectLod(input({ projectedHeight: 0.6 })).level).toBe(0);
+    expect(selectLod(input({ projectedHeight: 0.3 })).level).toBe(1);
+    expect(selectLod(input({ projectedHeight: 0.05 })).level).toBe(3);
+  });
+
+  it('drops history on a new view epoch and selects from current coverage', () => {
+    expect(
+      selectLod(input({ projectedHeight: 0.05, previousLevel: 0, historyValid: false })).level,
+    ).toBe(3);
+  });
+
+  it('uses hysteresis at a boundary and still permits a multi-level jump', () => {
+    expect(selectLod(input({ projectedHeight: 0.46, previousLevel: 0 })).level).toBe(0);
+    expect(selectLod(input({ projectedHeight: 0.39, previousLevel: 0 })).level).toBe(1);
+    expect(selectLod(input({ projectedHeight: 0.05, previousLevel: 0 })).level).toBe(3);
+  });
+
+  it('uses the adjacent threshold when a prior level crosses multiple boundaries', () => {
+    expect(selectLod(input({ projectedHeight: 0.19, previousLevel: 1 })).level).toBe(1);
+    expect(selectLod(input({ projectedHeight: 0.17, previousLevel: 1 })).level).toBe(2);
+    expect(selectLod(input({ projectedHeight: 0.21, previousLevel: 2 })).level).toBe(2);
+    expect(selectLod(input({ projectedHeight: 0.23, previousLevel: 2 })).level).toBe(1);
+  });
+
+  it('falls back toward LOD0 when the selected detail is not resident', () => {
+    expect(
+      selectLod(input({ projectedHeight: 0.05, ready: [true, false, false, false] })).level,
+    ).toBe(0);
+    expect(
+      selectLod(input({ projectedHeight: 0.05, ready: [true, false, false, true] })).level,
+    ).toBe(3);
+  });
+
+  it('returns LOD0 for invalid projection inputs', () => {
+    expect(selectLod(input({ projectedHeight: Number.NaN })).level).toBe(0);
+    expect(selectLod(input({ projectedHeight: -1 })).level).toBe(0);
+  });
+});