@forgeax/engine-render 0.1.21 → 0.1.23

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

package/src/__tests__/material-contract-inventory.unit.test.ts

@@ -53,6 +53,23 @@ describe('vertex color does not change the material contract', () => {
     expect(material.passes?.[0]?.renderState).toMatchObject({ depthWriteEnabled: false });
   });
 
+  it.each([
+    [
+      'unlit',
+      Materials.unlit([1, 1, 1, 1], { renderState: { cullMode: 'none', frontFace: 'cw' } }),
+    ],
+    [
+      'standard',
+      Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        renderState: { cullMode: 'none', frontFace: 'cw' },
+      }),
+    ],
+  ] as const)('projects the %s material raster orientation into its ShadowCaster pass', (_name, material) => {
+    const shadowCaster = material.passes?.find((entry) => entry.name === 'shadow-caster');
+    expect(shadowCaster?.renderState).toMatchObject({ cullMode: 'none', frontFace: 'cw' });
+  });
+
   it.each([
     ['transmission', { transmission: -0.1 }],
     ['ior', { ior: 0 }],

package/src/__tests__/occlusion-confidence.unit.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import {
+  applyConfidenceEvent,
+  createConfidenceState,
+  OcclusionConfidenceScheduler,
+  shouldIssueRetest,
+} from '../scene/visibility/occlusion-confidence';
+
+describe('occlusion confidence FSM', () => {
+  it('shows positive results immediately and suppresses only after two zeros', () => {
+    const initial = createConfidenceState();
+    const positive = applyConfidenceEvent(initial, {
+      type: 'result',
+      samples: 4,
+      submissionGeneration: 1,
+    });
+    expect(positive.status).toBe('visible');
+    const firstZero = applyConfidenceEvent(positive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    expect(firstZero.status).toBe('visible');
+    const secondZero = applyConfidenceEvent(firstZero, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 3,
+    });
+    expect(secondZero.status).toBe('hidden');
+  });
+
+  it('retests within six successful submits and expires to visible by eight', () => {
+    const budget = createVisibilityBudget();
+    let state = applyConfidenceEvent(createConfidenceState(), {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    state = applyConfidenceEvent(state, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    expect(state.status).toBe('hidden');
+    for (let generation = 3; generation <= 2 + budget.retestSubmits; generation += 1) {
+      state = applyConfidenceEvent(
+        state,
+        { type: 'submit', submissionGeneration: generation },
+        budget,
+      );
+    }
+    expect(shouldIssueRetest(state, budget)).toBe(true);
+    expect(state.status).toBe('hidden');
+    for (
+      let generation = 3 + budget.retestSubmits;
+      generation <= 2 + budget.expirySubmits;
+      generation += 1
+    ) {
+      state = applyConfidenceEvent(
+        state,
+        { type: 'submit', submissionGeneration: generation },
+        budget,
+      );
+    }
+    expect(state.status).toBe('visible');
+    expect(shouldIssueRetest(state, budget)).toBe(false);
+  });
+
+  it('keeps failures and invalidations visible and clears only the facet state', () => {
+    const hidden = applyConfidenceEvent(
+      applyConfidenceEvent(createConfidenceState(), {
+        type: 'result',
+        samples: 0,
+        submissionGeneration: 1,
+      }),
+      { type: 'result', samples: 0, submissionGeneration: 2 },
+    );
+    const failed = applyConfidenceEvent(hidden, {
+      type: 'failure',
+      submissionGeneration: 3,
+    });
+    expect(failed).toMatchObject({ status: 'visible', queryable: true });
+    const invalidated = applyConfidenceEvent(hidden, { type: 'invalidate', reason: 'teleport' });
+    expect(invalidated).toMatchObject({ status: 'visible', zeroStreak: 0, queryable: true });
+  });
+
+  it('does not query transparent or detached facets', () => {
+    expect(
+      applyConfidenceEvent(createConfidenceState(), { type: 'invalidate', reason: 'transparent' }),
+    ).toMatchObject({ queryable: false, status: 'visible' });
+    expect(
+      applyConfidenceEvent(createConfidenceState(), { type: 'invalidate', reason: 'detach' }),
+    ).toMatchObject({ queryable: false, status: 'visible' });
+  });
+
+  it('consumes overdue wake/expiry buckets without scanning unrelated generations', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    scheduler.apply('other', { type: 'result', samples: 0, submissionGeneration: 99 });
+    scheduler.apply('other', { type: 'result', samples: 0, submissionGeneration: 100 });
+
+    scheduler.advanceSuccessfulSubmits(100);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+    expect(scheduler.get('other')).toMatchObject({ status: 'hidden', successfulSubmits: 0 });
+  });
+
+  it('reschedules an excluded due wake without retaining its old expiry bucket', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits, new Set(['hidden']));
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits + 2);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'hidden', successfulSubmits: 0 });
+
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits + budget.expirySubmits);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+  });
+
+  it('keeps a same-generation excluded reschedule reachable after an empty bucket', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    for (let generation = 3; generation <= 2 + budget.retestSubmits; generation += 1) {
+      scheduler.apply('hidden', { type: 'submit', submissionGeneration: generation });
+    }
+
+    const retestGeneration = 2 + budget.retestSubmits;
+    scheduler.advanceSuccessfulSubmits(retestGeneration, new Set(['hidden']));
+    // Repeating the same generation used to leave the newly-created bucket
+    // only in the map: unschedule removed its key but the heap membership bit
+    // prevented addDue from pushing a reachable heap entry.
+    scheduler.advanceSuccessfulSubmits(retestGeneration, new Set(['hidden']));
+    // The requeued wake at generation 8 must remain reachable. Consuming it
+    // here recreates the expiry at generation 10; without the heap repair the
+    // old expiry was removed and this later recovery never happens.
+    scheduler.advanceSuccessfulSubmits(retestGeneration);
+    scheduler.advanceSuccessfulSubmits(
+      retestGeneration + budget.expirySubmits - budget.retestSubmits,
+    );
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+  });
+
+  it('advances a due hidden row queried in the same generation exactly once', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    const dueGeneration = 2 + budget.retestSubmits;
+
+    scheduler.advanceSuccessfulSubmits(dueGeneration);
+    expect(scheduler.get('hidden')).toMatchObject({
+      status: 'hidden',
+      successfulSubmits: budget.retestSubmits,
+    });
+    scheduler.apply('hidden', { type: 'submit', submissionGeneration: dueGeneration });
+    scheduler.advanceSuccessfulSubmits(dueGeneration);
+    expect(scheduler.get('hidden')).toMatchObject({
+      status: 'hidden',
+      successfulSubmits: budget.retestSubmits + 1,
+    });
+  });
+});