Skip to content

spec(queen): reviewer_sizing.t27 - the reviewer's worker pool follows its backlog and its lanes #8273

Closed

Description

@gHashTag

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 1302 in 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 = 0 reads 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-report FAIL or blocks the spec from compiling (negative controls listed in the PR).
  • t27c gen-c output 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 computes reviewer_concurrency, then mb_per_review = 0 is 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 when mb_per_review == 0, otherwise returns mb_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 when pool_size > target_size AND idle_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 at REVIEWER_CEILING (16).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions