feat(speculation): generator contract and bestfirst impl

[behinddwalls]

Summary

Why?

The standard Speculator needs a ranked stream of candidate speculation paths to fund. Nothing enumerates or ranks the path space today.

What?

Adds submitqueue/extension/speculation/generator — the Generator/PathIterator contract — plus the bestfirst implementation and mocks.

The generator is a pure enumerator: Open takes only the queue’s batches and offers every coherent path, including ones whose builds already ran. Suppressing those belongs to the Allocator, which reconciles candidates against stored path sets by ID.

bestfirst ranks each path by how likely all its assumptions are to hold and generates lazily: one heap holds the frontier of every head’s path tree, so pulling k paths does O(k) work however large the space behind them. Scores are summed log probabilities so wide heads cannot underflow into ties, and canonical subset expansion emits each path exactly once in non-increasing score order. The full algorithm, tie-breaks, derivation, and floating-point constraints live in doc/rfc/submitqueue/speculation-generator-best-first.md; the package README now records only operational behavior.

Also sharpens scorer.Scorer’s contract: it returns the probability that a batch’s build succeeds — the quantity bestfirst consumes — rather than “the likelihood of a successful land.”

Test Plan

✅ ./tool/bazel test //submitqueue/extension/speculation/generator/...

✅ make fmt

✅ make lint

✅ make check-tidy

✅ make check-gazelle

Stack

1. docs(rfc): explain best-first speculation generation #513
2. @ feat(speculation): generator contract and bestfirst impl #446
3. feat(speculation): allocator contract and sticky impl #450
4. feat(speculation): standard composed speculator #451
5. feat(storage): speculation path set store #501
6. feat(storage): path-build link store for per-path builds #502
7. feat(orchestrator): dispatch builds per speculation path #503
8. feat(orchestrator): poll builds and stop the ones nothing wants #504
9. fix(orchestrator): mint distinct message IDs for cancel re-publishes #505
10. feat(orchestrator): re-plan the queue from the Speculator each run #506
11. feat(orchestrator)!: finalize batches from their speculation paths #507
12. feat(orchestrator): compose per-queue speculators and turn speculation on #508