Clarify stale repair report metrics

hxrts · hxrts · commit b20a942f188c · 2026-04-21T10:26:03.000+02:00
diff --git a/analysis/document.py b/analysis/document.py
@@ -794,7 +794,7 @@ def write_pdf_report(
                 styles,
                 "Routing-Fitness Stale Repair Summary",
                 stale_block.lines,
-                ["Family", "Engine Set", "Persist", "Recov.", "Unrec.", "Loss", "Churn"],
+                ["Family", "Engine Set", "Persist", "Route", "Unrec.", "Loss", "Churn"],
                 routing_fitness_stale_repair_table_rows(routing_fitness_stale_repair_summary),
                 [3.0 * cm, 2.8 * cm, 1.4 * cm, 1.4 * cm, 1.5 * cm, 1.3 * cm, 1.4 * cm],
                 table_counter,
@@ -1026,7 +1026,7 @@ def write_pdf_report(
         styles,
         "Routing-Fitness Stale Repair Summary",
         stale_ref_block.lines,
-        ["Family", "Engine Set", "Persist", "Recov.", "Unrec.", "Loss", "Churn"],
+        ["Family", "Engine Set", "Persist", "Route", "Unrec.", "Loss", "Churn"],
         routing_fitness_stale_repair_table_rows(routing_fitness_stale_repair_summary),
         [3.0 * cm, 2.8 * cm, 1.4 * cm, 1.4 * cm, 1.5 * cm, 1.3 * cm, 1.4 * cm],
         table_counter,
diff --git a/analysis/plots.py b/analysis/plots.py
@@ -2435,12 +2435,16 @@ def render_routing_fitness_stale_repair(
                 "family_label": row["family_label"],
                 "engine_key": row["comparison_engine_set"],
                 "engine_label": engine_display_label(row["comparison_engine_set"]),
+                "route_presence": float(
+                    row["route_present_total_window_permille_mean"] or 0.0
+                )
+                / 10.0,
                 "stale_persistence": persistence,
                 "label_x": label_x,
                 "recovery_success": float(row["recovery_success_permille_mean"] or 0.0)
                 / 10.0,
-                "recovery_label": (
-                    f"recov={float(row['recovery_success_permille_mean'] or 0.0) / 10.0:.1f}%"
+                "route_label": (
+                    f"route={float(row['route_present_total_window_permille_mean'] or 0.0) / 10.0:.1f}%"
                 ),
                 "detail_label": (
                     f"unrec={int(round(row['unrecovered_after_loss_count_mean'] or 0.0))} "
@@ -2465,7 +2469,8 @@ def render_routing_fitness_stale_repair(
             alt.Tooltip("family_label:N", title="Family"),
             alt.Tooltip("engine_label:N", title="Engine"),
             alt.Tooltip("stale_persistence:Q", title="Stale persistence", format=".1f"),
-            alt.Tooltip("recovery_success:Q", title="Recovery success", format=".1f"),
+            alt.Tooltip("route_presence:Q", title="Route presence", format=".1f"),
+            alt.Tooltip("recovery_success:Q", title="Recovery event success", format=".1f"),
             alt.Tooltip("control_activity:Q", title="Control activity", format=".1f"),
             alt.Tooltip("detail_label:N", title="Detail"),
         ],
@@ -2490,7 +2495,7 @@ def render_routing_fitness_stale_repair(
                 clip=False,
             ).encode(
                 x=alt.X("label_x:Q", scale=alt.Scale(domain=[0, x_limit])),
-                text="recovery_label:N",
+                text="route_label:N",
             ),
             base.mark_text(
                 align="left",
diff --git a/analysis/sections.py b/analysis/sections.py
@@ -861,7 +861,7 @@ def routing_fitness_takeaway_lines(
         routing_fitness_stale_repair_summary,
         filters=[("family_label", "Recovery window")],
         sort_columns=[
-            "recovery_success_permille_mean",
+            "route_present_total_window_permille_mean",
             "stale_persistence_round_mean",
         ],
         descending=[True, False],
@@ -908,7 +908,8 @@ def routing_fitness_takeaway_lines(
         "fit-for-purpose inside the tested search-plus-maintenance envelope"
         if (
             maintenance_high["comparison_engine_set"] == "pathway-batman-bellman"
-            and float(stale_best["recovery_success_permille_mean"] or 0.0) >= 700.0
+            and float(stale_best["route_present_total_window_permille_mean"] or 0.0)
+            >= 900.0
         )
         else "directionally supported, but still carrying one unresolved routing-risk regime"
     )
@@ -939,11 +940,11 @@ def routing_fitness_takeaway_lines(
             [row["comparison_engine_set"] or "none" for row in stale_best_rows]
         ),
         stale_best_persistence=f"{float(stale_best['stale_persistence_round_mean'] or 0.0):.1f}",
-        stale_best_recovery=stale_best["recovery_success_permille_mean"],
+        stale_best_route=stale_best["route_present_total_window_permille_mean"],
         worst_stale_family=worst_stale["family_label"],
         worst_stale_engine=worst_stale["comparison_engine_set"] or "none",
         worst_stale_persistence=f"{float(worst_stale['stale_persistence_round_mean'] or 0.0):.1f}",
-        worst_stale_recovery=worst_stale["recovery_success_permille_mean"],
+        worst_stale_route=worst_stale["route_present_total_window_permille_mean"],
         routing_fitness_envelope=envelope,
     )
 
diff --git a/analysis/tables.py b/analysis/tables.py
@@ -533,7 +533,7 @@ def routing_fitness_stale_repair_table_rows(
                 row["family_label"],
                 engine_display_label(row["comparison_engine_set"]),
                 _format_table_number(row["stale_persistence_round_mean"]),
-                _format_table_number(row["recovery_success_permille_mean"]),
+                _format_table_number(row["route_present_total_window_permille_mean"]),
                 _format_table_number(row["unrecovered_after_loss_count_mean"]),
                 _format_table_number(row["first_loss_round_mean"]),
                 f"{row['route_churn_count_mean']:.1f}",
diff --git a/analysis/tests/test_scoring.py b/analysis/tests/test_scoring.py
@@ -1049,12 +1049,14 @@ def test_routing_fitness_takeaways_close_with_tested_envelope(self) -> None:
                     {
                         "family_label": "Recovery window",
                         "comparison_engine_set": "pathway-batman-bellman",
+                        "route_present_total_window_permille_mean": 930.0,
                         "stale_persistence_round_mean": 2.0,
                         "recovery_success_permille_mean": 900.0,
                     },
                     {
                         "family_label": "Delayed observation",
                         "comparison_engine_set": "pathway",
+                        "route_present_total_window_permille_mean": 640.0,
                         "stale_persistence_round_mean": 4.0,
                         "recovery_success_permille_mean": 600.0,
                     },
@@ -1136,12 +1138,14 @@ def test_routing_fitness_takeaways_keep_tied_best_engine_labels_stable(self) ->
                     {
                         "family_label": "Recovery window",
                         "comparison_engine_set": "pathway-batman-bellman",
+                        "route_present_total_window_permille_mean": 930.0,
                         "stale_persistence_round_mean": 2.0,
                         "recovery_success_permille_mean": 900.0,
                     },
                     {
                         "family_label": "Delayed observation",
                         "comparison_engine_set": "pathway",
+                        "route_present_total_window_permille_mean": 640.0,
                         "stale_persistence_round_mean": 4.0,
                         "recovery_success_permille_mean": 600.0,
                     },
@@ -1183,6 +1187,7 @@ def test_routing_fitness_renderers_keep_deterministic_family_order(self) -> None
         stale_rows = stale["datasets"][stale["data"]["name"]]
         self.assertEqual(stale_rows[0]["family_label"], "Recovery window")
         self.assertEqual(stale_rows[0]["engine_key"], "pathway")
+        self.assertIn("route=", stale_rows[0]["route_label"])
 
     def test_comparison_config_sensitivity_marks_flat_and_separating_families(self) -> None:
         aggregates = pl.from_dicts(
diff --git a/analysis/text.md b/analysis/text.md
@@ -496,7 +496,7 @@ Compact fairness view for the shared-broker families. Column guide: Min and Max
 
 @table routing_fitness_stale_repair_summary
 
-Compact stale-information repair view. Column guide: Persist is the mean bad-route persistence after the first disruptive topology change, Recov. is recovery success, Unrec. is mean unrecovered-after-loss count, Loss is the first-loss round, and Churn is mean route churn.
+Compact stale-information repair view. Column guide: Persist is the mean bad-route persistence after the first disruptive topology change, Route is total-window route presence, Unrec. is mean unrecovered-after-loss count, Loss is the first-loss round, and Churn is mean route churn. Recovery-event success is still exported in the CSV, but it is not used as the headline because many stale scenarios never enter a loss/recovery event path.
 
 ### Routing-Fitness Figure Context
 
@@ -519,15 +519,15 @@ The broker detail labels summarize how much of the visible route activity still
 
 @figure routing_fitness_stale_repair
 
-Bad-route persistence after delayed or asymmetric observations. Shorter bars are better because they mean the engine stops trusting stale routing state quickly after disruption. The labels show recovery success and unrecovered counts so the figure separates fast cleanup from cleanup that still fails to recover.
+Bad-route persistence after delayed or asymmetric observations. Shorter bars are better because they mean the engine stops trusting stale routing state quickly after disruption. The labels show total-window route presence and unrecovered counts so the figure separates fast cleanup from cleanup that still leaves the objective unavailable.
 
 ### Routing-Fitness Takeaways
 
 - In the high search-burden crossover band, {search_high_engines} lead at {search_high_route} permille total-window route presence with {search_high_recovery} permille recovery success.
 - In the high maintenance-benefit crossover band, {maintenance_high_engines} lead at {maintenance_high_route} permille total-window route presence with {maintenance_high_recovery} permille recovery success.
 - Under shared-broker contention, `Shared corridor` is best handled by {shared_corridor_engines} at {shared_corridor_min_route} permille minimum per-flow route presence, while `Detour choice` is best handled by {detour_choice_engines} at {detour_choice_min_route} permille.
 - The harshest fairness tail is currently `{worst_starvation_family}`, where `{worst_starvation_engine}` still records {worst_starvation_value} starved objectives on average.
-- In the stale-repair surface, `Recovery window` is best handled by {stale_best_engines} at {stale_best_persistence} rounds of stale persistence and {stale_best_recovery} permille recovery success, while the worst stale overcommit is `{worst_stale_family}` under `{worst_stale_engine}` at {worst_stale_persistence} rounds and only {worst_stale_recovery} permille recovery success.
+- In the stale-repair surface, `Recovery window` is best handled by {stale_best_engines} at {stale_best_persistence} rounds of stale persistence and {stale_best_route} permille route presence, while the worst stale overcommit is `{worst_stale_family}` under `{worst_stale_engine}` at {worst_stale_persistence} rounds and only {worst_stale_route} permille route presence.
 - Taken together, the new evidence says the candidate direction is {routing_fitness_envelope}.
 
 ## Part III. Diffusion Calibration
diff --git a/docs/305_profile_reference.md b/docs/305_profile_reference.md
@@ -48,4 +48,4 @@ graph LR
 
 The reference end-to-end examples are the split `reference-client` tests in [`crates/reference-client/tests/client_builder.rs`](../crates/reference-client/tests/client_builder.rs), [`crates/reference-client/tests/e2e_pathway_shared_network.rs`](../crates/reference-client/tests/e2e_pathway_shared_network.rs), [`crates/reference-client/tests/e2e_batman_pathway_handoff.rs`](../crates/reference-client/tests/e2e_batman_pathway_handoff.rs), [`crates/reference-client/tests/e2e_olsrv2_shared_network.rs`](../crates/reference-client/tests/e2e_olsrv2_shared_network.rs), and [`crates/reference-client/tests/e2e_olsrv2_pathway_handoff.rs`](../crates/reference-client/tests/e2e_olsrv2_pathway_handoff.rs), plus the shared scenarios in [`crates/testkit/src/reference_client_scenarios.rs`](../crates/testkit/src/reference_client_scenarios.rs). They show how to add a new client runtime to the same in-memory network without bypassing the bridge-owned ingress path or the router-owned canonical path.
 
-For walkthroughs on implementing a custom link or a custom node profile, see [Custom Transport](505_custom_transport.md) and [Custom Device](506_custom_device.md). For the full dependency graph and ownership rules the profile crates fit into, see [Crate Architecture](999_crate_architecture.md).
+For custom link or node profile work, start from the in-tree builders in `jacquard-mem-link-profile` and `jacquard-mem-node-profile`, then validate the ownership boundaries against [Crate Architecture](999_crate_architecture.md).
diff --git a/docs/307_experimental_methodology.md b/docs/307_experimental_methodology.md
@@ -38,7 +38,7 @@ The same discipline applies to policy parameters when a comparison covers polici
 
 ## The Pipeline From Experiment To Report
 
-A simulator run produces `runs.jsonl`, `aggregate_summary.json`, and `breakdown_summary.json` under the run directory. Diffusion runs add `diffusion_runs.jsonl` plus the diffusion aggregate and boundary summaries. Head-to-head runs add `head_to_head_summary.csv`. Model-lane runs add `model_artifacts.jsonl` as a validation companion rather than a scoring input.
+A simulator run produces a per-run log plus aggregate and breakdown JSON files under the run directory. Diffusion runs add their own per-run log plus diffusion aggregate and boundary summaries. Head-to-head reductions are exported into the generated report directory. Model-lane runs add model artifacts as validation companions rather than scoring inputs.
 
 The `analysis/` Python package reads those artifacts. `data.py` loads them into Polars frames. `scoring.py` derives per-run metrics. `tables.py` produces CSV tables. `plots.py` produces vector plots. `sections.py` composes report sections. `report.py` is the entry that assembles the PDF.
 
diff --git a/docs/505_custom_transport.md b/docs/505_custom_transport.md
@@ -104,4 +104,4 @@ The composed profile plugs into the reference client's `ClientBuilder` or into a
 
 The minimum composition wires three things together. First, a router that owns canonical route publication. Second, one or more engines registered on that router, each holding a queue-backed `TransportSenderEffects` handle. Third, a host bridge that owns the `TransportDriver`, drains ingress, stamps `Tick`, and advances the router through synchronous rounds.
 
-For the full capstone that composes a custom transport, a custom engine, and a custom device profile end to end, see [Bringing It Together](507_bringing_it_together.md).
+For end-to-end host composition patterns, see [Client Assembly](503_client_assembly.md) and [Crate Architecture](999_crate_architecture.md).
diff --git a/docs/506_custom_device.md b/docs/506_custom_device.md
@@ -51,7 +51,7 @@ let node = NodePreset::route_capable(options, &PATHWAY_ENGINE_ID).build();
 
 Engine eligibility is encoded through the node's service descriptors. Only engines whose `RoutingEngineId` appears in the node's service surface are eligible to produce route candidates toward that node. A custom device that implements a custom engine tags the engine id in its service descriptor; see [Custom Engine](504_custom_engine.md).
 
-For a device profile to advertise multiple services or multi-engine eligibility, compose the descriptors manually through `SimulatedServiceDescriptor` builders. `ServiceKind` distinguishes `Discover`, `Move`, `Hold`, and other service classes.
+For a device profile to advertise multiple services or multi-engine eligibility, compose the descriptors manually through `SimulatedServiceDescriptor` builders. `RouteServiceKind` distinguishes `Discover`, `Move`, `Hold`, and other service classes.
 
 ## Node State
 
diff --git a/docs/507_bringing_it_together.md b/docs/507_bringing_it_together.md
@@ -12,7 +12,7 @@ The current reference `ClientBuilder` expects the in-tree engines and the in-mem
 
 ## Driving The Custom Client From The Simulator
 
-Lift the custom client into the simulator harness by implementing `JacquardHostAdapter`. The adapter's `build_hosts` method constructs one client per scenario host. Pass the adapter to `JacquardSimulator::new` instead of the default `ReferenceClientAdapter`. The walkthrough for the host adapter lives under [Running Simulations](501_running_simulations.md) in the "Swapping the Host Adapter" section.
+Lift the custom stack into the simulator harness by implementing `JacquardHostAdapter`. The adapter's `build_hosts` method returns one host runtime per scenario host. Pass the adapter to `JacquardSimulator::new` instead of the default `ReferenceClientAdapter`. The walkthrough for the host adapter lives under [Running Simulations](501_running_simulations.md) in the "Swapping the Host Adapter" section.
 
 ```rust
 use jacquard_simulator::{JacquardHostAdapter, JacquardScenario, JacquardSimulator, SimulationError};
@@ -68,7 +68,7 @@ The call shape and the data frames follow the conventions already used for the i
 
 ## Artifact Schema Stability
 
-The Rust simulator guarantees stable schemas for `runs.jsonl`, `aggregate_summary.json`, `breakdown_summary.json`, `diffusion_runs.jsonl`, and the diffusion aggregate and boundary summaries. Schema changes go through explicit versioning. A 3rd party can rely on the shape across patch releases and plan migrations for minor releases.
+The Rust simulator guarantees stable schemas for the per-run JSONL logs plus aggregate, breakdown, diffusion aggregate, and diffusion boundary JSON summaries. Schema changes go through explicit versioning. A 3rd party can rely on the shape across patch releases and plan migrations for minor releases.
 
 Model-lane artifacts are additive and subject to looser guarantees. They serve as a validation companion rather than a scoring input. Consumers who need long-term stability of their custom reductions should target the full-stack artifacts first.
 

Original file line number	Diff line number	Diff line change
`@@ -48,4 +48,4 @@ graph LR`
`48`	`48`
`49`	`49`	The reference end-to-end examples are the split `reference-client` tests in [`crates/reference-client/tests/client_builder.rs`](../crates/reference-client/tests/client_builder.rs), [`crates/reference-client/tests/e2e_pathway_shared_network.rs`](../crates/reference-client/tests/e2e_pathway_shared_network.rs), [`crates/reference-client/tests/e2e_batman_pathway_handoff.rs`](../crates/reference-client/tests/e2e_batman_pathway_handoff.rs), [`crates/reference-client/tests/e2e_olsrv2_shared_network.rs`](../crates/reference-client/tests/e2e_olsrv2_shared_network.rs), and [`crates/reference-client/tests/e2e_olsrv2_pathway_handoff.rs`](../crates/reference-client/tests/e2e_olsrv2_pathway_handoff.rs), plus the shared scenarios in [`crates/testkit/src/reference_client_scenarios.rs`](../crates/testkit/src/reference_client_scenarios.rs). They show how to add a new client runtime to the same in-memory network without bypassing the bridge-owned ingress path or the router-owned canonical path.
`50`	`50`
`51`		`-For walkthroughs on implementing a custom link or a custom node profile, see [Custom Transport](505_custom_transport.md) and [Custom Device](506_custom_device.md). For the full dependency graph and ownership rules the profile crates fit into, see [Crate Architecture](999_crate_architecture.md).`
	`51`	+For custom link or node profile work, start from the in-tree builders in `jacquard-mem-link-profile` and `jacquard-mem-node-profile`, then validate the ownership boundaries against [Crate Architecture](999_crate_architecture.md).
Original file line number	Diff line number	Diff line change
@@ -104,4 +104,4 @@ The composed profile plugs into the reference client's `ClientBuilder` or into a
`104`	`104`
`105`	`105`	The minimum composition wires three things together. First, a router that owns canonical route publication. Second, one or more engines registered on that router, each holding a queue-backed `TransportSenderEffects` handle. Third, a host bridge that owns the `TransportDriver`, drains ingress, stamps `Tick`, and advances the router through synchronous rounds.
`106`	`106`
`107`		`-For the full capstone that composes a custom transport, a custom engine, and a custom device profile end to end, see [Bringing It Together](507_bringing_it_together.md).`
	`107`	`+For end-to-end host composition patterns, see [Client Assembly](503_client_assembly.md) and [Crate Architecture](999_crate_architecture.md).`