From 4331bac458853819c7b224056d92cf37486a5806 Mon Sep 17 00:00:00 2001 From: nasr <156965421+div0rce@users.noreply.github.com> Date: Sun, 21 Jun 2026 21:54:58 -0400 Subject: [PATCH] =?UTF-8?q?release:=20v0.3.0=20=E2=80=94=20FIX=20text=20pr?= =?UTF-8?q?otocol=20adapter,=20perf=20flamegraph,=20anchor=20sweep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bump the project version 0.2.0 -> 0.3.0 and record the release. - CMakeLists.txt: project VERSION 0.3.0. - CHANGELOG.md: new [0.3.0] section — FIX-like text protocol adapter (#29), `make flamegraph` + dependency-free renderer (#32), and the Codex resume-anchor / PMU-claim consistency sweep (#127/#128 follow-up); [Unreleased] reset. - PROGRESS.md / HANDOFF.md: release and resume anchors brought to the v0.3.0 released state; #29 and #32 marked done. No code or benchmark artifacts change in this release PR. On squash-merge, tag `v0.3.0` on the merge commit and publish the GitHub release. make check 261/261. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 35 ++++++++++++++++++++++++++ CMakeLists.txt | 2 +- HANDOFF.md | 45 +++++++++++++++++++--------------- PROGRESS.md | 66 +++++++++++++++++++++++++++++++------------------- 4 files changed, 103 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 813bef7..27a0fa9 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.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 `` 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/CMakeLists.txt b/CMakeLists.txt index 383a4e6..35c6504 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.3.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) diff --git a/HANDOFF.md b/HANDOFF.md index 0bee945..65e6dd1 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.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). diff --git a/PROGRESS.md b/PROGRESS.md index f7c953c..2ebb4ee 100644 --- a/PROGRESS.md +++ b/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