Repository navigation
spec(queen): reviewer_sizing.t27 - the reviewer's worker pool follows its backlog and its lanes #8273
Copy link
Copy link
Closed
Labels
Description
Part of gHashTag/trios#1712 (item 3: reviewer concurrency read from the measured backlog).
reviewer.t27 (#8212) says how many rows may be reviewed at once: reviewer_concurrency(keys, lanes_per_key, free_mb, mb_per_review, waiting), capped at REVIEWER_CEILING (16). The runtime in gHashTag/trios still starts a fixed REVIEWER_CONCURRENCY = 4 workers. To size the pool from that rule, the runtime needs four more decisions, and by the Only-t27 rule they belong in a spec:
- Which lanes count. A key counts what it still carries for a review, never more than its provider is measured to carry. On 2026-09-15, z.ai refused a third concurrent request on one key with
1302in under half a second. The lanes the pool's own busy reviews hold also count. A lane held by a killed review does not. - Which rows count. Rows under review and rows queued. If only queued rows counted, the pool would shrink below its own busy workers.
- What memory a review is charged until it is measured.
mb_per_review = 0reads as "one review", so a host that has not measured would never grow. - When an idle worker stops. Only while the pool is larger than its target, and only after it has been idle a while, as Akka Cluster Sharding passivates an idle entity.
Boundary
specs/queen/reviewer_sizing.t27(new).trinity/seals/queen_QueenReviewerSizing.json(new)docs/now/(one entry)
Acceptance criteria
t27c test-report specs/queen/reviewer_sizing.t27: no FAIL, 0 vacuous tests.- Each new rule, broken once, makes
test-reportFAIL or blocks the spec from compiling (negative controls listed in the PR). t27c gen-coutput builds to wasm with every fn exported, and two builds give one hash.
User Scenarios
- Given a reviewer pool with 3 keys each measured at 2 lanes, 2 busy reviews holding 1 lane each, and 4 queued rows, when the sizing rule runs, then the target concurrency counts 3×2 = 6 key lanes minus 2 busy lanes = 4 available lanes, capped at REVIEWER_CEILING (16), so the pool sizes to 4 workers.
- Given a host that has not yet measured
mb_per_review(value 0) and 500 MB free, when the sizing rule computesreviewer_concurrency, thenmb_per_review = 0is treated as one review per unit so memory does not block growth, and the pool sizes by lanes and backlog instead. - Given a pool sized to 6 workers with 4 currently busy and 2 idle for longer than the idle timeout, when the backlog drops so the target becomes 4, then the 2 idle workers stop because the pool exceeds its target and they have been idle long enough.
Requirements
- FR-001: The spec MUST define
lanes_available(keys, busy_lanes)that sums each key's measured lane capacity, never exceeding the provider's measured capacity, and subtracts lanes held by busy reviews, excluding lanes from killed reviews. - FR-002: The spec MUST define
backlog_rows(under_review, queued)that counts both rows currently under review and rows queued for review, so the pool does not shrink below its own busy workers. - FR-003: The spec MUST define
effective_mb_per_review(mb_per_review)that returns 1 whenmb_per_review == 0, otherwise returnsmb_per_review, so an unmeasured host charges one review per unit of memory. - FR-004: The spec MUST define
idle_worker_may_stop(pool_size, target_size, idle_duration, idle_timeout)that returns true only whenpool_size > target_sizeANDidle_duration >= idle_timeout, mirroring Akka Cluster Sharding passivation semantics. - FR-005: The spec MUST compose the above into
reviewer_concurrency(keys, lanes_per_key, free_mb, mb_per_review, waiting, busy_lanes, under_review, queued, idle_duration, idle_timeout)that returns the target worker count capped atREVIEWER_CEILING (16).
Reactions are currently unavailable
Activity