From fc94642662e15f8cc8ee7bf5ba8e54daef4adbda Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 07:04:31 -0500 Subject: [PATCH] docs: the scheduler's 32 and 64 are one constant, and "cutover" is overloaded live-scheduler.md is accurate -- worker_count 32, result_capacity 4096, batch_size 50, batch_timeout 500 ms and the verify_queue_dropped_events_total counter all verified against ingest/pipeline.zig. Three things a reader cannot see from the text. Per-DID pending capacity is key_queue_capacity = worker_count * 2, so the "thirty-two workers" and "64 pending events" in the contract are the same constant. They read as independent knobs; changing worker_count silently moves the drop-oldest threshold. That bound is also the one the batch submit/consume deadlock turned on, so it carries two responsibilities. "Graceful cutover" here means the shutdown handover -- stop admission, drain, tear down workers. Everywhere else in docs/ cutover is the lifecycle phase transition out of merge where serving stops 503ing. Two unrelated events sharing a word, in a file about the path that runs after that transition. Flagged both senses. Also expands Atmos on first use, and notes the constants are matched to upstream rather than chosen here -- which is why they are not tunable. Co-Authored-By: Claude Opus 5 (1M context) --- docs/live-scheduler.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/live-scheduler.md b/docs/live-scheduler.md index 6b313e5..6d1d690 100644 --- a/docs/live-scheduler.md +++ b/docs/live-scheduler.md @@ -1,7 +1,27 @@ # Live scheduler parity Stream's live path follows the scheduler and cursor behavior in pinned Atmos -v0.2.14, which Jetstream V2 configures with its defaults. +v0.2.14 — the Go atproto library upstream Jetstream V2 runs, and the reference +these numbers come from — which Jetstream V2 configures with its defaults. So +the constants below are matched to upstream, not chosen here. + +Verified against `ingest/pipeline.zig` on 2026-07-30: `worker_count = 32`, +`result_capacity = 4096`, `batch_size = 50`, `batch_timeout = 500 ms`, and the +`jetstream_livestream_verify_queue_dropped_events_total` counter all exist as +described. + +**The 32 and the 64 are one constant, not two.** Per-DID pending capacity is +`key_queue_capacity = worker_count * 2`, so "32 workers" and "64 pending events" +are not independent knobs — changing `worker_count` silently changes the +drop-oldest threshold with it. That same `worker_count * 2` bound is the one the +batch submit/consume deadlock turned on (see `invariants.md`, "a bounded producer +must not outrun its consumer"), so it carries two responsibilities at once. + +**"Cutover" below does not mean what it means elsewhere.** In this file +"graceful cutover" is the *shutdown* handover — stop admission, drain, tear down +workers. In `deployment-runbook.md`, `upstream-bootstrap-spec.md` and the other +lifecycle docs, cutover is the *phase transition* out of merge into steady state +where serving stops returning 503. Two unrelated events, one word. ## Contract -- 2.51.2