Nw Speculative Dispatch

Speculative Dispatch Methodology

Speculative dispatch is a technique where the orchestrator generates N candidate implementations of the same TDD step in parallel, scores each by measured properties, and picks the best — while logging every candidate, including discarded ones, for human audit.

1. When to Use Speculative Dispatch

Use speculative dispatch when the decision is ambiguous and at least 3 feasible candidate strategies exist.

Speculative dispatch is orthogonal to TDD stages — it applies at any phase (RED unit-test authoring, GREEN, COMMIT under the 3-phase canon per ADR-025; or RED_UNIT, GREEN, COMMIT under the legacy 5-phase contract) where ambiguity is genuine and 3 candidates are feasible within the time budget.

2. The Three-Candidate Rule

Generate exactly 3 candidates per speculative step by default:

Three candidates is the minimum viable set for meaningful scoring. More than 5 candidates adds noise without proportional signal. Each candidate must be behaviourally correct before scoring — incorrect candidates are eliminated before scoring, not by scoring.

3. Auditability Mandate

ALL candidates must be logged — winner AND losers.

Discarded candidates have audit value. A human reviewer validating the orchestrator's pick must be able to inspect every alternative considered, not just the selected one. This is not optional.

What the audit log captures per candidate

candidate_id:     unique name within the step (e.g. "minimal-change")
step_id:          identifies the TDD step these candidates competed on
timestamp_iso:    ISO-8601 when the trace was written
files_modified:   tuple of relative paths modified by this candidate
tests_added:      tuple of test file paths added
tests_pass:       True / False — did the full test suite pass?
rationale:        human-readable explanation of this candidate's approach

Why losers matter

A loser trace explains:

• What the orchestrator tried and why it was discarded.
• Whether the discard was due to test failure (hard signal) or lower score (preference).
• Whether a future reviewer would make the same call.

Without loser traces, the audit log is a winner's narrative — it cannot be challenged or validated.

4. Scoring Model

Candidates are ranked by a composite 5-tuple score. Tuple ordering implements priority naturally: Python's built-in > comparison on tuples is sufficient.

score(metrics) -> (tests_pass: int, -complexity_delta, -lines_added, 0, -runtime)

Priority order (element 0 dominates):

Correctness gate: a candidate with tests_pass=False is ALWAYS dominated by any candidate with tests_pass=True, regardless of all other metrics. This prevents the orchestrator from ever selecting a broken candidate on the grounds that it is "simpler".

5. pick_best Rationale Requirements

The pick_best function must return a rationale string that:

1. Names the winner candidate_id.
2. Names every loser candidate_id.
3. States the winner's key metrics (tests_pass, complexity_delta, lines_added).
4. States why each loser was discarded (test failure, or specific metric comparison).

A rationale that omits any candidate is an audit violation. Reviewer agents check that all candidate_ids appear in the rationale string.

6. Storage Layout

<root>/
  .nwave/
    speculative/
      <step_id>/
        traces.jsonl      # one JSONL line per candidate, in write order

• One file per step. All candidates for a step share the file.
• Append-only. Never overwrite. Each write_trace call appends one line.
• read_traces(step_id, root=root) returns all candidates for the step.
• Human-readable with jq or any JSONL viewer.

Inspection example

cat .nwave/speculative/ws-prepended-with/traces.jsonl | python -m json.tool

7. Stage Cascade Fit

Speculative dispatch is stage-agnostic. It applies at any TDD phase where a genuine implementation choice exists:

Do not apply speculative dispatch to mechanical steps (adding an import, renaming a variable, fixing a typo). Reserve it for decisions with measurable trade-offs.

8. Integration with nwave_ai.speculative

Two modules provide the walking-skeleton implementation:

from nwave_ai.speculative.audit import CandidateTrace, write_trace, read_traces
from nwave_ai.speculative.score import CandidateMetrics, score, pick_best

Workflow

# 1. Build and run candidates (external to this module)
#    Each candidate modifies files, runs tests, records outcome.

# 2. Write a trace for each candidate — ALL of them, pass or fail
trace = CandidateTrace(
    candidate_id="minimal-change",
    step_id="step-42",
    timestamp_iso=datetime.utcnow().isoformat() + "Z",
    files_modified=("src/foo.py",),
    tests_added=("tests/test_foo.py",),
    tests_pass=True,
    rationale="Single-expression — no new abstractions.",
)
write_trace(trace, root=Path("."))

# 3. Build metrics for each candidate
metrics_map = {
    "minimal-change": CandidateMetrics(
        tests_pass=True, complexity_delta=1, lines_added=3, test_runtime_seconds=0.5
    ),
    ...
}

# 4. Recover all traces and pick best
traces = read_traces("step-42", root=Path("."))
winner, rationale = pick_best(traces, metrics_map)

# 5. Apply winner's changes; discard losers (but keep audit log)
print(f"Selected: {winner.candidate_id}")
print(f"Rationale: {rationale}")

9. Anti-Patterns

10. Empirical Baseline (walking skeleton)

Walking skeleton verified 2026-05-05 (tests/speculative/test_walking_skeleton.py):

Three candidates implement prepended_with(value, prefix) -> bool:

Rationale produced:

Selected: minimal-change (tests_pass=True, complexity_delta=1, lines_added=2).
Discarded candidates:
  - refactor-heavy: tests_passed, complexity_delta=5, lines_added=12.
  - pattern-extraction: tests_passed, complexity_delta=4, lines_added=10.

All three candidate_ids appear in the rationale. Auditability mandate satisfied.