minecraft-renderer 0.1.106 → 0.1.108

package/src/lighting/versioning/clientLightVersions.test.ts

@@ -0,0 +1,241 @@
+//@ts-nocheck
+import { describe, expect, test } from 'vitest'
+import {
+  INITIAL_TOPOLOGY_REVISION,
+  nextTopologyRevision,
+  shouldAcceptVersionedMesh,
+  shouldDispatchCoveringRemesh,
+  snapshotMeshVersions,
+  validateMeshResultVersions,
+  validateOwnerPackedSection,
+  validateOwnerPublicationMessage
+} from './clientLightVersions'
+
+describe('shouldAcceptVersionedMesh', () => {
+  const required = { requiredVersion: 3, worldGeneration: 1, topologyRevision: 5 }
+
+  test('legacy bootstrap still accepts unversioned geometry', () => {
+    expect(shouldAcceptVersionedMesh({}, required, { ownerManaged: false })).toBe(true)
+  })
+
+  test('owner-managed path rejects unversioned geometry as current', () => {
+    expect(shouldAcceptVersionedMesh({}, required, { ownerManaged: true })).toBe(false)
+    expect(shouldAcceptVersionedMesh({ meshMode: 'legacyBootstrap' }, required, { ownerManaged: true })).toBe(false)
+  })
+
+  test('fast A→B→C drops B when C is required', () => {
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 2, topologyRevision: 4, sessionEpoch: 1 }, required, {
+        ownerManaged: true,
+        sessionEpoch: 1
+      })
+    ).toBe(false)
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 3, topologyRevision: 5, sessionEpoch: 1 }, required, {
+        ownerManaged: true,
+        sessionEpoch: 1
+      })
+    ).toBe(true)
+  })
+
+  test('late reply from a previous incarnation is dropped', () => {
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 3, topologyRevision: 5, sessionEpoch: 1, columnIncarnation: 1 }, required, {
+        ownerManaged: true,
+        sessionEpoch: 1,
+        columnIncarnation: 2
+      })
+    ).toBe(false)
+  })
+
+  test('hadErrors is never a successful empty commit', () => {
+    expect(
+      shouldAcceptVersionedMesh({ hadErrors: true, worldGeneration: 1, lightPublicationVersion: 3, topologyRevision: 5 }, required, { ownerManaged: true })
+    ).toBe(false)
+    expect(
+      shouldAcceptVersionedMesh({ hadErrors: false, worldGeneration: 1, lightPublicationVersion: 3, topologyRevision: 5 }, required, {
+        ownerManaged: true
+      })
+    ).toBe(true)
+  })
+
+  test('stale topology with fresh light is rejected', () => {
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 3, topologyRevision: 4, sessionEpoch: 1 }, required, {
+        ownerManaged: true,
+        sessionEpoch: 1
+      })
+    ).toBe(false)
+  })
+
+  test('fresh topology with stale light is accepted so the block can install this frame', () => {
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 2, topologyRevision: 5, sessionEpoch: 1 }, required, {
+        ownerManaged: true,
+        sessionEpoch: 1
+      })
+    ).toBe(true)
+  })
+
+  test('required == null accepts versioned geometry', () => {
+    expect(
+      shouldAcceptVersionedMesh({ worldGeneration: 1, lightPublicationVersion: 1, topologyRevision: 1, sessionEpoch: 1 }, null, {
+        ownerManaged: true,
+        sessionEpoch: 1
+      })
+    ).toBe(true)
+  })
+
+  test('legacyBootstrap with a required revision is still rejected', () => {
+    expect(shouldAcceptVersionedMesh({ meshMode: 'legacyBootstrap', topologyRevision: 5 }, required, { ownerManaged: true })).toBe(false)
+  })
+
+  test('legacyBootstrap without required is accepted', () => {
+    expect(shouldAcceptVersionedMesh({ meshMode: 'legacyBootstrap' }, null, { ownerManaged: true })).toBe(true)
+  })
+
+  test('legacyBootstrap still has to match the column life', () => {
+    expect(
+      shouldAcceptVersionedMesh({ meshMode: 'legacyBootstrap', sessionEpoch: 1, columnIncarnation: 1 }, null, {
+        ownerManaged: true,
+        sessionEpoch: 2,
+        columnIncarnation: 2
+      })
+    ).toBe(false)
+  })
+
+  test('legacyBootstrap with a proven neighbor light version covers the requirement', () => {
+    expect(
+      shouldAcceptVersionedMesh(
+        { meshMode: 'legacyBootstrap', worldGeneration: 1, lightPublicationVersion: 10, sessionEpoch: 1, columnIncarnation: 1 },
+        { requiredVersion: 10, worldGeneration: 1 },
+        { ownerManaged: true, sessionEpoch: 1, columnIncarnation: 1 }
+      )
+    ).toBe(true)
+    expect(
+      shouldAcceptVersionedMesh(
+        { meshMode: 'legacyBootstrap', worldGeneration: 1, sessionEpoch: 1, columnIncarnation: 1 },
+        { requiredVersion: 10, worldGeneration: 1 },
+        { ownerManaged: true, sessionEpoch: 1, columnIncarnation: 1 }
+      )
+    ).toBe(false)
+  })
+
+  test('owner mesh with an older own-column light version stays rejected', () => {
+    expect(
+      shouldAcceptVersionedMesh(
+        { meshMode: 'owner', worldGeneration: 1, lightPublicationVersion: 9, sessionEpoch: 1, columnIncarnation: 1 },
+        { requiredVersion: 10, worldGeneration: 1 },
+        { ownerManaged: true, sessionEpoch: 1, columnIncarnation: 1 }
+      )
+    ).toBe(false)
+  })
+
+  test('without topology on the requirement, stale light still rejects (old gate)', () => {
+    expect(
+      shouldAcceptVersionedMesh(
+        { worldGeneration: 1, lightPublicationVersion: 2, topologyRevision: 5, sessionEpoch: 1 },
+        { requiredVersion: 3, worldGeneration: 1 },
+        { ownerManaged: true, sessionEpoch: 1 }
+      )
+    ).toBe(false)
+  })
+})
+
+describe('shouldDispatchCoveringRemesh', () => {
+  const required = { requiredVersion: 4, worldGeneration: 1 }
+
+  test('dispatches when nothing is outstanding', () => {
+    expect(shouldDispatchCoveringRemesh({ required, outstandingCount: 0 })).toBe(true)
+  })
+
+  test('does not add another remesh when pending already covers the requirement', () => {
+    expect(
+      shouldDispatchCoveringRemesh({
+        required,
+        outstandingCount: 1,
+        pendingCoveringVersion: 4,
+        pendingCoveringGeneration: 1
+      })
+    ).toBe(false)
+  })
+
+  test('dispatches when the outstanding remesh is behind the new requirement', () => {
+    expect(
+      shouldDispatchCoveringRemesh({
+        required,
+        outstandingCount: 2,
+        pendingCoveringVersion: 3,
+        pendingCoveringGeneration: 1
+      })
+    ).toBe(true)
+  })
+})
+
+describe('snapshotMeshVersions', () => {
+  test('freezes neighbor revisions with the task snapshot, not a later live map', () => {
+    const neighbors = [{ key: '16,64,0', topologyRevision: 2 }]
+    const snap = snapshotMeshVersions({
+      sessionEpoch: 1,
+      columnIncarnation: 3,
+      requestId: 9,
+      topologyRevision: 4,
+      lightPublicationVersion: 7,
+      worldGeneration: 1,
+      neighborTopologyRevisions: neighbors
+    })
+    neighbors[0]!.topologyRevision = 99
+    expect(snap.neighborTopologyRevisions[0]!.topologyRevision).toBe(2)
+    expect(snap.meshMode).toBe('owner')
+  })
+})
+
+describe('nextTopologyRevision', () => {
+  test('increments from zero', () => {
+    expect(nextTopologyRevision(undefined)).toBe(1)
+    expect(nextTopologyRevision(1)).toBe(2)
+  })
+
+  test('the initial revision is not the first edit', () => {
+    expect(INITIAL_TOPOLOGY_REVISION).toBe(0)
+    expect(nextTopologyRevision(undefined)).not.toBe(INITIAL_TOPOLOGY_REVISION)
+    expect(nextTopologyRevision(INITIAL_TOPOLOGY_REVISION)).toBe(1)
+  })
+})
+
+describe('payload validation', () => {
+  test('rejects NaN and non-integer revision ids', () => {
+    expect(validateMeshResultVersions({ sessionEpoch: 1.5 })).toEqual({ ok: false, reason: 'sessionEpoch' })
+    expect(validateMeshResultVersions({ requestId: -1 })).toEqual({ ok: false, reason: 'requestId' })
+    expect(validateMeshResultVersions({ key: '0,64,0', requestId: 3 })).toEqual({ ok: true })
+  })
+
+  test('rejects packed light that is not 2048 bytes per channel', () => {
+    expect(
+      validateOwnerPackedSection({
+        sx: 0,
+        sy: 64,
+        sz: 0,
+        blockLight: new Uint8Array(16)
+      })
+    ).toEqual({ ok: false, reason: 'blockLight' })
+    expect(
+      validateOwnerPackedSection({
+        sx: -16,
+        sy: 64,
+        sz: 32,
+        blockLight: new Uint8Array(2048)
+      })
+    ).toEqual({ ok: true })
+  })
+
+  test('rejects a foreign publication with bad section payload', () => {
+    expect(
+      validateOwnerPublicationMessage({
+        worldGeneration: 1,
+        publicationVersion: 2,
+        sections: [{ sx: 0, sy: 64, sz: 0, blockLight: new Uint8Array(8) }]
+      })
+    ).toEqual({ ok: false, reason: 'blockLight' })
+  })
+})

package/src/lighting/versioning/clientLightVersions.ts

@@ -0,0 +1,203 @@
+//@ts-nocheck
+/**
+ * P-02: explicit mesh versions, covering coalesce, and payload validation.
+ * Metadata only — never copies raw meshes or light arrays into logs.
+ */
+
+export const OWNER_STATES_PER_SECTION = 4096
+export const OWNER_PACKED_LIGHT_BYTES = 2048
+
+export type MeshGeometryMode = 'owner' | 'legacyBootstrap'
+
+export type MeshResultVersions = {
+  sessionEpoch: number
+  columnIncarnation: number
+  requestId: number
+  topologyRevision: number
+  lightPublicationVersion: number
+  worldGeneration: number
+  neighborTopologyRevisions: Array<{ key: string; topologyRevision: number }>
+  meshMode: MeshGeometryMode
+}
+
+export type MeshSectionLightRequirement = {
+  requiredVersion: number
+  worldGeneration: number
+  topologyRevision?: number
+}
+
+export function isUnversionedMesh(mesh: {
+  worldGeneration?: number
+  lightPublicationVersion?: number
+  topologyRevision?: number
+  sessionEpoch?: number
+}): boolean {
+  return mesh.worldGeneration == null && mesh.lightPublicationVersion == null && mesh.topologyRevision == null && mesh.sessionEpoch == null
+}
+
+export function shouldAcceptVersionedMesh(
+  mesh: {
+    worldGeneration?: number
+    lightPublicationVersion?: number
+    topologyRevision?: number
+    sessionEpoch?: number
+    columnIncarnation?: number
+    hadErrors?: boolean
+    meshMode?: MeshGeometryMode
+  },
+  required: MeshSectionLightRequirement | null | undefined,
+  opts: { ownerManaged: boolean; sessionEpoch?: number; columnIncarnation?: number }
+): boolean {
+  if (mesh.hadErrors) return false
+  if (opts.ownerManaged) {
+    if (opts.sessionEpoch != null && mesh.sessionEpoch != null && mesh.sessionEpoch !== opts.sessionEpoch) return false
+    if (opts.columnIncarnation != null && mesh.columnIncarnation != null && mesh.columnIncarnation !== opts.columnIncarnation) {
+      return false
+    }
+    if (mesh.meshMode === 'legacyBootstrap') {
+      if (required == null) return true
+      if (mesh.lightPublicationVersion == null) return false
+    } else if (isUnversionedMesh(mesh)) {
+      return false
+    }
+  } else if (isUnversionedMesh(mesh)) {
+    return true
+  }
+  if (required == null) return true
+  if (mesh.worldGeneration != null && mesh.worldGeneration !== required.worldGeneration) return false
+  if (required.topologyRevision != null && mesh.topologyRevision != null && mesh.topologyRevision < required.topologyRevision) {
+    return false
+  }
+  const topologyFresh = required.topologyRevision != null && mesh.topologyRevision != null && mesh.topologyRevision >= required.topologyRevision
+  if (!topologyFresh && mesh.lightPublicationVersion != null && mesh.lightPublicationVersion < required.requiredVersion) {
+    return false
+  }
+  return true
+}
+
+export function isOwnerGeometryLightStale(mesh: { lightPublicationVersion?: number }, required: MeshSectionLightRequirement | null | undefined): boolean {
+  return required != null && mesh.lightPublicationVersion != null && mesh.lightPublicationVersion < required.requiredVersion
+}
+
+export function shouldDispatchCoveringRemesh(opts: {
+  required: MeshSectionLightRequirement
+  outstandingCount: number
+  pendingCoveringVersion?: number
+  pendingCoveringGeneration?: number
+}): boolean {
+  if (opts.outstandingCount <= 0) return true
+  if (opts.pendingCoveringGeneration !== opts.required.worldGeneration) return true
+  if ((opts.pendingCoveringVersion ?? -1) < opts.required.requiredVersion) return true
+  return false
+}
+
+/** Stamped on a section that has not been edited. The first edit is always greater. */
+export const INITIAL_TOPOLOGY_REVISION = 0
+
+export function nextTopologyRevision(current: number | undefined): number {
+  return (current ?? INITIAL_TOPOLOGY_REVISION) + 1
+}
+
+export function snapshotMeshVersions(input: {
+  sessionEpoch: number
+  columnIncarnation: number
+  requestId: number
+  topologyRevision: number
+  lightPublicationVersion: number
+  worldGeneration: number
+  neighborTopologyRevisions: Array<{ key: string; topologyRevision: number }>
+  meshMode?: MeshGeometryMode
+}): MeshResultVersions {
+  return {
+    sessionEpoch: input.sessionEpoch,
+    columnIncarnation: input.columnIncarnation,
+    requestId: input.requestId,
+    topologyRevision: input.topologyRevision,
+    lightPublicationVersion: input.lightPublicationVersion,
+    worldGeneration: input.worldGeneration,
+    neighborTopologyRevisions: input.neighborTopologyRevisions.map(entry => ({
+      key: entry.key,
+      topologyRevision: entry.topologyRevision
+    })),
+    meshMode: input.meshMode ?? 'owner'
+  }
+}
+
+export function isSafeIntegerId(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && Number.isSafeInteger(value) && value >= 0
+}
+
+export function isSafeCoord(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && Number.isSafeInteger(value)
+}
+
+export function validateSectionKey(key: unknown): boolean {
+  if (typeof key !== 'string') return false
+  const parts = key.split(',')
+  if (parts.length !== 3) return false
+  return parts.every(part => {
+    const n = Number(part)
+    return Number.isInteger(n) && Number.isFinite(n)
+  })
+}
+
+export function validateOwnerPackedSection(section: {
+  sx?: unknown
+  sy?: unknown
+  sz?: unknown
+  blockLight?: unknown
+  skyLight?: unknown
+  states?: unknown
+}): { ok: true } | { ok: false; reason: string } {
+  if (!isSafeCoord(section.sx)) return { ok: false, reason: 'sx' }
+  if (!isSafeCoord(section.sy)) return { ok: false, reason: 'sy' }
+  if (!isSafeCoord(section.sz)) return { ok: false, reason: 'sz' }
+  if (section.blockLight != null) {
+    if (!(section.blockLight instanceof Uint8Array) || section.blockLight.length !== OWNER_PACKED_LIGHT_BYTES) {
+      return { ok: false, reason: 'blockLight' }
+    }
+  }
+  if (section.skyLight != null) {
+    if (!(section.skyLight instanceof Uint8Array) || section.skyLight.length !== OWNER_PACKED_LIGHT_BYTES) {
+      return { ok: false, reason: 'skyLight' }
+    }
+  }
+  if (section.states != null) {
+    if (!(section.states instanceof Uint16Array) || section.states.length !== OWNER_STATES_PER_SECTION) {
+      return { ok: false, reason: 'states' }
+    }
+  }
+  return { ok: true }
+}
+
+export function validateMeshResultVersions(data: {
+  sessionEpoch?: unknown
+  columnIncarnation?: unknown
+  requestId?: unknown
+  topologyRevision?: unknown
+  lightPublicationVersion?: unknown
+  worldGeneration?: unknown
+  key?: unknown
+}): { ok: true } | { ok: false; reason: string } {
+  if (data.key != null && !validateSectionKey(data.key)) return { ok: false, reason: 'key' }
+  for (const field of ['sessionEpoch', 'columnIncarnation', 'requestId', 'topologyRevision', 'lightPublicationVersion', 'worldGeneration'] as const) {
+    if (data[field] == null) continue
+    if (!isSafeIntegerId(data[field])) return { ok: false, reason: field }
+  }
+  return { ok: true }
+}
+
+export function validateOwnerPublicationMessage(data: {
+  worldGeneration?: unknown
+  publicationVersion?: unknown
+  sections?: unknown
+}): { ok: true } | { ok: false; reason: string } {
+  if (!isSafeIntegerId(data.worldGeneration)) return { ok: false, reason: 'worldGeneration' }
+  if (!isSafeIntegerId(data.publicationVersion)) return { ok: false, reason: 'publicationVersion' }
+  if (!Array.isArray(data.sections)) return { ok: false, reason: 'sections' }
+  for (const section of data.sections) {
+    const checked = validateOwnerPackedSection(section ?? {})
+    if (!checked.ok) return checked
+  }
+  return { ok: true }
+}

package/src/lighting/versioning/pendingSectionFlush.test.ts

@@ -0,0 +1,214 @@
+//@ts-nocheck
+import { describe, expect, it } from 'vitest'
+import { faceNeighborKeys, pendingSectionGroups, selectReadySectionFlushes, selectReadySectionUpdates } from './pendingSectionFlush'
+
+const SECTION_HEIGHT = 16
+const MAX_BUFFER_MS = 500
+
+type Scene = {
+  pending: Map<string, number>
+  outstanding: Set<string>
+  visible: Set<string>
+}
+
+function select(scene: Scene, now: number) {
+  return selectReadySectionUpdates({
+    pendingKeys: scene.pending.keys(),
+    startedAt: key => scene.pending.get(key),
+    now,
+    maxBufferMs: MAX_BUFFER_MS,
+    sectionHeight: SECTION_HEIGHT,
+    isOutstanding: key => scene.outstanding.has(key),
+    hasSectionObject: key => scene.visible.has(key)
+  })
+}
+
+/**
+ * The per-key policy this module replaced (worldRendererThree before the group
+ * flush): each key waited out its OWN deadline and was released on its own.
+ * Kept here so the regression it caused stays pinned by a test.
+ */
+function selectPerKeyLegacy(scene: Scene, now: number) {
+  const ready: string[] = []
+  for (const key of scene.pending.keys()) {
+    const startedAt = scene.pending.get(key) ?? now
+    if (now - startedAt < MAX_BUFFER_MS) {
+      const busy = faceNeighborKeys(key, SECTION_HEIGHT).some(
+        neighbor => scene.outstanding.has(neighbor) && !scene.pending.has(neighbor) && scene.visible.has(neighbor)
+      )
+      if (busy) continue
+    }
+    ready.push(key)
+  }
+  return ready
+}
+
+describe('pendingSectionGroups', () => {
+  it('splits buffered sections into face-connected components', () => {
+    const groups = pendingSectionGroups(['0,64,0', '0,80,0', '160,64,160'], SECTION_HEIGHT)
+    expect(groups).toHaveLength(2)
+    expect(groups.find(g => g.length === 2)?.sort()).toEqual(['0,64,0', '0,80,0'])
+    expect(groups.find(g => g.length === 1)).toEqual(['160,64,160'])
+  })
+})
+
+describe('selectReadySectionUpdates', () => {
+  it('holds a section while a visible face neighbour is still being re-meshed', () => {
+    const scene: Scene = {
+      pending: new Map([['0,64,0', 1000]]),
+      outstanding: new Set(['16,64,0']),
+      visible: new Set(['16,64,0'])
+    }
+    expect(select(scene, 1050)).toEqual([])
+  })
+
+  it('flushes as soon as every neighbour of the group has arrived, without waiting the deadline', () => {
+    const scene: Scene = {
+      pending: new Map([
+        ['0,64,0', 1000],
+        ['16,64,0', 1040]
+      ]),
+      outstanding: new Set(),
+      visible: new Set(['0,64,0', '16,64,0'])
+    }
+    expect(select(scene, 1050).sort()).toEqual(['0,64,0', '16,64,0'])
+  })
+
+  it('does not wait on an air neighbour that has no geometry on screen', () => {
+    const scene: Scene = {
+      pending: new Map([['0,64,0', 1000]]),
+      outstanding: new Set(['0,80,0']),
+      visible: new Set(['0,64,0'])
+    }
+    expect(select(scene, 1010)).toEqual(['0,64,0'])
+  })
+
+  // The sky-flash regression: the dug section and its face neighbours are
+  // buffered at staggered times (they come back on different worker ticks).
+  // Releasing the earliest one alone shows the neighbour's still-culled faces
+  // as a hole, so the whole group must go out in the same frame.
+  it('releases a staggered group in one batch when the deadline expires', () => {
+    const scene: Scene = {
+      pending: new Map([
+        ['0,64,0', 1000],
+        ['16,64,0', 1120],
+        ['0,80,0', 1180]
+      ]),
+      outstanding: new Set(['32,64,0']),
+      visible: new Set(['0,64,0', '16,64,0', '0,80,0', '32,64,0'])
+    }
+    expect(select(scene, 1500).sort()).toEqual(['0,64,0', '0,80,0', '16,64,0'])
+    // The legacy policy installs 0,64,0 while 16,64,0 keeps the geometry it was
+    // meshed with before the edit — the faces between them stay culled on both
+    // sides for a frame, which is the hole seen as a sky flash.
+    expect(selectPerKeyLegacy(scene, 1500)).not.toContain('16,64,0')
+    expect(selectPerKeyLegacy(scene, 1500)).toContain('0,64,0')
+  })
+
+  it('measures the deadline from the oldest member so a group cannot be starved', () => {
+    const scene: Scene = {
+      pending: new Map([
+        ['0,64,0', 1000],
+        ['16,64,0', 1400]
+      ]),
+      outstanding: new Set(['32,64,0']),
+      visible: new Set(['0,64,0', '16,64,0', '32,64,0'])
+    }
+    expect(select(scene, 1499)).toEqual([])
+    expect(select(scene, 1500).sort()).toEqual(['0,64,0', '16,64,0'])
+  })
+
+  it('keeps unrelated groups independent', () => {
+    const scene: Scene = {
+      pending: new Map([
+        ['0,64,0', 1000],
+        ['160,64,160', 1000]
+      ]),
+      outstanding: new Set(['16,64,0']),
+      visible: new Set(['0,64,0', '16,64,0', '160,64,160'])
+    }
+    expect(select(scene, 1010)).toEqual(['160,64,160'])
+  })
+
+  it('labels complete groups vs deadline flushes', () => {
+    const complete: Scene = {
+      pending: new Map([['160,64,160', 1000]]),
+      outstanding: new Set(),
+      visible: new Set(['160,64,160'])
+    }
+    expect(
+      selectReadySectionFlushes({
+        pendingKeys: complete.pending.keys(),
+        startedAt: key => complete.pending.get(key),
+        now: 1010,
+        maxBufferMs: MAX_BUFFER_MS,
+        sectionHeight: SECTION_HEIGHT,
+        isOutstanding: key => complete.outstanding.has(key),
+        hasSectionObject: key => complete.visible.has(key)
+      })
+    ).toEqual([{ key: '160,64,160', reason: 'group-complete' }])
+
+    const expired: Scene = {
+      pending: new Map([
+        ['0,64,0', 1000],
+        ['16,64,0', 1120]
+      ]),
+      outstanding: new Set(['32,64,0']),
+      visible: new Set(['0,64,0', '16,64,0', '32,64,0'])
+    }
+    expect(
+      selectReadySectionFlushes({
+        pendingKeys: expired.pending.keys(),
+        startedAt: key => expired.pending.get(key),
+        now: 1500,
+        maxBufferMs: MAX_BUFFER_MS,
+        sectionHeight: SECTION_HEIGHT,
+        isOutstanding: key => expired.outstanding.has(key),
+        hasSectionObject: key => expired.visible.has(key)
+      }).map(item => item.reason)
+    ).toEqual(['deadline', 'deadline'])
+  })
+})
+
+describe('selectReadySectionFlushes topology vs covering', () => {
+  const flushQuery = (scene: Scene, now: number, topologyOutstanding?: Set<string>) =>
+    selectReadySectionFlushes({
+      pendingKeys: scene.pending.keys(),
+      startedAt: key => scene.pending.get(key),
+      now,
+      maxBufferMs: MAX_BUFFER_MS,
+      sectionHeight: SECTION_HEIGHT,
+      isOutstanding: key => scene.outstanding.has(key),
+      isTopologyOutstanding: topologyOutstanding ? key => topologyOutstanding.has(key) : undefined,
+      hasSectionObject: key => scene.visible.has(key)
+    })
+
+  it('holds a group while a visible neighbour is topology-outstanding', () => {
+    const scene: Scene = {
+      pending: new Map([['0,64,0', 1000]]),
+      outstanding: new Set(),
+      visible: new Set(['0,64,0', '16,64,0'])
+    }
+    expect(flushQuery(scene, 1050, new Set(['16,64,0'])).map(item => item.key)).toEqual([])
+  })
+
+  it('does not hold a group for covering-only outstanding neighbours', () => {
+    const scene: Scene = {
+      pending: new Map([['0,64,0', 1000]]),
+      outstanding: new Set(['16,64,0']),
+      visible: new Set(['0,64,0', '16,64,0'])
+    }
+    expect(flushQuery(scene, 1050, new Set()).map(item => item.key)).toEqual(['0,64,0'])
+    expect(flushQuery(scene, 1050, new Set())[0]?.reason).toBe('group-complete')
+  })
+
+  it('holds a singleton with a topology-outstanding neighbour until the deadline', () => {
+    const scene: Scene = {
+      pending: new Map([['0,64,0', 1000]]),
+      outstanding: new Set(['16,64,0']),
+      visible: new Set(['0,64,0', '16,64,0'])
+    }
+    expect(flushQuery(scene, 1499, new Set(['16,64,0']))).toEqual([])
+    expect(flushQuery(scene, 1500, new Set(['16,64,0']))).toEqual([{ key: '0,64,0', reason: 'deadline' }])
+  })
+})