Docs / Optimizer

Optimizer methodology

The optimizer searches a discrete neighborhood of reversible settings, measures each candidate with KraftBench, and keeps only what passes stability and comparison gates.

Mode

Milestone 1 / current safe path supports --mode safe only. Balanced/Aggressive modes are rejected with a clear error rather than silently doing something else.

kraftverk optimize --mode safe --goal balanced

Goals include: balanced, gaming, compile, workstation, throughput, latency, efficiency, sustained, quiet.

Safe parameters (implemented)

Key	Scope	Rollback
`bench.worker_threads`	Process / KraftBench workers	Yes
`bench.rayon_threads`	Local rayon pool size	Yes
`process.priority`	Current process (`normal` / `above_normal` / `high`)	Yes (best-effort)
`process.affinity`	Current process (`all` / `even` / `odd` / `first_half`)	Yes (best-effort)

Not implemented (explicitly unsupported): GPU clocks, power plans, registry tweaks, TRIM/cleaners, other-process affinity.

Search strategy

Deterministic hill climbing (HillClimbStrategy) with a reproducible seed
Neighborhood: discrete thread counts, priority, affinity variants
Stop conditions: max experiments, time budget, plateau limit, neighborhood exhausted, instability

ε-greedy / Bayesian plugins may be listed in the architecture as future work — treat unimplemented strategies as non-claims.

Lifecycle per candidate

Apply via ApplyGuard (writes recovery journal)
Verify each change
Measure (warm-up + samples)
Compare to baseline index samples
Rollback during search
Provisional best → validation run with more samples
Accept + commit (keep applied) or reject + rollback

flowchart LR
  A[Propose] --> B[Apply + journal]
  B --> C[Measure]
  C --> D{Better + stable?}
  D -->|search| E[Rollback]
  E --> A
  D -->|validate pass| F[Commit]
  D -->|fail| E

Stability gate

Validation requires:

Stability PASS (CoV ≤ threshold, checksums present, ≥2 samples)
Comparison class improvement (LIKELY_* or CONFIRMED_*)

Sessions, hot-plug, recovery

Optimizer sessions can resume; hardware eligibility is re-checked. If a disallowed GPU appears mid-session, Kraftverk stops, restores managed config, and blocks further execution.

On launch, RecoveryJournal restores any interrupted apply so a crash mid-experiment does not leave the process in a mystery state.

Statistics · Safety · Architecture