From e2056b64367e3d4bd94435fd110b96b99f1722d9 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 11 Jun 2026 19:38:38 +0200 Subject: [PATCH] plan: 0033 unify-runreport-json-serde MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two-task RED→GREEN plan for spec 0033. Task 1 (RED, test-only): flip the engine canonical-form golden + the CLI sweep golden to the serde array-of-pairs/.0-float shape, add the to_json_equals_serde_disk_shape pin test — all fail against the current hand-rolled to_json. Task 2 (GREEN, atomic): promote serde_json dev-dep -> normal dep, swap to_json's body to serde_json::to_string, delete the now-unused json_str helper, refresh the method + module-header doc comments — one build+clippy gate flips every Task-1 assertion green. graph_model.rs:30 + INDEX.md:729 stale cross-refs deferred to cycle-close audit. refs #54 --- docs/plans/0033-unify-runreport-json-serde.md | 280 ++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 docs/plans/0033-unify-runreport-json-serde.md diff --git a/docs/plans/0033-unify-runreport-json-serde.md b/docs/plans/0033-unify-runreport-json-serde.md new file mode 100644 index 0000000..2d2722d --- /dev/null +++ b/docs/plans/0033-unify-runreport-json-serde.md @@ -0,0 +1,280 @@ +# Unify RunReport JSON (serde) — Implementation Plan + +> **Parent spec:** `docs/specs/0033-unify-runreport-json-serde.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run +> this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Render `RunReport` stdout JSON through serde (the same encoder the run +registry uses on disk), retiring the hand-rolled `to_json` writer, so a record's +stdout bytes equal its `runs.jsonl` bytes — pinned by a test. + +**Architecture:** `RunReport` already derives serde; the registry already +serializes via `serde_json::to_string`. This cycle swaps `RunReport::to_json`'s +body to delegate to `serde_json::to_string`, deletes the now-unused hand-rolled +`json_str` helper, promotes `serde_json` from a dev-dep to a normal dep of +`aura-engine`, and flips the two RunReport JSON goldens (engine canonical-form + +CLI sweep) to the serde shape. RED-first: Task 1 moves the goldens + adds the pin +test (RED against the current hand-rolled writer); Task 2 swaps the body + dep +(GREEN). + +**Tech Stack:** `aura-engine` (`report.rs`, `Cargo.toml`), `aura-cli` integration +goldens (`tests/cli_run.rs`), serde / serde_json. + +**Parse-the-bytes gate (self-review #9):** the profile declares no +`spec_validation` → the gate is a no-op. All inlined bodies are Rust (caught by +the `implement` compile gate) or TOML; the JSON goldens live inside Rust string +literals. No surface-language snippet needs a parser. + +--- + +**Files this plan creates or modifies:** + +- Modify: `crates/aura-engine/src/report.rs:6-8` — module-header doc: drop the + now-false "`to_json` is a hand-rolled writer" claim. +- Modify: `crates/aura-engine/src/report.rs:59-103` — `RunReport::to_json` doc + comment + body swapped to serde. +- Modify: `crates/aura-engine/src/report.rs:159-175` — delete the `json_str` + free function (unused after the swap). +- Test: `crates/aura-engine/src/report.rs:389-412` — canonical-form golden + updated to the serde shape. +- Test: `crates/aura-engine/src/report.rs` (tests module, after line 412) — new + `to_json_equals_serde_disk_shape` pin test. +- Modify: `crates/aura-engine/Cargo.toml:8-17` — `serde_json` dev-dep → normal + dep. +- Test: `crates/aura-cli/tests/cli_run.rs:213-216` — sweep golden `params` + substring updated to the serde array-of-pairs shape. + +**Out of scope (deferred to cycle-close audit, per the spec's INDEX.md:729 +deferral precedent):** `crates/aura-engine/src/graph_model.rs:30` stale +cross-reference to `RunReport::json_str` (a different file, #58/#28 territory — +not widened into here); `docs/design/INDEX.md:729` ledger cross-ref. + +--- + +### Task 1: Move the goldens + add the pin test (RED) + +All edits here are test/golden code only. `serde_json` is already a dev-dep, so +the new pin test compiles without the Task-2 dep promotion. Against the current +hand-rolled `to_json` (params-object / whole-int floats), all three assertions +FAIL — the intended RED state proving the serde shape genuinely differs. + +**Files:** +- Test: `crates/aura-engine/src/report.rs:389-412` (canonical-form golden) +- Test: `crates/aura-engine/src/report.rs` (new pin test after line 412) +- Test: `crates/aura-cli/tests/cli_run.rs:213-216` (sweep golden) + +- [ ] **Step 1: Update the engine canonical-form golden to the serde shape** + +In `crates/aura-engine/src/report.rs`, in `to_json_renders_the_canonical_form`, +replace the expected raw-string literal (currently line 410) — only the +`r#"..."#` argument changes, the `RunReport { ... }` fixture above it is +untouched: + +Replace: + +```rust + r#"{"manifest":{"commit":"abc123","params":{"sma_fast":2,"sma_slow":4,"exposure_scale":1},"window":[1,6],"seed":0,"broker":"sim-optimal(pip_size=1.0)"},"metrics":{"total_pips":12,"max_drawdown":1,"exposure_sign_flips":1}}"#, +``` + +with: + +```rust + r#"{"manifest":{"commit":"abc123","params":[["sma_fast",2.0],["sma_slow",4.0],["exposure_scale",1.0]],"window":[1,6],"seed":0,"broker":"sim-optimal(pip_size=1.0)"},"metrics":{"total_pips":12.0,"max_drawdown":1.0,"exposure_sign_flips":1}}"#, +``` + +- [ ] **Step 2: Add the `to_json_equals_serde_disk_shape` pin test** + +In `crates/aura-engine/src/report.rs`, insert this test immediately after +`to_json_renders_the_canonical_form` (after its closing `}` at line 412, before +`runreport_serde_round_trips`). `serde_json` is called fully-qualified (the +existing `runreport_serde_round_trips` does the same — no new `use` needed): + +```rust + #[test] + fn to_json_equals_serde_disk_shape() { + // the same RunReport value the canonical-form test builds. + let report = RunReport { + manifest: RunManifest { + commit: "abc123".to_string(), + params: vec![ + ("sma_fast".to_string(), 2.0), + ("sma_slow".to_string(), 4.0), + ("exposure_scale".to_string(), 1.0), + ], + window: (Timestamp(1), Timestamp(6)), + seed: 0, + broker: "sim-optimal(pip_size=1.0)".to_string(), + }, + metrics: RunMetrics { total_pips: 12.0, max_drawdown: 1.0, exposure_sign_flips: 1 }, + }; + // stdout (to_json) and disk (serde_json::to_string) are now the same bytes. + assert_eq!(report.to_json(), serde_json::to_string(&report).unwrap()); + } +``` + +- [ ] **Step 3: Update the CLI sweep golden to the serde shape** + +In `crates/aura-cli/tests/cli_run.rs`, in +`sweep_prints_four_json_lines_and_exits_zero`, replace the `params` assert +(lines 213-216): + +Replace: + +```rust + assert!( + first.contains("\"params\":{\"sma_cross.fast.length\":2,\"sma_cross.slow.length\":4,\"exposure.scale\":0.5}"), + "got: {stdout}" + ); +``` + +with: + +```rust + assert!( + first.contains("\"params\":[[\"sma_cross.fast.length\",2.0],[\"sma_cross.slow.length\",4.0],[\"exposure.scale\",0.5]]"), + "got: {stdout}" + ); +``` + +- [ ] **Step 4: Verify the engine canonical-form golden FAILS (RED)** + +Run: `cargo test -p aura-engine to_json_renders_the_canonical_form` +Expected: FAIL — `assert_eq!` left/right mismatch (current hand-rolled output has +`"params":{...}` and whole-int floats; the new expected has `"params":[[...]]` +and `.0` floats). + +- [ ] **Step 5: Verify the pin test FAILS (RED)** + +Run: `cargo test -p aura-engine to_json_equals_serde_disk_shape` +Expected: FAIL — `report.to_json()` (hand-rolled, object/int) `!=` +`serde_json::to_string(&report)` (array-of-pairs / `.0`). + +- [ ] **Step 6: Verify the CLI sweep golden FAILS (RED)** + +Run: `cargo test -p aura-cli sweep_prints_four_json_lines_and_exits_zero` +Expected: FAIL — the spawned binary still renders the params-object form, so +`first.contains("\"params\":[[...]]")` is false (panic with `got: {stdout}` +showing the object form). + +--- + +### Task 2: Swap the body + promote the dep (GREEN) + +Promote `serde_json` to a normal dep, swap `to_json`'s body to serde, delete the +now-unused `json_str`, and refresh the two doc comments. These MUST land together: +the body swap references `serde_json` in non-test code (needs the normal dep), and +deleting `json_str` while the hand-rolled body still calls it would not compile — +so the dep move, the body swap, and the `json_str` deletion are one atomic task +with a single build+clippy gate. This flips every Task-1 assertion to GREEN. + +**Files:** +- Modify: `crates/aura-engine/Cargo.toml:8-17` +- Modify: `crates/aura-engine/src/report.rs:6-8` (module header) +- Modify: `crates/aura-engine/src/report.rs:59-103` (`to_json` doc + body) +- Modify: `crates/aura-engine/src/report.rs:159-175` (delete `json_str`) + +- [ ] **Step 1: Promote `serde_json` to a normal dependency** + +In `crates/aura-engine/Cargo.toml`, move `serde_json` from `[dev-dependencies]` +to `[dependencies]`. The two blocks (lines 8-17) become: + +```toml +[dependencies] +aura-core = { path = "../aura-core" } +# serde is admitted under the amended C16 per-case dependency policy (INDEX.md): +# it gives the run-report types a typed (de)serialization path for the run +# registry (cycle 0029). serde's output is deterministic (C1-safe). +serde = { workspace = true } +# serde_json renders RunReport JSON for both the registry (disk) and stdout +# (RunReport::to_json) — one shape, no hand-rolled writer (amended C16). +serde_json = { workspace = true } + +[dev-dependencies] +aura-std = { path = "../aura-std" } +``` + +- [ ] **Step 2: Swap `to_json`'s doc comment + body to serde** + +In `crates/aura-engine/src/report.rs`, replace the whole `to_json` doc comment + +method (lines 59-103 — from the `/// Render canonical…` doc block through the +method's closing `}`) with: + +```rust + /// Render the canonical, machine-readable JSON (C14) via serde — the same + /// encoder the run registry uses on disk, so a record's stdout shape and its + /// `runs.jsonl` shape are byte-identical. `params` is an array of + /// `[name, value]` pairs; finite `f64` fields carry a fractional part + /// (`2.0`). Consumers must parse values as numbers, never key off the token + /// shape. + pub fn to_json(&self) -> String { + serde_json::to_string(self).expect("a finite RunReport always serializes") + } +``` + +- [ ] **Step 3: Delete the now-unused `json_str` helper** + +In `crates/aura-engine/src/report.rs`, delete the entire `json_str` free function +(lines 159-175, the `/// Minimal JSON string rendering…` doc through the fn's +closing `}`). Its only callers were inside the `to_json` body just replaced, so +nothing references it now (leaving it would trip `clippy -D warnings` as +`dead_code`). The independent `json_str` in `graph_model.rs` is untouched. + +- [ ] **Step 4: Refresh the module-header doc** + +In `crates/aura-engine/src/report.rs`, replace the module-header lines 6-8: + +Replace: + +```rust +//! and folds them here. Output is canonical JSON (C14): the schema is tiny, +//! closed, and flat. `to_json` is a hand-rolled writer; the report types also +//! derive serde (cycle 0029) for the run registry's typed read-path. +``` + +with: + +```rust +//! and folds them here. Output is canonical JSON (C14): the schema is tiny, +//! closed, and flat. `to_json` renders via serde (the report types derive it, +//! cycle 0029) — the same encoder the run registry uses, so a record's stdout +//! and on-disk shapes coincide. +``` + +- [ ] **Step 5: Build the workspace (compile gate)** + +Run: `cargo build --workspace` +Expected: success — `aura-engine` compiles with `serde_json` as a normal dep and +the serde-backed `to_json`; no `unused`/`dead_code` from the removed `json_str`. + +- [ ] **Step 6: Verify the engine canonical-form golden PASSES (GREEN)** + +Run: `cargo test -p aura-engine to_json_renders_the_canonical_form` +Expected: PASS — `to_json()` now emits the serde shape matching the updated +expected string. + +- [ ] **Step 7: Verify the pin test PASSES (GREEN)** + +Run: `cargo test -p aura-engine to_json_equals_serde_disk_shape` +Expected: PASS — `to_json()` and `serde_json::to_string(&report)` are now the +same bytes. + +- [ ] **Step 8: Verify the CLI sweep golden + structural golden PASS (GREEN)** + +Run: `cargo test -p aura-cli sweep_prints_four_json_lines_and_exits_zero` +Expected: PASS — the binary now renders params as the array-of-pairs serde form. + +Run: `cargo test -p aura-cli run_prints_json_and_exits_zero` +Expected: PASS — the structural asserts (commit prefix, `window:[1,7]`, +`total_pips:` key, `exposure_sign_flips:1}}`) are shape-agnostic and stay green. + +- [ ] **Step 9: Full workspace gate** + +Run: `cargo test --workspace` +Expected: PASS — all tests green, including the determinism asserts +(`report_is_deterministic_end_to_end`, `run_sample_is_deterministic_and_non_trivial`, +`run_macd_compiles_from_nested_composite_and_is_deterministic`, +`sweep_report_is_deterministic`) which compare two serde outputs and stay green. + +Run: `cargo clippy --workspace --all-targets -- -D warnings` +Expected: clean — no `dead_code` (json_str gone), no warnings.