mirror of https://github.com/bdbrown4/peltier.io.git synced 2026-11-07 19:08:27 +00:00

Files

T

Claude 328aafae77 Bootstrap hotpath from engineering spec v0.1

Commit the spec and scaffold the system it describes:

- SPEC.md: the full v0.1 engineering spec
- crates/: trust-layer Rust workspace, unit-tested
  - bench-runner: interleaved ABAB scheduling with discarded warm-ups,
    deterministic bootstrap CIs over the ratio of medians,
    CI-lower-bound accept rule, env fingerprinting, and a CLI with
    compare + A/A self-test modes (A/A verified passing end-to-end)
  - diff-test: gate outcome model, sha256 corpus pin verifier that
    refuses on mismatch, per-target equivalence policy parser
    (byte-identical default, explicit fp-tolerance opt-in)
  - ledger: append-only SQLite attempt schema with UPDATE/DELETE
    refused by triggers, anti-double-attempt query
  - report: cores-saved and dollars/yr ROI math over speedup CIs,
    pricing.toml inputs
- playbook/: classes 1-7 with preconditions, procedure, verification
  notes, and known failure modes per class
- agent/: Python package skeleton — six-tool contract and prompting
  spine, harness IPC deferred to Phase 1
- config/: accept.toml (2% threshold, 30 runs/side), pricing.toml
- targets/, corpora/, results/calibration/: layout and policy docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2

2026-07-06 18:34:51 +00:00

2.0 KiB

Raw Blame History

Class 1 — Build configuration

Zero source changes. Always first: a large fraction of real-world CPU is lost to shipping defaults.

Preconditions

Any CPU-bound target not already using an optimized release profile.
Profile signature: flat-ish flamegraph with time spread across many small frames (inlining starved); heavy call overhead into tiny leaf functions; or a build that visibly lacks -O2/--release.
Check before anything else: opt-level, lto, codegen-units, panic, target-cpu (Rust); -O, -march, -flto (C/C++).

Procedure (cheapest first)

Confirm release profile: opt-level=3, panic=abort where the target permits, codegen-units=1.
target-cpu=native / -march=native — only when the deployment fleet's ISA baseline is known; record the chosen baseline in the hypothesis.
LTO: thin, then fat. Watch build-time cost; fat LTO on huge targets can be a net loss for the engagement.
PGO: instrument with the golden-replay corpus as the training run, rebuild with the profile. The corpus is representative by construction.
BOLT (post-link layout) where the binary and toolchain permit.

Verification notes

Flags must not include any -ffast-math-class option — that's an equivalence change, auto-routed to needs-human-review (SPEC §8).
Byte-identical golden replay still applies: build flags occasionally change FP contraction on some ISAs (-march enabling FMA); if golden replay diverges on numeric output, stop — this class is not equivalence-preserving for that target without a tolerance policy.

Known failure modes

target-cpu=native on the bench machine but not the fleet: a real win that the customer cannot deploy. Pin the ISA baseline to the fleet.
PGO trained on a non-representative workload overfits the benchmark — hold out workloads (SPEC §11).
Layout changes from LTO/BOLT interact with layout bias (§7): measured wins here especially need the randomize-and-aggregate protocol.

2.0 KiB Raw Blame History