mirror of
https://github.com/bdbrown4/peltier.io.git
synced 2026-11-07 10:58:28 +00:00
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
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
# Class 4 — Data layout
|
||||
|
||||
Make the memory hierarchy work for the access pattern.
|
||||
|
||||
## Preconditions
|
||||
- Profile signature: high cache-miss rate in `perf stat` (LLC misses per
|
||||
instruction), hot loops whose flamegraph frames are memory-bound
|
||||
(`perf` cycles concentrated on loads), low IPC (<1) on wide cores.
|
||||
- For false sharing: multithreaded target where per-thread throughput
|
||||
degrades as threads are added; `perf c2c` confirms.
|
||||
|
||||
## Procedure (cheapest first)
|
||||
1. Struct field reordering / packing: kill padding, group hot fields on
|
||||
one cache line, split hot/cold (`#[repr(C)]` review, cold-field
|
||||
box-out).
|
||||
2. AoS→SoA for loops that touch one field across many elements —
|
||||
restructure the container, not the algorithm.
|
||||
3. False-sharing fixes: pad or align per-thread state to 64 bytes
|
||||
(`#[repr(align(64))]`, `crossbeam_utils::CachePadded`).
|
||||
4. Cache blocking / loop tiling for nested loops over large matrices or
|
||||
images; tile to L1/L2, verified empirically, not by datasheet.
|
||||
|
||||
## Verification notes
|
||||
- Layout changes to any type that crosses FFI, serialization, or hashing
|
||||
boundaries can change observable behavior (struct hash, serialized
|
||||
bytes, memcmp-based equality) — golden replay catches this; check the
|
||||
target for `#[repr]`-sensitive traits before patching.
|
||||
- Differential fuzz the functions whose types changed, not just the
|
||||
functions whose code changed.
|
||||
|
||||
## Known failure modes
|
||||
- Reordering fields of a type that derives `Hash`/`Ord` used in ordered
|
||||
iteration → output order changes → replay divergence (correct reject).
|
||||
- AoS→SoA wins the target loop but loses every other access site; the
|
||||
end-to-end number is the verdict, not the microbench.
|
||||
- Alignment padding blowing up per-element size until the working set
|
||||
falls out of cache — the cure worse than the disease.
|
||||
Reference in New Issue
Block a user