@forgeax/engine-render 0.1.21 → 0.1.24

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);
+  });
+});

package/src/__tests__/lod-visibility-identity.unit.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import {
+  type PrimitiveKey,
+  primitiveKey,
+  primitiveKeyId,
+  type ViewKey,
+  VisibilityFacetStore,
+  viewKey,
+} from '../scene/visibility/facet';
+
+const primitive = (slot: number, generation = 0): PrimitiveKey =>
+  primitiveKey({
+    attachmentId: 'world-a',
+    worldGeneration: 4,
+    primitiveSlot: slot,
+    slotGeneration: generation,
+  });
+
+const view = (
+  cameraEntity: number,
+  generation = 1,
+  viewRole: ViewKey['viewRole'] = 'main',
+): ViewKey =>
+  viewKey({ attachmentId: 'world-a', cameraEntity, viewRole, viewGeneration: generation });
+
+describe('LOD visibility facet identity', () => {
+  it('keeps attachment, camera role, and generation in the view identity', () => {
+    const store = new VisibilityFacetStore();
+    const main = view(7, 3, 'main');
+    const shadow = view(7, 3, 'shadow');
+
+    store.activateView(main);
+    store.activateView(shadow);
+    store.setCandidate(main, primitive(2), { level: 1, confidence: 0.8 });
+    store.setCandidate(shadow, primitive(2), { level: 0, confidence: 1 });
+
+    expect(store.getCandidate(main, primitive(2))).toEqual({ level: 1, confidence: 0.8 });
+    expect(store.getCandidate(shadow, primitive(2))).toEqual({ level: 0, confidence: 1 });
+    expect(store.inspect().activeViews).toBe(2);
+  });
+
+  it('keeps primitive slot identity separate across ABA generations', () => {
+    const store = new VisibilityFacetStore();
+    const current = primitive(5, 2);
+    const stale = primitive(5, 1);
+    const main = view(9);
+    store.activateView(main);
+    store.setCandidate(main, current, { level: 2, confidence: 0.6 });
+
+    expect(store.getCandidate(main, stale)).toBeUndefined();
+    expect(store.getCandidate(main, current)).toEqual({ level: 2, confidence: 0.6 });
+  });
+
+  it('rejects completion from a retired view or an older view generation', () => {
+    const store = new VisibilityFacetStore();
+    const active = view(3, 4);
+    const reused = view(3, 5);
+    const p = primitive(1);
+    store.activateView(active);
+    store.retireView(active);
+
+    expect(store.applyCompletion(active, p, 4, { level: 1, confidence: 0.5 })).toBe(false);
+    store.activateView(reused);
+    expect(store.applyCompletion(active, p, 5, { level: 0, confidence: 1 })).toBe(false);
+    expect(store.getCandidate(reused, p)).toBeUndefined();
+  });
+
+  it('does not use array position as attachment identity when worlds reorder', () => {
+    const store = new VisibilityFacetStore();
+    const worldA = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const worldB = viewKey({
+      attachmentId: 'world-b',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const primitiveA = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 0,
+      slotGeneration: 0,
+    });
+    const primitiveB = primitiveKey({
+      attachmentId: 'world-b',
+      worldGeneration: 9,
+      primitiveSlot: 0,
+      slotGeneration: 0,
+    });
+    store.activateView(worldA);
+    store.activateView(worldB);
+    store.setCandidate(worldA, primitiveA, { level: 1, confidence: 0.7 });
+    store.setCandidate(worldB, primitiveB, { level: 2, confidence: 0.9 });
+
+    expect(store.getCandidate(worldA, primitiveA)?.level).toBe(1);
+    expect(store.getCandidate(worldB, primitiveB)?.level).toBe(2);
+  });
+
+  it('advances hidden evidence on successful frames and expires it without a query', () => {
+    const budget = createVisibilityBudget();
+    const store = new VisibilityFacetStore(budget);
+    const main = view(11);
+    const p = primitive(3);
+    store.activateView(main);
+    store.setCandidate(main, p, { level: 1, confidence: 0 });
+    store.applyConfidence(main, p, { type: 'result', samples: 0, submissionGeneration: 1 });
+    store.applyConfidence(main, p, { type: 'result', samples: 0, submissionGeneration: 2 });
+    expect(store.getConfidence(main, p)).toMatchObject({ status: 'hidden', successfulSubmits: 0 });
+
+    for (let generation = 3; generation <= 2 + budget.retestSubmits; generation += 1) {
+      store.advanceSuccessfulSubmits(generation);
+    }
+    expect(store.getConfidence(main, p)).toMatchObject({
+      status: 'hidden',
+      successfulSubmits: budget.retestSubmits,
+    });
+    expect(store.shouldQuery(main, p)).toBe(true);
+
+    store.advanceSuccessfulSubmits(2 + budget.expirySubmits);
+    expect(store.getConfidence(main, p)).toMatchObject({
+      status: 'visible',
+      successfulSubmits: 0,
+      dirty: true,
+    });
+  });
+
+  it('dequeues bounded ready work and requeues only failed identities', () => {
+    const store = new VisibilityFacetStore();
+    const main = view(12);
+    const first = primitive(1);
+    const second = primitive(2);
+    store.activateView(main);
+    store.setCandidate(main, first, { level: 0, confidence: 1 });
+    store.setCandidate(main, second, { level: 0, confidence: 1 });
+
+    const page = store.dequeueQueryCandidates(main, 1);
+    expect(page).toHaveLength(1);
+    expect(page[0]?.primitive.primitiveSlot).toBe(1);
+    expect(store.dequeueQueryCandidates(main, 1)[0]?.primitive.primitiveSlot).toBe(2);
+
+    store.requeueQueryCandidate(main, first);
+    expect(store.dequeueQueryCandidates(main, 1)[0]?.primitive.primitiveSlot).toBe(1);
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(0);
+  });
+
+  it('keeps a first zero provisional so the production path submits the second query', () => {
+    const store = new VisibilityFacetStore();
+    const main = view(13);
+    const p = primitive(4);
+    store.activateView(main);
+    store.setCandidate(main, p, { level: 0, confidence: 1 });
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(1);
+    store.applyConfidence(main, p, { type: 'submit', submissionGeneration: 1 });
+    store.applyConfidence(main, p, { type: 'result', samples: 0, submissionGeneration: 1 });
+
+    expect(store.getConfidence(main, p)).toMatchObject({
+      status: 'visible',
+      zeroStreak: 1,
+      dirty: true,
+    });
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(1);
+  });
+
+  it('removes pruned queue identities without leaving stale work to scan', () => {
+    const store = new VisibilityFacetStore();
+    const main = view(14);
+    const first = primitive(7);
+    const second = primitive(8);
+    store.activateView(main);
+    store.setCandidate(main, first, { level: 0, confidence: 1 });
+    store.setCandidate(main, second, { level: 0, confidence: 1 });
+    store.pruneCandidates(main, new Set([primitiveKeyId(second)]));
+
+    const page = store.dequeueQueryCandidates(main, 2);
+    expect(page.map((entry) => entry.primitive.primitiveSlot)).toEqual([8]);
+    expect(store.dequeueQueryCandidates(main, 2)).toHaveLength(0);
+  });
+
+  it('requeues an identity after hidden confidence is invalidated', () => {
+    const store = new VisibilityFacetStore();
+    const main = view(15);
+    const p = primitive(9);
+    store.activateView(main);
+    store.setCandidate(main, p, { level: 0, confidence: 1 });
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(1);
+    store.applyConfidence(main, p, { type: 'result', samples: 0, submissionGeneration: 1 });
+    store.applyConfidence(main, p, { type: 'result', samples: 0, submissionGeneration: 2 });
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(0);
+
+    store.applyConfidence(main, p, { type: 'invalidate', reason: 'teleport' });
+    expect(store.dequeueQueryCandidates(main, 1)).toHaveLength(1);
+  });
+});

package/src/__tests__/lod-visibility-lifecycle.integration.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import { primitiveKey, VisibilityFacetStore, viewKey } from '../scene/visibility/facet';
+
+describe('LOD visibility facet lifecycle', () => {
+  it('retires all facet rows for a detached attachment', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 4,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 3,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    store.setCandidate(view, primitive, { level: 0, confidence: 1 });
+
+    store.detachAttachment('world-a');
+
+    expect(store.getCandidate(view, primitive)).toBeUndefined();
+    expect(store.inspect()).toMatchObject({ activeViews: 0, facetRows: 0 });
+  });
+
+  it('preserves active rows when unrelated worlds reorder', () => {
+    const store = new VisibilityFacetStore();
+    const first = viewKey({
+      attachmentId: 'world-first',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 2,
+    });
+    const second = viewKey({
+      attachmentId: 'world-second',
+      cameraEntity: 2,
+      viewRole: 'probe',
+      viewGeneration: 5,
+    });
+    const firstPrimitive = primitiveKey({
+      attachmentId: 'world-first',
+      worldGeneration: 3,
+      primitiveSlot: 0,
+      slotGeneration: 1,
+    });
+    const secondPrimitive = primitiveKey({
+      attachmentId: 'world-second',
+      worldGeneration: 7,
+      primitiveSlot: 1,
+      slotGeneration: 4,
+    });
+    store.activateView(first);
+    store.activateView(second);
+    store.setCandidate(first, firstPrimitive, { level: 1, confidence: 0.8 });
+    store.setCandidate(second, secondPrimitive, { level: 2, confidence: 0.4 });
+
+    store.reorderAttachments(['world-second', 'world-first']);
+
+    expect(store.getCandidate(first, firstPrimitive)).toEqual({ level: 1, confidence: 0.8 });
+    expect(store.getCandidate(second, secondPrimitive)).toEqual({ level: 2, confidence: 0.4 });
+  });
+
+  it('rejects stale completion after a view epoch advances', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 8,
+      viewRole: 'reflection',
+      viewGeneration: 3,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 8,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    const epoch = store.beginViewEpoch(view);
+    store.beginViewEpoch(view);
+
+    expect(store.applyCompletion(view, primitive, epoch, { level: 2, confidence: 0.3 })).toBe(
+      false,
+    );
+    expect(store.getCandidate(view, primitive)).toBeUndefined();
+  });
+
+  it('does not invalidate draw admission for an identical completion', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 9,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 9,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    const epoch = store.beginViewEpoch(view);
+    store.setCandidate(view, primitive, { level: 0, confidence: 1 });
+    const before = {
+      visibility: store.revision,
+      draw: store.drawRevisionValue,
+    };
+
+    expect(store.applyCompletion(view, primitive, epoch, { level: 0, confidence: 1 })).toBe(true);
+    expect(store.revision).toBe(before.visibility);
+    expect(store.drawRevisionValue).toBe(before.draw);
+
+    expect(store.applyCompletion(view, primitive, epoch, { level: 1, confidence: 0.5 })).toBe(true);
+    expect(store.revision).toBe(before.visibility + 1);
+    expect(store.drawRevisionValue).toBe(before.draw + 1);
+  });
+
+  it('exposes one facet owner without lane-specific visibility maps', () => {
+    const store = new VisibilityFacetStore();
+    const inspection = store.inspect();
+
+    expect(inspection).toMatchObject({
+      owner: 'persistent-render-scene',
+      activeViews: 0,
+      facetRows: 0,
+    });
+    expect(Object.keys(inspection)).not.toContain('cameraUnion');
+    expect(Object.keys(inspection)).not.toContain('laneVisibility');
+  });
+});

package/src/__tests__/ltc-resources.unit.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import { deriveLtcResourcePlan } from '../prepare/extended-lighting/ltc-resources';
+
+describe('LTC extended-lighting resource admission', () => {
+  it('omits Rect when LTC or required device facts are unavailable', () => {
+    const scope = DeviceScope.create(7, 'renderer');
+
+    expect(deriveLtcResourcePlan({ scope, ltcAvailable: false })).toEqual({
+      topology: 'extendedLighting',
+      generation: 7,
+      rectAdmission: 'omitted',
+      tableCount: 0,
+      uploadCount: 0,
+    });
+  });
+
+  it('plans exactly one pair of resident tables per DeviceScope', () => {
+    const scope = DeviceScope.create(8, 'renderer');
+
+    expect(deriveLtcResourcePlan({ scope, ltcAvailable: true })).toMatchObject({
+      topology: 'extendedLighting',
+      generation: 8,
+      rectAdmission: 'admitted',
+      tableCount: 2,
+      uploadCount: 2,
+    });
+    expect(
+      deriveLtcResourcePlan({ scope, ltcAvailable: true, residentGeneration: scope.generation }),
+    ).toMatchObject({ tableCount: 2, uploadCount: 0 });
+  });
+});