From c5059c2fc8886a4bfccdc7b9aa3b64fc871b496a Mon Sep 17 00:00:00 2001 From: Marcin Pawlowski Date: Wed, 5 Aug 2026 10:42:03 +0200 Subject: [PATCH] Consolidate the TSI report into one document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four-part split existed because the single report had grown dense and heavily cross-referenced; splitting traded that for a different cost, which the merged read makes visible. Section numbers (§1–§9, Appendices A–C) were already the stable identifiers, so the parts were a packaging choice, not a structural one. reports/tsi/tsi-report.md is now the whole report. Parts are interleaved back into section order — §1, §2–§5, §6, §7–§8, §9 + appendices — which is NOT concatenation order: Part 1 carried §1, §7 and §8, so appending files in sequence would have put §7–§8 ahead of §2. Every cross-file link collapses to an internal anchor; all 47 anchors resolve, all 37 figure embeds resolve, and no line of prose was lost (verified by diffing normalised content lines with link targets stripped — 0 lost, additions are the new header and table of contents). Coherence fixes the merge exposed, all artefacts of the split: - The roadmap paragraph described "four parts (see the index)" and is now a section-order roadmap, with its circular self-link to §1 dropped. - §7's figure-location note pointed readers at "the other parts". It now names the actual sections, and it was also WRONG about three figures: fig17/fig18/fig21 are in Appendix C and figB1/figB2 in Appendix B, not §9. It had also never been updated for fig30–fig35. - §9's "throughout this part" is now "throughout". README.md becomes a proper index — a section table pointing into the one document — rather than a list of four files. scripts/split_report.py is deleted: a one-time migration that produced the split, now both obsolete and pointing the wrong way. scripts/build_html.py was already broken before this change — it still read the report from tsi-sim-pernode/, where the files stopped living when they moved to reports/tsi/. Retargeted at reports/tsi/ and the single document; verified end-to-end (0 broken internal anchors, 0 unrewritten .md links, 37 images in the rendered HTML). Its output is now gitignored, as its docstring always claimed it was. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 3 + reports/tsi/README.md | 28 +- ...i-report-1-overview-and-recommendations.md | 191 ---- .../tsi/tsi-report-2-accuracy-and-design.md | 375 ------- .../tsi-report-3-robustness-and-incentives.md | 246 ----- ...report-4-reproducibility-and-appendices.md | 146 --- reports/tsi/tsi-report.md | 943 ++++++++++++++++++ .../tsi/tsi-sim-pernode/scripts/build_html.py | 26 +- .../tsi-sim-pernode/scripts/split_report.py | 214 ---- 9 files changed, 977 insertions(+), 1195 deletions(-) delete mode 100644 reports/tsi/tsi-report-1-overview-and-recommendations.md delete mode 100644 reports/tsi/tsi-report-2-accuracy-and-design.md delete mode 100644 reports/tsi/tsi-report-3-robustness-and-incentives.md delete mode 100644 reports/tsi/tsi-report-4-reproducibility-and-appendices.md create mode 100644 reports/tsi/tsi-report.md delete mode 100644 tools/simulators/tsi/tsi-sim-pernode/scripts/split_report.py diff --git a/.gitignore b/.gitignore index 559613b..bc74d7e 100644 --- a/.gitignore +++ b/.gitignore @@ -224,3 +224,6 @@ __marimo__/ # External upstream clones vendored for benchmarking (own .git, not our history) tools/benchmarks/original/ + +# Rendered report HTML — a build artifact of scripts/build_html.py; markdown is the source +reports/**/*.html diff --git a/reports/tsi/README.md b/reports/tsi/README.md index fb9afd5..2a29add 100644 --- a/reports/tsi/README.md +++ b/reports/tsi/README.md @@ -2,20 +2,30 @@ *Per-node network simulation of Cryptarchia Total Stake Inference (TSI). Simulator: [`tsi-sim-pernode`](../../tools/simulators/tsi/tsi-sim-pernode). All runs at the true security parameter **k = 2160** unless noted; latency is in slots and **1 slot = 1 s**.* -This report selects and justifies the TSI parameters for Cryptarchia from a per-node network simulation. It is split into four cohesive parts; section numbers (§1–§9, A–C) are stable identifiers preserved across the set. +This report selects and justifies the TSI parameters for Cryptarchia from a per-node network simulation. The whole report is one document — **[tsi-report.md](tsi-report.md)** — and section numbers (§1–§9, Appendices A–C) are stable identifiers referenced from the simulator and from spec discussion. -> **Uncle references.** The model analysed throughout is the **countable** one: counting-only references, deduplicated by slot, drawn from first-fork blocks only, within a window derived as `w_u = W_abs/f`. An **unrestricted** baseline — any orphan in the window at any fork depth — is measured alongside it for comparison. The two are indistinguishable in the design regime `ρ < 1` and diverge only under overload. See the model note at the top of [Part 1](tsi-report-1-overview-and-recommendations.md), the mechanism in [§2.1](tsi-report-2-accuracy-and-design.md#s2-1), the comparison in [§3.2](tsi-report-2-accuracy-and-design.md#s3-2)–[§3.2a](tsi-report-2-accuracy-and-design.md#s3-2a), and the reproduction notes in [§9](tsi-report-4-reproducibility-and-appendices.md#s9). +> **Uncle references.** The model analysed throughout is the **countable** one: counting-only references, deduplicated by slot, drawn from first-fork blocks only, within a window derived as `w_u = W_abs/f`. An **unrestricted** baseline — any orphan in the window at any fork depth — is measured alongside it for comparison. The two are indistinguishable in the design regime `ρ < 1` and diverge only under overload. See the model note at the top of the [report](tsi-report.md), the mechanism in [§2.1](tsi-report.md#s2-1), the comparison in [§3.2](tsi-report.md#s3-2)–[§3.2a](tsi-report.md#s3-2a), and the reproduction notes in [§9](tsi-report.md#s9). -## Parts +## Contents -1. **[Overview and recommendations](tsi-report-1-overview-and-recommendations.md)** — the executive summary, the per-knob parameter reference (§7), and the safest selection with residual risks and the recommendation-vs-spec deltas (§8). -2. **[Accuracy and design](tsi-report-2-accuracy-and-design.md)** — the model and counting rule (§2), the seven findings and their evidence (§3), the design equations and selection algorithm (§4), and the caveats and regime of validity (§5). -3. **[Robustness and incentives](tsi-report-3-robustness-and-incentives.md)** — jitter, grinding, withholding, selfish mining, the reward design, fork/reorg depth, and organic churn (§6). -4. **[Reproducibility and appendices](tsi-report-4-reproducibility-and-appendices.md)** — how to re-run every study (§9), the residual f-rounding offset (App A), the per-epoch noise floor (App B), and consensus detail (App C). +**[Read the report →](tsi-report.md)** + +| § | what it covers | +|---|---| +| [§1](tsi-report.md#s1) | executive summary — the problem, the findings, the recommendation | +| [§2](tsi-report.md#s2) | the model, the measurement convention, and the counting rule | +| [§3](tsi-report.md#s3) | the findings and their evidence, including the high-precision design band ([§3.2a](tsi-report.md#s3-2a)) | +| [§4](tsi-report.md#s4) | design equations and the parameter-selection algorithm | +| [§5](tsi-report.md#s5) | caveats and regime of validity | +| [§6](tsi-report.md#s6) | robustness — jitter, grinding, withholding, selfish mining, rewards, reorg depth, churn | +| [§7](tsi-report.md#s7) | parameter reference — what each knob does | +| [§8](tsi-report.md#s8) | the safest selection, residual risks, and the recommendation-vs-spec deltas | +| [§9](tsi-report.md#s9) | reproducibility — how to re-run every study | +| [A](tsi-report.md#sA) · [B](tsi-report.md#sB) · [C](tsi-report.md#sC) | the residual `f`-rounding offset · the per-epoch noise floor · consensus detail | ## Headline recommendation -Cryptarchia baseline f = 1/30. Two design choices are foundational: count uncles **per occupied slot**, not per block — the density-bug fix that lands the estimate at exactly `D` ([§2.1](tsi-report-2-accuracy-and-design.md#s2-1), [§8.5](tsi-report-1-overview-and-recommendations.md#s8-5)) — and make genesis `D̂` **a single protocol constant, identical at every node**, never client-configurable, since a per-node divergence is never self-corrected ([§8.1](tsi-report-1-overview-and-recommendations.md#s8-1) row 7). The settings: security `k = 2160`, uncle window `W = 300` slots, uncle cap `U ≥ ⌈ρ⌉ + 1` (2 at the Blend target; the protocol's `MAX_UNCLES = 4` sits safely above it), learning rate `β = 1`, on-chain `f` at 10⁻⁶ precision, peering degree ≥ 6 at scale, soft uncle rewards with `w_u + w_n < 1`, and operate at load `ρ = f·D_vis < 1`. The full recommended-configuration table and rationale are in **[Part 1 →](tsi-report-1-overview-and-recommendations.md)**. +Cryptarchia baseline f = 1/30. Two design choices are foundational: count uncles **per occupied slot**, not per block — the density-bug fix that lands the estimate at exactly `D` ([§2.1](tsi-report.md#s2-1), [§8.5](tsi-report.md#s8-5)) — and make genesis `D̂` **a single protocol constant, identical at every node**, never client-configurable, since a per-node divergence is never self-corrected ([§8.1](tsi-report.md#s8-1) row 7). The settings: security `k = 2160`, uncle window `W = 300` slots, uncle cap `U ≥ ⌈ρ⌉ + 1` (2 at the Blend target; the protocol's `MAX_UNCLES = 4` sits safely above it), learning rate `β = 1`, on-chain `f` at 10⁻⁶ precision, peering degree ≥ 6 at scale, soft uncle rewards with `w_u + w_n < 1`, and operate at load `ρ = f·D_vis < 1`. The full recommended-configuration table and rationale are in **[§8 →](tsi-report.md#s8)**. ## Figures @@ -23,4 +33,4 @@ Figures are embedded from [`report-figures/`](report-figures) via relative links ## Reproducing the results -The simulation code, configs, and run data live in [`tools/simulators/tsi/tsi-sim-pernode`](../../tools/simulators/tsi/tsi-sim-pernode). Every study's exact command is listed in [Part 4 — Reproducibility (§9)](tsi-report-4-reproducibility-and-appendices.md). In short, from the simulator directory: `make install`, then `make ` to run a sweep (results land under `runs/_