release: v0.3.0 — FIX text protocol adapter (#29), perf flamegraph (#32), anchor sweep

CHANGELOG.md

@@ -7,6 +7,41 @@ All notable changes to this project. The format is loosely based on
 
 _Nothing yet._
 
+## [0.3.0] - 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 `<not counted>` 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

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.3.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)

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.3.0` (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.3.0 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.3.0` 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,32 +70,34 @@ 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.3.0
 ```
 
 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.3.0` 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.3.0` 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` 261/261 and `make asan` 261/261 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.3.0` (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 #130 and
+  PR #131 (now part of `v0.3.0`)
 - open review request issue: #94
-- legacy backlog still open: #29 and #32
 
 ### 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). Low-signal backlog: #32
-(flamegraph) and #29 (FIX adapter). 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.3.0 content (PRs #129/#130/#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
 
@@ -100,7 +107,7 @@ 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.3.0):
 
 1. Issue #94 — independent external technical review remains the single highest credibility gap
    (human-gated; cannot be self-certified).

PROGRESS.md

@@ -20,27 +20,27 @@ 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.3.0` released; project is between releases
+- **Status:** ☑ `v0.3.0` 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:** 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:** 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.3.0` content: Codex resume-anchor
+  sweep (PR #129), perf flamegraph #32 (PR #130), and the FIX text adapter #29 (PR #131)
+- **Last completed docs sync:** v0.3.0 release prep (this PR): version bump + CHANGELOG `[0.3.0]`
+  and resume/release anchors brought current
+- **Release:** `v0.1.0` (tag on 9857e1a), `v0.2.0` (tag on ded6e80), and `v0.3.0` (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` 261/261 and `make asan` 261/261 on the bare-metal
+  Apple M2 (aarch64) Fedora Asahi host on 2026-06-21 (includes the v0.3.0 FIX-adapter and flamegraph
+  renderer tests)
+- **Last action:** delivered the `v0.3.0` 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 and fixed its findings; 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` 261/261.
 - **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.
@@ -396,6 +396,21 @@ 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.3.0` release (`docs/v0.3.0-release`, stacked on the FIX adapter PR):
+  bumped `CMakeLists.txt` to 0.3.0, added the CHANGELOG `[0.3.0]` 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.3.0` on the merge commit and publishes the GitHub release. Do not merge from automation.
 - [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.
@@ -802,12 +817,13 @@ 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.3.0` is the current release, on top of `v0.2.0` (PR #127 ded6e80)
+and `v0.1.0`. The `v0.3.0` content lands as the Codex resume-anchor sweep (PR #129), the perf
+flamegraph #32 (PR #130), the FIX text adapter #29 (PR #131), and the version-bump release PR; the
+human squash-merges those in order and tags `v0.3.0` 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