Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
30.9 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import { getEventListeners } from 'node:events'
import { CONTROL_API_REQUEST_TIMEOUT_MS } from '../src/controlApiClient.js'
import {
  RequestLimitError,
  STREAM_LIMITS,
  StreamGate,
  VISUAL_PER_HOST_MAX_ADMITTED,
  VISUAL_STREAM_LIMITS,
  assertBoundedDeadline,
  visualStreamGate,
} from '../src/requestLimits.js'
import { DEFAULT_HEARTBEAT_INTERVAL_MS, MAX_HEARTBEAT_INTERVAL_MS } from '../src/sseHeartbeat.js'

// undici's default headersTimeout and bodyTimeout in the Node 24.22.1 image the
// Host runs; the Host sets neither for its proxy calls.
const HOST_UNDICI_TIMEOUT_MS = 300_000

describe('stream timing invariant', () => {
  it('T-KI-1 reaches the first keepalive before the Host HTTP client times out', () => {
    expect(STREAM_LIMITS.maxStreamDurationMs).toBe(1_800_000)
    expect(STREAM_LIMITS.maxQueueWaitMs).toBe(60_000)
    expect(CONTROL_API_REQUEST_TIMEOUT_MS).toBe(15_000)
    // Nothing is written while a request waits for a slot or for the redeem,
    // so both must end, and one heartbeat interval pass, inside the timeout.
    // Every wait a request performs (the body budget, the visual gate, the
    // stream gate) is bounded by one admission clock of maxQueueWaitMs from
    // arrival (#739 D1), so the queue time counts once. The interval is
    // configurable, so the largest one config accepts is the one pinned.
    expect(MAX_HEARTBEAT_INTERVAL_MS).toBe(60_000)
    expect(DEFAULT_HEARTBEAT_INTERVAL_MS).toBeLessThanOrEqual(MAX_HEARTBEAT_INTERVAL_MS)
    const firstKeepaliveBy =
      STREAM_LIMITS.maxQueueWaitMs + CONTROL_API_REQUEST_TIMEOUT_MS + MAX_HEARTBEAT_INTERVAL_MS
    expect(firstKeepaliveBy).toBe(135_000)
    expect(HOST_UNDICI_TIMEOUT_MS).toBe(300_000)
    expect(firstKeepaliveBy).toBeLessThan(HOST_UNDICI_TIMEOUT_MS)
  })
})

describe('assertBoundedDeadline', () => {
  it('refuses a missing or invalid proxy maximum even when the request carries a deadline', () => {
    // Liveness witness: the same request deadline passes with a valid maximum.
    expect(assertBoundedDeadline(1_000, 1_800_000)).toBe(1_000)
    for (const maxDeadlineMs of [undefined, Number.NaN, 0, -1, 1.5]) {
      let caught: unknown
      try {
        assertBoundedDeadline(1_000, maxDeadlineMs as unknown as number)
      } catch (err) {
        caught = err
      }
      expect(caught, `maxDeadlineMs=${String(maxDeadlineMs)}`).toBeInstanceOf(RequestLimitError)
      expect((caught as Error).message).toBe('deadline is invalid')
    }
  })
})

// Queues a waiter behind `gate` and records how it settled.
function track(gate: StreamGate, signal?: AbortSignal) {
  const state: { outcome?: string } = {}
  const waiter = gate.acquire(signal).then(
    next => {
      state.outcome = 'admitted'
      return next
    },
    (err: Error) => {
      state.outcome = err.message
      return undefined
    }
  )
  return { state, waiter }
}

describe('StreamGate', () => {
  it('admits a queued waiter once a running stream releases', async () => {
    const gate = new StreamGate(1, 1)
    const release = await gate.acquire()
    let admitted = false
    const queued = gate.acquire().then(next => {
      admitted = true
      return next
    })
    await new Promise(resolve => setTimeout(resolve, 30))
    expect(admitted).toBe(false)
    release()
    const releaseQueued = await queued
    expect(admitted).toBe(true)
    releaseQueued()
  })

  it('rejects immediately without taking a slot when the signal is already aborted', async () => {
    const gate = new StreamGate(1, 1)
    const abort = new AbortController()
    abort.abort()
    await expect(gate.acquire(abort.signal)).rejects.toBeInstanceOf(RequestLimitError)
    // The running slot was not consumed: a fresh caller is admitted at once.
    const release = await Promise.race([
      gate.acquire(),
      new Promise<never>((_, reject) =>
        setTimeout(() => reject(new Error('slot leaked by aborted caller')), 100)
      ),
    ])
    release()
  })

  it('rejects a queued waiter when its client aborts and frees the queue slot', async () => {
    const gate = new StreamGate(1, 1)
    const release = await gate.acquire()
    const abort = new AbortController()
    const queued = gate.acquire(abort.signal)
    abort.abort()
    await expect(
      Promise.race([
        queued,
        new Promise<never>((_, reject) =>
          setTimeout(() => reject(new Error('queued waiter ignored abort')), 200)
        ),
      ])
    ).rejects.toBeInstanceOf(RequestLimitError)
    // The queue slot is free again, so a new waiter queues instead of "queue is full".
    const next = gate.acquire()
    release()
    const releaseNext = await next
    releaseNext()
  })

  it('clears the deadline when a queued client aborts', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 55)
      const release = await gate.acquire()
      const abort = new AbortController()
      const { state, waiter } = track(gate, abort.signal)
      await vi.advanceTimersByTimeAsync(20)
      // Witness: the waiter is queued with its deadline and its abort
      // listener live, and the gate keeps no other timer.
      expect(state.outcome).toBeUndefined()
      expect(vi.getTimerCount()).toBe(1)
      expect(getEventListeners(abort.signal, 'abort')).toHaveLength(1)
      abort.abort()
      await vi.advanceTimersByTimeAsync(0)
      expect(state.outcome).toBe('stream request was aborted')
      expect(vi.getTimerCount()).toBe(0)
      await waiter
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      release()
    } finally {
      vi.useRealTimers()
    }
  })

  it('rejects a waiter queued longer than maxQueueWaitMs and frees its queue slot', async () => {
    const gate = new StreamGate(1, 1, 50)
    const release = await gate.acquire()
    const started = Date.now()
    await expect(gate.acquire()).rejects.toMatchObject({
      name: 'RequestLimitError',
      message: 'stream queue wait exceeded',
      // No caller deadline governed this wait, so a dead ticket cannot be inferred.
      kind: 'queue_wait',
    })
    // Witness: the waiter was queued for the whole wait, not refused at once.
    expect(Date.now() - started).toBeGreaterThanOrEqual(45)
    // The queue slot is free again, so a new waiter queues instead of "queue is full".
    const next = gate.acquire()
    release()
    const releaseNext = await next
    releaseNext()
  })

  it('T-AC-3 rejects a waiter at its admission deadline when that comes before maxQueueWaitMs', async () => {
    const gate = new StreamGate(1, 1, 60_000)
    const release = await gate.acquire()
    const started = Date.now()
    const queued = gate.acquire(undefined, started + 50)
    // Witness: the waiter really queued, it was not refused at once.
    expect(gate.snapshot().queued).toBe(1)
    await expect(
      Promise.race([
        queued,
        new Promise<never>((_, reject) =>
          setTimeout(() => reject(new Error('the admission deadline did not end the wait')), 1_000)
        ),
      ])
    ).rejects.toMatchObject({
      name: 'RequestLimitError',
      message: 'stream queue wait exceeded',
      // The caller's deadline ended the wait; the server reads this, not the clock.
      kind: 'deadline',
    })
    expect(Date.now() - started).toBeGreaterThanOrEqual(45)
    expect(gate.snapshot().queued).toBe(0)
    release()
  })

  // The admission deadline shortens the bound the gate's own timer enforces.
  // A timer armed with maxQueueWaitMs would leave the waiter queued past
  // 55 ms; only the deadline timer settles it there.
  it('T-AC-3b settles at deadlineAt on the deadline timer, not on the next poll', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 60_000)
      const release = await gate.acquire()
      const state: { outcome?: string } = {}
      const waiter = gate.acquire(undefined, Date.now() + 55).then(
        () => {
          state.outcome = 'admitted'
        },
        (err: Error) => {
          state.outcome = err.message
        }
      )
      await vi.advanceTimersByTimeAsync(54)
      // Witness: one millisecond before the deadline the waiter is still queued.
      expect(state.outcome).toBeUndefined()
      expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
      await vi.advanceTimersByTimeAsync(1)
      expect(state.outcome).toBe('stream queue wait exceeded')
      expect(vi.getTimerCount()).toBe(0)
      await waiter
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      release()
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses a waiter at the 60 000 ms default maxQueueWaitMs', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1)
      const release = await gate.acquire()
      const { state, waiter } = track(gate)
      await vi.advanceTimersByTimeAsync(59_999)
      expect(state.outcome).toBeUndefined()
      await vi.advanceTimersByTimeAsync(1)
      expect(state.outcome).toBe('stream queue wait exceeded')
      await waiter
      release()
    } finally {
      vi.useRealTimers()
    }
  })

  // The gate keeps one timer per waiter, its deadline. A release hands the
  // slot to the oldest waiter in the same turn, so the bound and a release
  // are the only events that settle a waiter.
  it('rejects at maxQueueWaitMs and leaves no timer or abort listener behind', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 55)
      const release = await gate.acquire()
      const abort = new AbortController()
      const { state, waiter } = track(gate, abort.signal)
      await vi.advanceTimersByTimeAsync(54)
      // Witness: one millisecond before the bound the waiter is still queued,
      // with its deadline and its abort listener live, and no other timer.
      expect(state.outcome).toBeUndefined()
      expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
      expect(vi.getTimerCount()).toBe(1)
      expect(getEventListeners(abort.signal, 'abort')).toHaveLength(1)
      await vi.advanceTimersByTimeAsync(1)
      expect(state.outcome).toBe('stream queue wait exceeded')
      expect(vi.getTimerCount()).toBe(0)
      expect(getEventListeners(abort.signal, 'abort')).toHaveLength(0)
      await waiter
      // The queue slot was returned exactly once: one new waiter queues and
      // the one after it finds the queue full.
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      const next = gate.acquire()
      await expect(gate.acquire()).rejects.toThrow('stream queue is full')
      release()
      await vi.advanceTimersByTimeAsync(10)
      ;(await next)()
    } finally {
      vi.useRealTimers()
    }
  })

  it('hands a slot that frees 3 ms before the bound to the waiter in the same turn', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 55)
      const release = await gate.acquire()
      const { state, waiter } = track(gate)
      await vi.advanceTimersByTimeAsync(52)
      // Witness: still queued 3 ms before the bound.
      expect(state.outcome).toBeUndefined()
      release()
      await vi.advanceTimersByTimeAsync(0)
      // No poll interval separates the release from the grant, and the grant
      // cleared the deadline timer.
      expect(state.outcome).toBe('admitted')
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      expect(vi.getTimerCount()).toBe(0)
      ;(await waiter)?.()
      expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses a waiter whose bound and a release fall due in the same millisecond', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 50)
      const release = await gate.acquire()
      const { state, waiter } = track(gate)
      // Armed after the waiter's deadline timer with the same due time, so the
      // deadline runs first.
      setTimeout(release, 50)
      await vi.advanceTimersByTimeAsync(49)
      expect(state.outcome).toBeUndefined()
      await vi.advanceTimersByTimeAsync(1)
      expect(state.outcome).toBe('stream queue wait exceeded')
      await waiter
      // The release found nobody queued, so the slot was freed, not leaked.
      expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses a waiter that a release reaches after the bound because the event loop stalled', async () => {
    const gate = new StreamGate(1, 1, 500)
    const release = await gate.acquire()
    const { state, waiter } = track(gate)
    // Read after acquire() has recorded its own start, so the block below
    // measures at least as long as the gate does. Read before it, a runner
    // pause between the two reads would come out of the 30 ms margin.
    const queuedAt = performance.now()
    await new Promise(resolve => setTimeout(resolve, 20))
    // Witness: the waiter is still queued. The 500 ms bound leaves 25x the
    // 20 ms wait, so a paused runner does not fire the deadline first.
    expect(state.outcome).toBeUndefined()
    // Hold the event loop past the bound, then free the slot before any timer
    // can run. The deadline is overdue, so only the elapsed check in the
    // hand-off can refuse the waiter.
    while (performance.now() - queuedAt < 530) {
      // busy wait
    }
    release()
    // Settled in the release turn, before the deadline timer could run: the
    // hand-off refused the waiter and, with nobody left, freed the slot.
    expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
    ;(await waiter)?.()
    expect(state.outcome).toBe('stream queue wait exceeded')
  })

  it('admits a waiter whose slot frees before maxQueueWaitMs', async () => {
    vi.useFakeTimers()
    try {
      const gate = new StreamGate(1, 1, 55)
      const release = await gate.acquire()
      const abort = new AbortController()
      const { state, waiter } = track(gate, abort.signal)
      await vi.advanceTimersByTimeAsync(45)
      // Witness: the abort listener is registered while the waiter is queued.
      expect(getEventListeners(abort.signal, 'abort')).toHaveLength(1)
      release()
      await vi.advanceTimersByTimeAsync(5)
      expect(state.outcome).toBe('admitted')
      // The deadline timer and the abort listener were cleared on admission.
      expect(vi.getTimerCount()).toBe(0)
      expect(getEventListeners(abort.signal, 'abort')).toHaveLength(0)
      await vi.advanceTimersByTimeAsync(100)
      expect(state.outcome).toBe('admitted')
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      ;(await waiter)?.()
    } finally {
      vi.useRealTimers()
    }
  })

  // Grant order. A release hands its slot to the oldest waiter in the same
  // turn, and a caller that arrives while anyone is queued queues behind them.
  describe('FIFO hand-off', () => {
    function named(
      gate: StreamGate,
      name: string,
      order: string[],
      signal?: AbortSignal,
      deadlineAt?: number
    ) {
      const state: { outcome?: string; release?: () => void } = {}
      const waiter = gate.acquire(signal, deadlineAt).then(
        release => {
          order.push(name)
          state.outcome = 'admitted'
          state.release = release
        },
        (err: RequestLimitError) => {
          state.outcome = err.kind
        }
      )
      return { state, waiter }
    }

    it('grants the older of two waiters queued at different times first', async () => {
      vi.useFakeTimers()
      try {
        const gate = new StreamGate(1, 2, 60_000)
        const hold = await gate.acquire()
        const order: string[] = []
        const older = named(gate, 'older', order)
        await vi.advanceTimersByTimeAsync(5)
        const newer = named(gate, 'newer', order)
        await vi.advanceTimersByTimeAsync(7)
        // Witness: both are queued behind the held slot.
        expect(gate.snapshot()).toEqual({ running: 1, queued: 2 })
        hold()
        await vi.advanceTimersByTimeAsync(20)
        expect(order).toEqual(['older'])
        expect(newer.state.outcome).toBeUndefined()
        expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
        older.state.release!()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['older', 'newer'])
        newer.state.release!()
        await Promise.all([older.waiter, newer.waiter])
        expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
      } finally {
        vi.useRealTimers()
      }
    })

    it('queues a caller that arrives in the release turn behind the waiter', async () => {
      vi.useFakeTimers()
      try {
        const gate = new StreamGate(1, 2, 60_000)
        const hold = await gate.acquire()
        const order: string[] = []
        const queued = named(gate, 'queued', order)
        await vi.advanceTimersByTimeAsync(3)
        hold()
        const late = named(gate, 'late', order)
        // The released slot went to the queued waiter, so the late caller
        // queued instead of taking it.
        expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
        await vi.advanceTimersByTimeAsync(20)
        expect(order).toEqual(['queued'])
        expect(late.state.outcome).toBeUndefined()
        queued.state.release!()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['queued', 'late'])
        late.state.release!()
        await Promise.all([queued.waiter, late.waiter])
        expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
      } finally {
        vi.useRealTimers()
      }
    })

    it('skips an aborted head and grants the waiter behind it', async () => {
      vi.useFakeTimers()
      try {
        const gate = new StreamGate(1, 2, 60_000)
        const hold = await gate.acquire()
        const order: string[] = []
        const abort = new AbortController()
        const head = named(gate, 'head', order, abort.signal)
        const next = named(gate, 'next', order)
        abort.abort()
        await vi.advanceTimersByTimeAsync(0)
        expect(head.state.outcome).toBe('aborted')
        // Only the aborted waiter left the queue.
        expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
        hold()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['next'])
        next.state.release!()
        await Promise.all([head.waiter, next.waiter])
        expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
      } finally {
        vi.useRealTimers()
      }
    })

    it('removes only the waiter whose deadline expires and returns its queue place', async () => {
      vi.useFakeTimers()
      try {
        const gate = new StreamGate(1, 2, 60_000)
        const hold = await gate.acquire()
        const order: string[] = []
        const early = named(gate, 'early', order, undefined, Date.now() + 30)
        const later = named(gate, 'later', order)
        await vi.advanceTimersByTimeAsync(29)
        // Witness: both are queued one millisecond before the first deadline.
        expect(gate.snapshot()).toEqual({ running: 1, queued: 2 })
        await expect(gate.acquire()).rejects.toMatchObject({ kind: 'queue_full' })
        await vi.advanceTimersByTimeAsync(1)
        expect(early.state.outcome).toBe('deadline')
        expect(later.state.outcome).toBeUndefined()
        expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
        // The freed queue place takes a new waiter, which queues behind `later`.
        const third = named(gate, 'third', order)
        expect(gate.snapshot()).toEqual({ running: 1, queued: 2 })
        hold()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['later'])
        later.state.release!()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['later', 'third'])
        third.state.release!()
        await Promise.all([early.waiter, later.waiter, third.waiter])
        expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
      } finally {
        vi.useRealTimers()
      }
    })

    it('passes a slot past a head whose bound a stalled event loop overran', async () => {
      const gate = new StreamGate(1, 2, 5_000)
      const hold = await gate.acquire()
      const order: string[] = []
      const startedAt = Date.now()
      const head = named(gate, 'head', order, undefined, startedAt + 50)
      const next = named(gate, 'next', order)
      const queuedAt = performance.now()
      // Hold the event loop past the head's bound so its deadline timer
      // cannot run before the release.
      while (performance.now() - queuedAt < 80) {
        // busy wait
      }
      hold()
      // The hand-off refused the overdue head and granted the next waiter in
      // the same turn: one slot running, nobody queued.
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      await Promise.resolve()
      await head.waiter
      expect(head.state.outcome).toBe('deadline')
      await vi.waitFor(() => expect(order).toEqual(['next']))
      next.state.release!()
      await next.waiter
      expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
    })

    it('ignores a second call of the same release', async () => {
      vi.useFakeTimers()
      try {
        const gate = new StreamGate(1, 2, 60_000)
        const hold = await gate.acquire()
        const order: string[] = []
        const first = named(gate, 'first', order)
        const second = named(gate, 'second', order)
        hold()
        hold()
        await vi.advanceTimersByTimeAsync(0)
        // One release handed over one slot.
        expect(order).toEqual(['first'])
        expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })
        first.state.release!()
        await vi.advanceTimersByTimeAsync(0)
        expect(order).toEqual(['first', 'second'])
        second.state.release!()
        second.state.release!()
        await Promise.all([first.waiter, second.waiter])
        expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
      } finally {
        vi.useRealTimers()
      }
    })
  })

  it('refuses a maxQueueWaitMs that setTimeout cannot honor', () => {
    // Witness: the bounds themselves are accepted.
    expect(() => new StreamGate(1, 1, 1)).not.toThrow()
    expect(() => new StreamGate(1, 1, 2_147_483_647)).not.toThrow()
    for (const maxQueueWaitMs of [0, -1, 1.5, Number.NaN, 2_147_483_648]) {
      expect(() => new StreamGate(1, 1, maxQueueWaitMs), String(maxQueueWaitMs)).toThrow(RangeError)
    }
  })

  it('refuses a slot or queue size the gate cannot enforce', () => {
    // Witness: the smallest sizes are accepted, including a gate with no queue.
    expect(() => new StreamGate(1, 0)).not.toThrow()
    for (const maxConcurrent of [0, -1, 1.5, Number.NaN]) {
      expect(() => new StreamGate(maxConcurrent, 1), `maxConcurrent=${maxConcurrent}`).toThrow(
        RangeError
      )
    }
    for (const maxQueued of [-1, 1.5, Number.NaN]) {
      expect(() => new StreamGate(1, maxQueued), `maxQueued=${maxQueued}`).toThrow(RangeError)
    }
  })

  it('pins the visual 2/8 sibling, its per-host share, and the ordinary 8/16 gate', () => {
    expect(VISUAL_STREAM_LIMITS).toEqual({ maxConcurrentStreams: 2, maxQueuedRequests: 8 })
    expect(VISUAL_PER_HOST_MAX_ADMITTED).toBe(4)
    expect(STREAM_LIMITS.maxConcurrentStreams).toBe(8)
    expect(STREAM_LIMITS.maxQueuedRequests).toBe(16)
  })

  it('rejects the 11th visual waiter once 2 are running and 8 are queued', async () => {
    const gate = new StreamGate(
      VISUAL_STREAM_LIMITS.maxConcurrentStreams,
      VISUAL_STREAM_LIMITS.maxQueuedRequests
    )
    const held = [await gate.acquire(), await gate.acquire()]
    const queued = Array.from({ length: VISUAL_STREAM_LIMITS.maxQueuedRequests }, () =>
      gate.acquire()
    )
    await expect(gate.acquire()).rejects.toBeInstanceOf(RequestLimitError)
    for (const release of held) release()
    for (const waiter of queued) (await waiter)()
  })

  it('builds the shared visual gate from VISUAL_STREAM_LIMITS', async () => {
    const { maxConcurrentStreams, maxQueuedRequests } = VISUAL_STREAM_LIMITS
    const held: Array<() => void> = []
    for (let i = 0; i < maxConcurrentStreams; i += 1) held.push(await visualStreamGate.acquire())
    expect(visualStreamGate.snapshot()).toEqual({ running: maxConcurrentStreams, queued: 0 })
    // Width: every caller past maxConcurrentStreams queues instead of running.
    const queued = Array.from({ length: maxQueuedRequests }, () => visualStreamGate.acquire())
    expect(visualStreamGate.snapshot()).toEqual({
      running: maxConcurrentStreams,
      queued: maxQueuedRequests,
    })
    // Queue capacity: the caller after maxQueuedRequests is refused.
    await expect(visualStreamGate.acquire()).rejects.toMatchObject({ kind: 'queue_full' })
    for (const release of held) release()
    // Each waiter releases its slot as soon as it gets one, so the cleanup
    // does not depend on the grant order.
    await Promise.all(queued.map(async waiter => (await waiter)()))
    expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
  })
})

/**
 * Records how an acquire settled: `admitted`, or the refusal's kind and wire
 * code. Unset while the waiter is still queued.
 */
function settled(waiter: Promise<() => void>) {
  const state: { outcome?: 'admitted' | { kind: string; code: string } } = {}
  const done = waiter.then(
    release => {
      state.outcome = 'admitted'
      release()
    },
    (err: RequestLimitError) => {
      state.outcome = { kind: err.kind, code: err.code }
    }
  )
  return { state, done }
}

describe('StreamGate refusal identity', () => {
  const FAKE_CLOCK = {
    toFake: ['setTimeout', 'clearTimeout', 'Date', 'performance'] as Array<
      'setTimeout' | 'clearTimeout' | 'Date' | 'performance'
    >,
  }
  const WAIT_MS = STREAM_LIMITS.maxQueueWaitMs

  // The visual gate's own wait is the request's admission clock, so its caller
  // passes the arrival instant. The refusal must not depend on how many ms
  // passed between the arrival stamp and the enqueue.
  it('refuses visual waiters enqueued 0, 1 and 5 ms after arrival as visual_gate at arrival + maxQueueWaitMs', async () => {
    vi.useFakeTimers(FAKE_CLOCK)
    try {
      const gate = new StreamGate(1, 4, WAIT_MS, 'visual_gate')
      const held = await gate.acquire()
      const arrivedAt = Date.now()
      const admissionDeadlineAt = arrivedAt + WAIT_MS
      const atZero = settled(gate.acquire(undefined, admissionDeadlineAt, arrivedAt))
      await vi.advanceTimersByTimeAsync(1)
      const atOne = settled(gate.acquire(undefined, admissionDeadlineAt, arrivedAt))
      await vi.advanceTimersByTimeAsync(4)
      const atFive = settled(gate.acquire(undefined, admissionDeadlineAt, arrivedAt))

      await vi.advanceTimersByTimeAsync(WAIT_MS - 5 - 1)
      // Witness: one millisecond before the admission clock runs out, all
      // three waiters are still queued, so none was refused early.
      expect(Date.now()).toBe(admissionDeadlineAt - 1)
      expect(gate.snapshot()).toEqual({ running: 1, queued: 3 })
      expect([atZero.state.outcome, atOne.state.outcome, atFive.state.outcome]).toEqual([
        undefined,
        undefined,
        undefined,
      ])

      await vi.advanceTimersByTimeAsync(1)
      await Promise.all([atZero.done, atOne.done, atFive.done])
      expect(Date.now()).toBe(admissionDeadlineAt)
      const queueWait = { kind: 'queue_wait', code: 'visual_gate' }
      expect(atZero.state.outcome).toEqual(queueWait)
      expect(atOne.state.outcome).toEqual(queueWait)
      expect(atFive.state.outcome).toEqual(queueWait)
      expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
      held()
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses a visual waiter whose caller deadline is strictly earlier than arrival + maxQueueWaitMs as deadline', async () => {
    vi.useFakeTimers(FAKE_CLOCK)
    try {
      const gate = new StreamGate(1, 4, WAIT_MS, 'visual_gate')
      const held = await gate.acquire()
      const arrivedAt = Date.now()
      await vi.advanceTimersByTimeAsync(5)
      const callerDeadlineAt = arrivedAt + WAIT_MS - 1
      const waiter = settled(gate.acquire(undefined, callerDeadlineAt, arrivedAt))

      await vi.advanceTimersByTimeAsync(callerDeadlineAt - 1 - Date.now())
      // Witness: still queued one millisecond before the caller's deadline.
      expect(waiter.state.outcome).toBeUndefined()
      expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })

      await vi.advanceTimersByTimeAsync(1)
      await waiter.done
      expect(Date.now()).toBe(callerDeadlineAt)
      expect(waiter.state.outcome).toEqual({ kind: 'deadline', code: 'provider_unavailable' })
      held()
    } finally {
      vi.useRealTimers()
    }
  })

  // The ordinary gate measures its own bound from the enqueue. A caller
  // deadline that lands exactly on that bound is the admission clock running
  // out, which is answered with provider_unavailable.
  it('refuses an ordinary waiter whose caller deadline ties its own bound as deadline', async () => {
    vi.useFakeTimers(FAKE_CLOCK)
    try {
      const gate = new StreamGate(1, 1)
      const held = await gate.acquire()
      const enqueuedAt = Date.now()
      const waiter = settled(gate.acquire(undefined, enqueuedAt + WAIT_MS))

      await vi.advanceTimersByTimeAsync(WAIT_MS - 1)
      // Witness: still queued one millisecond before the shared bound.
      expect(waiter.state.outcome).toBeUndefined()
      expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })

      await vi.advanceTimersByTimeAsync(1)
      await waiter.done
      expect(Date.now() - enqueuedAt).toBe(WAIT_MS)
      expect(waiter.state.outcome).toEqual({ kind: 'deadline', code: 'provider_unavailable' })
      held()
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses an ordinary waiter whose caller deadline is 1 ms past its own bound as queue_wait', async () => {
    vi.useFakeTimers(FAKE_CLOCK)
    try {
      const gate = new StreamGate(1, 1)
      const held = await gate.acquire()
      const enqueuedAt = Date.now()
      const waiter = settled(gate.acquire(undefined, enqueuedAt + WAIT_MS + 1))

      await vi.advanceTimersByTimeAsync(WAIT_MS - 1)
      // Witness: still queued one millisecond before the gate's own bound.
      expect(waiter.state.outcome).toBeUndefined()
      expect(gate.snapshot()).toEqual({ running: 1, queued: 1 })

      await vi.advanceTimersByTimeAsync(1)
      await waiter.done
      // The gate's own bound ended the wait, not the later caller deadline.
      expect(Date.now() - enqueuedAt).toBe(WAIT_MS)
      expect(waiter.state.outcome).toEqual({ kind: 'queue_wait', code: 'proxy_capacity_exceeded' })
      held()
    } finally {
      vi.useRealTimers()
    }
  })

  it('refuses a queue wait start that is not a finite epoch time', async () => {
    const gate = new StreamGate(1, 1)
    for (const start of [Number.NaN, Number.POSITIVE_INFINITY]) {
      await expect(gate.acquire(undefined, undefined, start), String(start)).rejects.toThrow(
        RangeError
      )
    }
    // Witness: the refusal took no slot, and a finite start is accepted.
    expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
    const release = await gate.acquire(undefined, undefined, Date.now())
    expect(gate.snapshot()).toEqual({ running: 1, queued: 0 })
    release()
  })
})