diff --git a/AGENTS.md b/AGENTS.md index 2111146..592ad76 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1259,6 +1259,10 @@ Issue #90 remains the full hardware-PMU evidence debt (the cache-counter set spe #99 and #110 were addressed by PR #111. Issues #95, #28, and #26 were addressed by PR #112. Issue #94 is the external technical review request and remains one of the highest remaining credibility signals. PR #124 completed M49, PR #125 (d9094df) refreshed the Linux host artifacts on bare-metal -Fedora Asahi, and `v0.2.0` was released (PR #127 ded6e80; resume-anchor sync PR #128 ae93545). There -is no active milestone; the highest-value remaining work is non-code and gated on #94 (external -review) and #90 (full cache-PMU evidence on a PMU-capable microarchitecture). +Fedora Asahi, and `v0.2.0` was released (PR #127 ded6e80; resume-anchor sync PR #128 ae93545). +`v0.2.1` then shipped two reprioritized backlog items plus a consistency sweep: a Codex +resume-anchor/PMU sweep (PR #129), a perf call-graph flamegraph + `make flamegraph` (PR #134, +superseding the auto-closed #130, closing #32), and the FIX-like text protocol adapter (PR #131, +closing #29), with the version bump on the release PR. There is no active milestone; the +highest-value remaining work is non-code and gated on #94 (external review) and #90 (full cache-PMU +evidence on a PMU-capable microarchitecture). diff --git a/CHANGELOG.md b/CHANGELOG.md index 813bef7..98f8da8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,41 @@ All notable changes to this project. The format is loosely based on _Nothing yet._ +## [0.2.1] - 2026-06-21 + +Two backlog items — reprioritized by the maintainer and delivered — plus a resume-anchor and +perf-evidence consistency sweep. Same honesty bar as prior releases: a deterministic C++20 exchange +simulator and cross-language differential-testing harness — **not** a production exchange, no +real-market connectivity, no latency or profitability claims, and not formal verification. + +### Added + +- **FIX-like text protocol adapter (#29).** A human-readable `tag=value` (SOH-framed) codec + (`include/qsl/protocol/fix.hpp`, `src/protocol/fix.cpp`) over the **same internal message structs** + as the binary codec, with genuine FIX framing — BeginString (8) / BodyLength (9) / MsgType (35) / + … / mod-256 CheckSum (10) — for the client→gateway order path: NewOrderSingle (`35=D`) → `NewOrder` + and OrderCancelRequest (`35=F`) → `CancelOrder`. Decoding is total, deterministic, and `noexcept` + (fixed field table, `std::from_chars`, `std::string_view`; no heap on the decode path) and reports + every malformed input through a `FixError` taxonomy mirroring the binary codec's `DecodeError`. + Covered by `tests/unit/test_fix_protocol.cpp`, including a **cross-codec equivalence** test (binary + and FIX decode the same order to identical structs) and a byte-pinned fixture; documented in + `docs/fix_protocol.md`. Prices stay integer ticks and Symbol carries the numeric `SymbolId` + (documented simplifications, never floating-point price). +- **`make flamegraph` (#32).** Renders a Linux `perf` call-graph flamegraph + (`results/flamegraph.svg` + a provenance/classification `results/flamegraph.txt`) from the + benchmark harness via `scripts/flamegraph.py` — a dependency-free (stdlib-only) stackcollapse + SVG + renderer (deterministic; unit-tested in `tests/shell/test_flamegraph.sh`), so the artifact is + reproducible from the repo without vendoring the Perl FlameGraph toolkit. The committed artifact is + a software cpu-clock sampling **hot-symbol profile** from the bare-metal Fedora Asahi host — not a + latency/throughput claim; full hardware cache-PMU evidence stays in issue #90. + +### Changed + +- Synced the `/resume` anchors and perf-evidence wording to the released `v0.2.0` state and narrowed + an overstated Apple **Blizzard** (E-core) PMU claim — those rows read `` because the + single-threaded benchmark stays on the Avalanche P-cores (Codex follow-up to PRs #127/#128): + `PROGRESS.md`, `AGENTS.md`/`CLAUDE.md` agreement, and `docs/perf_analysis.md`. + ## [0.2.0] - 2026-06-21 Quant Systems Lab v0.2.0 — the Phase III/IV systems arc (M24–M49: a bounded SPSC queue and threaded diff --git a/CLAUDE.md b/CLAUDE.md index 46e95c2..0b0cabd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1203,6 +1203,10 @@ Issue #90 remains the full hardware-PMU evidence debt (the cache-counter set spe #99 and #110 were addressed by PR #111. Issues #95, #28, and #26 were addressed by PR #112. Issue #94 is the external technical review request and remains one of the highest remaining credibility signals. PR #124 completed M49, PR #125 (d9094df) refreshed the Linux host artifacts on bare-metal -Fedora Asahi, and `v0.2.0` was released (PR #127 ded6e80; resume-anchor sync PR #128 ae93545). There -is no active milestone; the highest-value remaining work is non-code and gated on #94 (external -review) and #90 (full cache-PMU evidence on a PMU-capable microarchitecture). +Fedora Asahi, and `v0.2.0` was released (PR #127 ded6e80; resume-anchor sync PR #128 ae93545). +`v0.2.1` then shipped two reprioritized backlog items plus a consistency sweep: a Codex +resume-anchor/PMU sweep (PR #129), a perf call-graph flamegraph + `make flamegraph` (PR #134, +superseding the auto-closed #130, closing #32), and the FIX-like text protocol adapter (PR #131, +closing #29), with the version bump on the release PR. There is no active milestone; the +highest-value remaining work is non-code and gated on #94 (external review) and #90 (full cache-PMU +evidence on a PMU-capable microarchitecture). diff --git a/CMakeLists.txt b/CMakeLists.txt index 383a4e6..19fc3b1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,5 @@ cmake_minimum_required(VERSION 3.24) -project(quant-systems-lab VERSION 0.2.0 LANGUAGES CXX) +project(quant-systems-lab VERSION 0.2.1 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) diff --git a/HANDOFF.md b/HANDOFF.md index ba1dafa..00271c9 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -16,7 +16,8 @@ command lists, roadmap state, non-overclaiming rules, and benchmark rules. --- ## Current handoff -The repo is released at `v0.2.0` (tag on ded6e80, marked Latest), after `v0.1.0`. M0–M49 are +The repo's current release is `v0.2.1` (tagged on the release-PR merge commit, marked Latest), after +`v0.2.0` (ded6e80) and `v0.1.0`. M0–M49 are merged. PR #101 (40f9249) and PR #102 (7092423) synchronized project-memory files after M35. PR #103 (0f2ceb7) inserted the repository-health refactor phase **M36–M42** and shifted the original networking/persistence roadmap after those @@ -28,8 +29,12 @@ refactors. PR #113 extended the future roadmap to **M43–M49**. M36–M42 lande PR #123 (c643b62), and PR #124 (d8c16b2), with M45B provenance migration in PR #116 (b9ea27a) and the M47 storage diagnosis follow-up in PR #122 (548cb68). The Linux host artifact refresh landed as PR #125 (d9094df), and the **v0.2.0 release** — a bare-metal Linux evidence refresh, the -partial-PMU reframe, and a full documentation staleness sweep — landed as PR #127 (ded6e80). There -is no active milestone; the project is between releases. +partial-PMU reframe, and a full documentation staleness sweep — landed as PR #127 (ded6e80). The +**v0.2.1 release** then adds two reprioritized backlog items and a consistency sweep: a Codex +resume-anchor/PMU sweep (PR #129), a perf call-graph flamegraph + `make flamegraph` (PR #130, +issue #32), the FIX-like text protocol adapter (PR #131, issue #29), and the version-bump release +PR — merged in that order, with `v0.2.1` tagged on the release merge commit. There is no active +milestone; the project is between releases. Background — Linux perf evidence (merged, now bare-metal partial PMU): @@ -65,33 +70,36 @@ git pull --ff-only git log --oneline -10 gh pr list --state open git tag -l -gh release view v0.2.0 +gh release view v0.2.1 ``` Current state: -- latest synced main baseline: `ded6e80` (PR #127, v0.2.0 release) +- latest synced main baseline: `ded6e80` (PR #127, v0.2.0); the `v0.2.1` baseline is the release-PR + merge commit, after PRs #129/#130/#131 - current active branch, if active: none (work lands via scoped PRs from `main`) -- current active status: `v0.2.0` released. The bare-metal Linux evidence refresh, the - partial-PMU reframe (real Apple PMU counters; cache counters unsupported), and a full - documentation staleness sweep are merged. All 15 `results/*.txt` are bare-metal with - `Dirty inputs: no` and no MAC leaks; `make check` 241/241 and `make asan` 241/241; README and - recruiting benchmark numbers match `results/latest.txt`. No active milestone -- release tag: `v0.2.0` (Latest), after `v0.1.0` +- current active status: `v0.2.1` is the current release on top of `v0.2.0`. It adds the FIX-like + text protocol adapter (#29), `make flamegraph` + a bare-metal flamegraph artifact (#32), and a + Codex resume-anchor/PMU consistency sweep. `make check` 263/263 and `make asan` 263/263 on the + bare-metal Apple M2 Fedora Asahi host; both new code files pass the CI CodeScene Code Health gate. + No active milestone +- release tag: `v0.2.1` (Latest, tagged on the release-PR merge commit), after `v0.2.0` and `v0.1.0` - open follow-up issue: #90 — narrowed to the full cache-counter PMU set; the bare-metal Apple host provides real cycles/instructions/branches/branch-misses but no cache-reference/cache-miss support -- issues #95, #28, and #26 were closed by PR #112 +- issues #95, #28, and #26 were closed by PR #112; issues #32 and #29 were closed by PR #134 and + PR #131 (now part of `v0.2.1`) - open review request issue: #94 -- legacy backlog still open: #32 (#29 delivered in this PR, `feat/fix-text-protocol-adapter`) +- legacy backlog: clear — #32 (flamegraph) and #29 (FIX adapter) shipped in `v0.2.1` (PR #134, + PR #131) ### Next milestone -There is no active milestone. M0–M49, the Linux artifact refresh (PR #125), and the v0.2.0 release -(PR #127) are merged. The highest-value remaining work is non-code and externally gated: issue #94 -(independent external review — needs a human reviewer) and issue #90 (full cache-counter PMU -evidence — needs a PMU microarchitecture that exposes cache events). #29 (FIX-like text protocol -adapter) is delivered in this PR; low-signal backlog: #32 (flamegraph). Do not invent a new -milestone without an explicit human request. +There is no active milestone. M0–M49, the Linux artifact refresh (PR #125), the v0.2.0 release +(PR #127), and the v0.2.1 content (PRs #129/#134/#131 + release PR) are merged. The highest-value +remaining work is non-code and externally gated: issue #94 (independent external review — needs a +human reviewer) and issue #90 (full cache-counter PMU evidence — needs a PMU microarchitecture that +exposes cache events). The #32 (flamegraph) and #29 (FIX adapter) backlog items are now done. Do not +invent a new milestone without an explicit human request. ### Phase III / IV purpose @@ -101,15 +109,14 @@ studies, advanced concurrency validation, event-driven gateway architecture, mul pressure, NUMA/affinity and scheduler-migration studies, ingress memory ordering and false-sharing evidence, persistence/recovery benchmarking, and late-stage low-latency networking research. -Current priority order (post-v0.2.0): +Current priority order (post-v0.2.1): 1. Issue #94 — independent external technical review remains the single highest credibility gap (human-gated; cannot be self-certified). 2. Issue #90 — full cache-counter PMU evidence. The bare-metal Apple host gives real cycles/instructions/branches/branch-misses but no cache-reference/cache-miss counters, so this needs a PMU microarchitecture that exposes cache events (x86_64, or an ARM server core). -3. Low-signal backlog only after the above: #32 (flamegraph). #29 (FIX adapter) is delivered in - this PR (`feat/fix-text-protocol-adapter`). +3. No low-signal backlog remains: #32 (flamegraph) and #29 (FIX adapter) shipped in `v0.2.1`. ### Forbidden shortcuts diff --git a/PROGRESS.md b/PROGRESS.md index 751757e..53d81cc 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -20,48 +20,45 @@ Do not rely on prior chat memory. ## Current state -- **Active milestone:** none — `v0.2.0` released; project is between releases -- **Status:** ☑ `v0.2.0` published (Phase III/IV systems arc + bare-metal evidence refresh) +- **Active milestone:** none — `v0.2.1` released; project is between releases +- **Status:** ☑ `v0.2.1` published (FIX-like text protocol adapter #29, perf flamegraph #32, and a + resume-anchor/PMU consistency sweep) on top of `v0.2.0` - **Active branch:** none (work lands via scoped PRs from `main`) - **Last completed milestone:** M49 — NIC offload and low-latency networking study (PR #124, - d8c16b2), then the Linux host artifact refresh (PR #125, d9094df) and the v0.2.0 release - (PR #127, ded6e80) -- **Last completed docs sync:** resume-anchor + PMU-claim sync (`docs/codex-resume-anchor-sync`, - this PR) resolving the Codex findings left on `main` by PRs #127/#128. Prior sweep: v0.2.0 - documentation staleness sweep (PR #127): perf evidence reframed as bare-metal partial PMU, - release-readiness rewritten, every doc read and brought current -- **Release:** `v0.1.0` (tag on 9857e1a) and `v0.2.0` (tag on ded6e80, marked Latest) published as - GitHub-only releases; no packages published -- **`make check` passing:** yes — `make check` 241/241 and `make asan` 241/241 on the bare-metal - Apple M2 (aarch64) Fedora Asahi host on 2026-06-21 -- **Last action:** resume-anchor + PMU-claim sync on `docs/codex-resume-anchor-sync` resolving the - Codex review findings left on `main` by PRs #127/#128 — removed PROGRESS's stale "Next action - remains" block that still pointed `/resume` at the merged PR #125, brought AGENTS.md in line with - CLAUDE.md's v0.2.0 partial-PMU reframe (no more "constrained Docker validation" wording), and - narrowed docs/perf_analysis.md so the Apple Blizzard (E-core) PMU rows are not implied to carry - live counts. Docs/memory only; no code or artifacts changed (`make check` still 241/241). -- **Prior action (v0.2.0 release):** prepared and released `v0.2.0`. Reframed the perf evidence from - "constrained Docker validation" to **partial hardware PMU evidence** on a bare-metal Apple M2 (real - cycles/instructions/branches/branch-misses; cache-references/cache-misses unsupported by the Apple - Silicon PMU), with a new three-way `perf_stat.sh` classifier and a reframed issue #90. Regenerated - all 15 `results/*.txt` on bare metal (`Dirty inputs: no`, MAC-leak grep clean), bumped the project - version to 0.2.0, swept every doc for staleness (release-readiness rewritten to 241 tests / six CI - jobs; architecture/socket/storage/OCaml framing corrected), verified all six mermaid diagrams, and - synced README/recruiting benchmark numbers to `results/latest.txt` (~87/16/110/98/110 ns). - PR #127 squash-merged to `main` as ded6e80; `v0.2.0` tagged and published. + d8c16b2); since then `v0.2.0` (PR #127, ded6e80) and the `v0.2.1` content: Codex resume-anchor + sweep (PR #129), perf flamegraph #32 (PR #134), and the FIX text adapter #29 (PR #131) +- **Last completed docs sync:** v0.2.1 release prep (this PR): version bump + CHANGELOG `[0.2.1]` + and resume/release anchors brought current +- **Release:** `v0.1.0` (tag on 9857e1a), `v0.2.0` (tag on ded6e80), and `v0.2.1` (tag created on the + squash-merge of the release PR, marked Latest) published as GitHub-only releases; no packages + published +- **`make check` passing:** yes — `make check` 263/263 and `make asan` 263/263 on the bare-metal + Apple M2 (aarch64) Fedora Asahi host on 2026-06-21 (includes the v0.2.1 FIX-adapter and flamegraph + renderer tests) +- **Last action:** delivered the `v0.2.1` content as scoped PRs and prepared this version-bump + release. Two reprioritized backlog items — the FIX-like text protocol adapter (#29) and the perf + call-graph flamegraph (#32) — plus the Codex resume-anchor/PMU consistency sweep (#127/#128 + follow-up). Ran Codex as an independent reviewer across the stack and resolved every finding: the + FIX envelope now requires MsgType as the first body field and rejects duplicate tags; + `flamegraph.sh` classifies zero-sample/partial runs honestly, fails hard on renderer errors, and + gates on the folded sample total (not perf's estimate); and the resume anchors were made + consistent across PROGRESS/HANDOFF/AGENTS/CLAUDE. Brought every touched file through the CodeScene + Code Health gate (table-driven enum maps, a `decode_typed` skeleton, split `parse_envelope`, + flattened `flamegraph.py`). `make check`/`make asan` 263/263. - **Next action:** no active milestone. Highest-value remaining work is non-code and gated: issue #94 (independent external review — needs a human reviewer) and issue #90 (full cache-counter PMU evidence — needs a PMU microarchitecture that exposes cache events, e.g. - x86_64). #29 (FIX-like text protocol adapter) is delivered in this PR - (`feat/fix-text-protocol-adapter`). Low-signal backlog: #32 (flamegraph). + x86_64). The #32 (flamegraph) and #29 (FIX adapter) backlog items are done — shipped in `v0.2.1` + (PR #134 and PR #131) — so do not reopen them. - **Blockers:** issue #90 is now a *cache-counter* PMU gap, not a host-access gap — this bare-metal Apple M2 exposes real `cycles`/`instructions`/`branches`/`branch-misses` but its PMU does not implement `cache-references`/`cache-misses`; closing it needs a PMU microarchitecture that exposes cache events (x86_64, or an ARM server core). Issue #94 remains open for independent external review (human-gated). Hardware NIC/offload latency measurement still requires suitable wired NIC hardware, driver support, timestamping/offload/RSS access, and a measured packet workload; the - current `wld0` Wi-Fi capability observation is not NIC-offload latency evidence. Legacy backlog - still includes #32 (#29 delivered in this PR). Issues #95, #28, and #26 were closed by PR #112. + current `wld0` Wi-Fi capability observation is not NIC-offload latency evidence. The legacy + backlog is now clear: #32 and #29 shipped in `v0.2.1` (PR #134, PR #131); issues #95, #28, and + #26 were closed by PR #112. --- @@ -405,6 +402,35 @@ Lower priority: in `docs/fix_protocol.md` (+ pointer from `docs/binary_protocol.md`). `make check` 260/260 and `make asan` 260/260 clean (the parser handles untrusted text). Closes #29. Do not merge from automation; human squash-merges. +- [2026-06-21] Post-review code-health pass on #130/#131 after Codex + the CI CodeScene Code Health + gate flagged `flamegraph.py` and `fix.cpp` below the 10.0 health bar. `flamegraph.py`: bundled + render args into a `FlameOptions` dataclass + extracted `_append_chrome`/`_frame_svg`, flattened + `fold_perf_script` into a `_Folder`, replaced the nested dso scan with a regex, and dropped an + unused `_layout` arg. `fix.cpp`: table-driven enum maps via `FieldReader::coded`, a `decode_typed` + skeleton to remove decoder duplication, and `parse_envelope` split into + tokenize/check-shape/verify-length-checksum. Behavior unchanged (`make check`/`make asan` 261/261); + both PRs' CodeScene gate now passes. Also fixed three Codex findings (cancel `ClOrdID` enforcement; + flamegraph tab/non-positive collapsed parsing). The local CodeScene MCP token is expired, so the + authoritative gate is the CI `CodeScene Code Health Review` check. +- [2026-06-21] Prepared the `v0.2.1` release (`docs/v0.2.1-release`, stacked on the FIX adapter PR): + bumped `CMakeLists.txt` to 0.2.1, added the CHANGELOG `[0.2.1]` section (FIX adapter #29, perf + flamegraph #32, resume-anchor/PMU sweep), and brought the PROGRESS/HANDOFF release anchors current. + No code or benchmark artifacts change in the release PR itself. On squash-merge the human tags + `v0.2.1` on the merge commit and publishes the GitHub release. Do not merge from automation. +- [2026-06-22] Second Codex review round on the open `v0.2.1` stack — addressed every remaining + inline finding across PRs #129/#130/#131/#133. #131 (`fix.cpp`): the FIX envelope now requires + MsgType (35) as the first body field (rejecting `8/9/34/35/.../10`) and `tokenize` rejects + duplicate tags (no repeating groups), with a deterministic rejection test for each; the older + cancel-`ClOrdID` finding was already resolved and is covered by an existing test. #130 + (`flamegraph.sh`): classify `zero-sized data` as a perf limitation (matching `perf_record.sh`), + remove a stale SVG on zero-stack partial runs, accept perf's `(~N samples)` estimate marker and + gate on the **folded** sample total instead of perf's estimate, fail hard (exit 4) on renderer + errors instead of `|| true`, and derive the software/hardware sampling label+caveat from the + selected event; regenerated the bare-metal artifact (329 folded samples, `Dirty inputs: no`). + #129: recorded the resume-anchor sync in PROGRESS's top current-state. #133: bumped the v0.2.1 + release anchors and removed completed #29/#32 from every backlog list, synced AGENTS.md/CLAUDE.md + to the v0.2.1 released state, and refreshed this release-readiness audit to 263 tests. `make + check`/`make asan` 263/263. CodeScene MCP token still expired; CI is the authoritative gate. - [2026-06-03] M35: implemented a multi-client TCP connection-scaling load test (`scripts/socket_load.sh`, `make socket-load`, Linux-only) driving N concurrent `qsl-client`s against the portable TCP and epoll (M34) gateways; `results/socket_load_summary.txt` is Docker-generated and constrained. A `/code-review` (3 finder agents) caught and fixed real measurement-integrity bugs before the PR: a failed trial's `wall=0` no longer poisons the reported best (only trials whose gateway served count toward the min); the `completed` column reports the WORST per-trial completion, not the last, so partial/total trial failures are surfaced rather than masked; a per-client `timeout` bounds a hang if the gateway dies; and `QSL_LOAD_TRIALS` is validated. Post-PR hardening uses fresh monotonic ports per gateway start, retries transient startup/serve failures on new ports, and refuses to write a partial artifact unless `QSL_LOAD_ALLOW_PARTIAL=1` is set intentionally; the refreshed artifact records `Dirty tree: no`. The scaling-shape claim remains constrained to loopback connection setup, not a demonstrated production-capacity advantage for either transport. Deferred follow-up: a shared `scripts/lib` to remove the dirty-tree / `wait_ready` / gateway-stop duplication across the three socket scripts. - [2026-06-03] M35: started after M34 (#98) squash-merged (commit 9e3750b). Scope: multi-client load / socket-pressure testing of the gateway/feed path (TCP/UDP stress, socket-buffer pressure, connection scaling, backpressure) building on M34's epoll multi-client path and M30's socket tooling. Constraints: scripts/tests document load shape + environment; results must distinguish kernel/socket pressure from user-space engine cost; no production-capacity claims (honest constrained-environment framing, like M29/M30). - [2026-06-04] M35: PR #100 squash-merged to `main` as a86b701 after all CI jobs and review checks were green. M35 is now landed; original M36 NUMA remains deferred until the repository-health refactor analysis is completed or explicitly skipped by the human. @@ -811,12 +837,14 @@ Quant Systems Lab — Linux Systems + Exchange Infrastructure Simulator ## Next action remains -There is no active milestone. `v0.2.0` is released (PR #127 ded6e80, tag on ded6e80, marked Latest; -resume-anchor sync PR #128 ae93545). M0–M49, the Linux host artifact refresh (PR #125, d9094df), and -the v0.2.0 release are all merged to `main`. The committed perf artifacts are **partial hardware PMU -evidence** from this bare-metal Apple M2 (aarch64) Fedora Asahi host — real -cycles/instructions/branches/branch-misses with cache-reference/cache-miss counters unsupported by -the Apple Silicon PMU — not NIC-offload, latency, or full hardware-PMU evidence. +There is no active milestone. `v0.2.1` is the current release, on top of `v0.2.0` (PR #127 ded6e80) +and `v0.1.0`. The `v0.2.1` content is squash-merged to `main`: the Codex resume-anchor sweep +(PR #129), the perf flamegraph #32 (PR #134, superseding the auto-closed #130), the FIX text adapter +#29 (PR #131), and the version-bump release PR (#133), with `v0.2.1` tagged on the release merge +commit. The committed perf artifacts remain **partial hardware PMU evidence** from this bare-metal +Apple M2 (aarch64) Fedora Asahi host — real cycles/instructions/branches/branch-misses with +cache-reference/cache-miss counters unsupported by the Apple Silicon PMU — not NIC-offload, latency, +or full hardware-PMU evidence. Highest-value remaining work is non-code and gated: issue #94 (independent external review) and issue #90 (full cache-PMU evidence). Issue #90 needs a PMU **microarchitecture** that exposes cache diff --git a/docs/release_readiness.md b/docs/release_readiness.md index c6f0f4e..2fa1637 100644 --- a/docs/release_readiness.md +++ b/docs/release_readiness.md @@ -1,16 +1,18 @@ # Release Readiness Audit A pre-release pass verifying the repo builds, demos, reproduces, and reads honestly. This audit -covers **M0–M49 plus the v0.2.0 evidence refresh** (bare-metal Linux artifact regeneration and the -documentation/staleness sweep). It supersedes the v0.1.0-era audit; the actual GitHub release is -cut by a human after squash-merge. +covers **M0–M49, the v0.2.0 evidence refresh** (bare-metal Linux artifact regeneration and the +documentation/staleness sweep), **and the v0.2.1 content** (the FIX-like text protocol adapter #29, +the perf call-graph flamegraph + `make flamegraph` #32, and a Codex resume-anchor/PMU consistency +sweep). It supersedes the v0.1.0-era audit; the actual GitHub release is cut by a human after +squash-merge. ## Verification (this session, bare-metal Apple M2 / aarch64 / GCC 16.1.1, Fedora Asahi Remix) | Check | Result | |---|---| -| `make check` | 241/241 tests pass, no warnings | -| `make asan` (ASan + UBSan) | 241/241, sanitizer-clean | +| `make check` | 263/263 tests pass, no warnings (incl. the v0.2.1 FIX-adapter + flamegraph-renderer tests) | +| `make asan` (ASan + UBSan) | 263/263, sanitizer-clean (the FIX text parser handles untrusted input) | | `make tsan` (ThreadSanitizer) | 20/20 concurrency-labelled tests, race-clean | | `make check-fixtures` | committed differential fixtures match current C++ output | | `make check-manifest` | provenance manifest matches the committed fixtures | @@ -19,6 +21,7 @@ cut by a human after squash-merge. | `dune runtest --root ocaml` | suites pass: log-invariant verifier, independent replay engine, differential replay (50 property fixtures), failure-bundle (`diff_report`), and oracle mutation testing | | `make demo` | clean, deterministic (replay/recovery + loopback gateway round-trip) | | `make bench` / `make bench-diff` | reproduce from the committed harness; `results/latest.txt` and `results/differential.txt` are bare-metal Apple M2 runs (single-machine, run-to-run variance) | +| `make flamegraph` (Linux perf, v0.2.1) | bare-metal cpu-clock call-graph profile → `results/flamegraph.svg`/`.txt`, classified `software cpu-clock sampling hot-symbol profile`, gated on the folded sample total, `Dirty inputs: no` | CI mirrors these across six jobs: `build-test` (build + test + bench compile-check + `check-fixtures` + `check-manifest` + fmt), `sanitizers` (ASan/UBSan), `thread-sanitizer`, @@ -36,6 +39,8 @@ does not buy: `instructions` / `branches` / `branch-misses` off the Apple Avalanche/Blizzard PMUs, with `cache-references` / `cache-misses` reported `` (Apple Silicon PMU limitation). Not full PMU evidence; issue #90 tracks the cache-counter set, which needs a different PMU. + `results/flamegraph.svg`/`.txt` (v0.2.1) is a **software cpu-clock sampling** hot-symbol profile + from the same host — a hot-symbol investigation aid, not a latency or throughput claim. - **Sockets** — `socket_profile_loopback.txt`, `socket_stress_summary.txt`, and `socket_load_summary.txt` are bare-metal but **loopback-only**: no NIC/driver/routing. - **NUMA** — `numa_affinity_study.txt` is bare-metal but the M2 is a **single-NUMA-node** machine, @@ -64,7 +69,8 @@ artifact leaks host identifiers (a publish-time MAC sanitizer redacts every non- separation, constrained/partial perf artifacts, loopback socket evidence, PMR node allocation, epoll prototype, durability modes and tail repair). - **No stale milestone references**: PROGRESS, HANDOFF, and the milestone tables reflect the merged - M0–M49 state and the v0.2.0 artifact refresh. + M0–M49 state, the v0.2.0 artifact refresh, and the v0.2.1 content (#29/#32 closed; resume anchors + consistent across PROGRESS/HANDOFF/AGENTS/CLAUDE). ## Scope and honesty @@ -82,6 +88,7 @@ verification. ## Outcome -Release-ready as a portfolio artifact. The next GitHub-only release is `v0.2.0` (Phase III/IV -systems work — M24–M49 — plus the bare-metal evidence refresh); it requires explicit human approval -and a squash-merge before tagging. +Release-ready as a portfolio artifact. The next GitHub-only release is `v0.2.1` (the FIX-like text +protocol adapter #29, the perf flamegraph #32, and a Codex resume-anchor/PMU consistency sweep) on +top of `v0.2.0` (Phase III/IV systems work — M24–M49 — plus the bare-metal evidence refresh); it +requires explicit human approval and a squash-merge before tagging.