docs(rfc): add speculation design

[behinddwalls]

Summary

Capture how SubmitQueue speculates before the interfaces land. Speculation is modeled as two layers: decision seams — enumeration and scoring describe the tree of possible bets, selection and prioritization act on it — and signal-driven limit policies that decide how much to allow at each step (dependency limit, selection limit, prioritization limit), scaling with the build system's resources. A path's score is dynamic — recomputed as dependencies land, fail, or have their builds pass — not frozen at enumeration.

Covers: the problem (dependent batches serialize behind multi-minute builds), the Base/Head path-and-tree model, where speculation sits in the orchestrator pipeline, the status-vs-action ownership split, the dependency limit as an eligibility gate (batches wait for predecessors to land rather than trimming their base), dynamic rescoring, and how prioritization rations the queue's builds against its budget.

Design only; entities, store, and extension interfaces follow in later PRs in this stack. Adds doc/rfc/submitqueue/speculation.md and links it from the RFC index.

Changes since review

Reframed from two seams (enumeration + selection) to describe/act decisions + limits, addressing @sbalabanov's review:

• selector resource-awareness → the new prioritization layer owns the queue-wide build budget; the selector stays a pure per-batch policy
• "variable depth, not a single knob" → the dependency limit is a signal-driven policy, not a constant
• clarified the dependency limit is an eligibility gate on active in-flight dependencies (a batch waits until predecessors land), not a base trim
• dynamic scoring: split scoring out of enumeration into a scorer that recomputes each path's score as dependencies land/fail/pass — enumeration is now structure-only
• entire tree persisted (the selector reads all path statuses + scores, so it can cancel a path it earlier asked to build); the redundant fallback path is cancelled on a winning bet; slash-free example names; trimmed impl-detail bullets
• recorded as open: extending rescoring to weigh how long a batch has waited

Test Plan

Doc-only. Rendered locally; ASCII diagrams and tables verified; no hard-wrapped prose.

Issues

Stack

1. @ docs(rfc): add speculation design #230
2. feat(entity,storage): rework speculation tree model and store #231
3. feat(speculation): add enumerator and selector extensions #232

[sbalabanov]

sending it back as it is quite old, resubmit if needed

[behinddwalls]

Reworked and resubmitting. Reframed the design around three decisions (enumeration, selection, prioritization) + three signal-driven limit policies (dependency / selection / prioritization limit) that scale with build resources.

Addresses all review comments:

• Selector resource-awareness — the new prioritization layer is the queue-wide enforcer that rations builds against the queue's budget; the selector stays a pure per-batch policy, with its SelectionLimit injected and called internally.
• Variable depth, not one knob — the dependency limit is a signal-driven policy, not a constant.
• What depth means — clarified it's an eligibility gate on active in-flight dependencies (a batch waits until predecessors land), not a base trim; added a gating-by-example.
• Store all paths? — yes, the controller persists the entire tree; the selector reads every path's status and can cancel one it earlier asked to build.
• Redundant fallback cancelled on a winning bet; slash-free example names; leaf-only target validation kept prominent; impl-detail bullets trimmed.
• Open item recorded: rescoring a batch the longer it waits queued.

PTAL @sbalabanov