README
¶
Speculation Path Enumerator
Vendor-agnostic interface for enumerating the candidate speculation paths of a batch — the raw material the orchestrator assembles into the batch's speculation tree.
See the Speculation RFC for the end-to-end design and how enumeration fits into the orchestrator pipeline.
Enumerator
An enumerator is deliberately dumb and purely structural: given a batch and its active dependency batches, it mechanically lists the candidate paths. It does not score paths — that is the scorer's job, which the controller re-runs on every respeculate — it does not decide which paths to build — that is the selector's job — it does not set path status, and it does not decide how far back to speculate. The dependency limit is the controller's responsibility: the controller gates a batch on the limit and hands the enumerator exactly the active dependencies to speculate over, which it then enumerates over verbatim.
Each candidate is a path: an assumed-good prefix of predecessor batches (the base) on top of which the batch under verification (the head) is built. The base maps directly onto the build stage's base changes and the head onto the changes being validated. The dependency batches are handed to the enumerator oldest-first (queue arrival order), and that ordering is load-bearing: it fixes which assumed-good prefixes exist and the order of predecessors within each.
Enumeration is pure and deterministic: the same batch and dependency list always produce the same paths. This lets the controller regenerate the candidates whenever the dependency graph changes without tracking incremental state in the enumerator. Keeping enumeration tractable for a very wide dependency list is the enumerator's only real concern.
The returned paths carry structure only — a Base/Head split, nothing else. Everything else about a path is owned by the controller, which wraps each one into the persisted tree entry: it assigns the path its identity, stamps its status, and calls the scorer to fill its score. Enumeration produces none of these.
Factory
A per-queue factory returns the enumerator for a queue, following the repo's extension contract. It is handed only the queue identity and nothing else; everything an implementation needs — including behavioral knobs like enumeration breadth — is injected at construction by the integrator in the wiring layer, which resolves per-queue settings through queueconfig. Enumeration itself stays config-free.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// QueueName identifies the queue this Enumerator serves.
QueueName string
}
Config carries the per-queue identity handed to a Factory. The system knows only the queue name; everything an implementation needs (including behavioral knobs such as speculation depth) is injected at construction by the integrator.
type Enumerator ¶
type Enumerator interface {
// Enumerate returns the candidate speculation paths for the batch, given its
// active dependency batches ordered oldest-first (queue arrival order). That
// ordering is load-bearing: a path's Base is an assumed-good prefix of
// predecessors applied in order, so the deps ordering fixes which Base
// prefixes exist and the order of batch IDs within each.
//
// Enumeration is pure and deterministic: the same (batch, deps) always
// yields the same paths, so callers may regenerate safely. Returned paths
// must not contain duplicates (same Head and same ordered Base).
Enumerate(ctx context.Context, batch entity.Batch, deps []entity.Batch) ([]entity.SpeculationPath, error)
}
Enumerator lists the candidate speculation paths for a batch — the raw material the controller assembles into the batch's speculation tree.
Enumeration answers "what futures are possible" for a batch. It is deliberately dumb and purely structural: it mechanically lists candidate Base/Head paths from the dependency batches it is handed and nothing else. It does not score paths — that is the scorer's job (see extension/speculation/pathscorer), which the controller re-runs on every respeculate — it does not decide which paths to build — that is the selector's job (see extension/speculation/selector) — and it does not decide how far back to speculate: the controller gates on the dependency limit and hands Enumerate exactly the active dependencies to speculate over.
Its output is structure only. Everything else about a path — its identity, status, and score — is owned by the controller, which wraps each returned path into the persisted tree entry (entity.SpeculationPathInfo).
type Factory ¶
type Factory interface {
// For returns the Enumerator for the given queue.
For(cfg Config) (Enumerator, error)
}
Factory builds the Enumerator for a queue. Implementations are provided by integrators (and tests) and inject whatever they need at construction.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package chain provides an enumerator.Enumerator that enumerates a batch as exactly one path, built directly on top of the full ordered chain of its active dependencies.
|
Package chain provides an enumerator.Enumerator that enumerates a batch as exactly one path, built directly on top of the full ordered chain of its active dependencies. |
|
Package fake provides a programmable in-memory enumerator.Enumerator for tests and examples.
|
Package fake provides a programmable in-memory enumerator.Enumerator for tests and examples. |
|
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |