docs(ledger): extract the long residuals into docs/residuals/

[doublegate]

Closes the refactor raised independently by three reviewers across four PRs (#188, #193, #194, #195) and deferred three times — on the grounds that migrating one residual alone would leave the ledger inconsistent about where provenance lives. Done properly now: every residual whose record passed 4,000 characters moves in one pass.

What moved

Residual	Before	After (table row)
R-18	47,811 chars	495
R-13	17,514	554
R-5	13,475	607
R-10	6,407	657
R-19	4,921	537

The table keeps a row for all 23 residuals with classification, current status and a link. It remains the index. Longest remaining row: 3,750 chars.

The harm was demonstrated, not theoretical

A Markdown table row cannot contain a hard line break, so these records grew as single lines of tens of thousands of characters. Unescaped | inside inline code spans then split the row, and markdownlint reported the consequence exactly:

MD056/table-column-count [Expected: 5; Actual: 9; Too many cells, extra data will be missing]

"extra data will be missing" — content at the end of the row, which is where the newest appends land, was being dropped from the rendered table. That was found on #194 and fixed by escaping; this removes the condition that made it possible.

Append-only is preserved

The new files are append-only exactly as the rows were. Superseded claims stay in place and marked ([HISTORICAL BASELINE — SUPERSEDED …], RETRACTED, at the time of writing) rather than being edited away. That matters more than usual here: several of these records exist mainly to hold refuted hypotheses, and a record showing only the conclusion cannot show which measurement overturned which guess.

Verified mechanically, not by eye

The obvious failure mode for a 47 KB text move is silently dropping a paragraph. Before replacing any row, all 20 cells across the five moved residuals were checked to appear verbatim in their new files:

R-5:  4 cells -> 0 missing        R-18: 4 cells -> 0 missing
R-10: 4 cells -> 0 missing        R-19: 4 cells -> 0 missing
R-13: 4 cells -> 0 missing
TOTAL CELLS LOST: 0

(A first pass compared sentence chunks and reported 15 "losses"; every one straddled a cell boundary, where the row had | and the file now has a section heading. Per-cell comparison is the correct check and shows zero loss. Worth recording — a verification that reports false positives is one you stop trusting.)

Gates

cargo fmt --all --check · cargo test --workspace · rustdoc -D warnings · markdownlint — green. Docs only; all link targets verified to exist.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added an index explaining the long-form residual records and their append-only history.
  • Added detailed records for residuals R-5, R-10, R-13, R-18 and R-19.
  • Updated the accuracy ledger with clearer residual statuses and links to full records.
  • Recorded resolved, partially resolved and remaining accuracy issues, including capstone and system-test outcomes.

Walkthrough

The accuracy ledger now links oversized entries to append-only residual records. New records preserve investigation histories for R-5, R-10, R-13, R-18, and R-19, while ledger statuses and supporting R-14 and R-6 text are refreshed.

Changes

Residual documentation

Layer / File(s)	Summary
Ledger index and status updates docs/accuracy-ledger.md	Adds the append-only residual-record convention and updates statuses, links, citations, and resolution details for R-6, R-10, R-13, R-14, R-18, and R-19.
Partial-resolution residual records docs/residuals/R-5.md, docs/residuals/R-10.md, docs/residuals/R-13.md	Adds verbatim append-only records describing investigation histories, implemented slices, remaining scope, and system-test impact.
Capstone and hang residual records docs/residuals/R-18.md, docs/residuals/R-19.md	Documents the R-18 cross-subsystem investigation and the resolved R-19 branch-delay-slot versus exception-vector race.
Residual record index docs/residuals/README.md	Defines the long-form record convention and links the five extracted residual records.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• doublegate/RustyN64#180: Earlier R-18 investigation and capstone status reflected by the expanded residual record.
• doublegate/RustyN64#189: ERET interrupt-attribution fix documented in the R-18 history.
• doublegate/RustyN64#131: Earlier R-19 delay-slot hang investigation superseded by the resolved record.

🚥 Pre-merge checks | ✅ 10

✅ Passed checks (10 passed)

Check name	Status	Explanation
Title check	✅ Passed	Matches Conventional Commits and clearly describes extracting long residual records into docs/residuals/.
Description check	✅ Passed	It is directly about moving oversized residuals into docs/residuals/ and preserving the ledger index.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Oracle Number Is Stated	✅ Passed	PASS — the patch changes only docs/accuracy-ledger.md, so this is a docs-only change exempted by the check.
Docs-As-Spec Sync	✅ Passed	PASS: this PR is docs-only; no crates/rustyn64-{cpu,rsp,rdp,audio,cart,core} files changed, so the docs-as-spec sync rule is not triggered.
Changelog Entry For User-Visible Changes	✅ Passed	PASS: only docs/accuracy-ledger.md and docs/residuals/* changed; CHANGELOG.md’s [Unreleased] is empty, so this is an internal docs refactor.
Measured, Never Tuned	✅ Passed	PASS: the new timing/constant values in R-5/R-6/R-10/R-13 are wiki-cited or oracle-validated in docs/accuracy-ledger.md; no tuned hardware constant is left uncited.
Unsafe Stays Out Of The Chip Crates	✅ Passed	PASS: diff touches only docs/accuracy-ledger.md; no actual unsafe constructs were found in crates, and no forbid(unsafe_code) attributes were removed.

---

_{Comment @coderabbitai help to get the list of available commands.}

[doublegate]

Adjudication — Antigravity review

No blocking issues. The truncation finding is adopted in full, and it was correct on every instance.

Truncated / unclosed summaries — adopted

You caught five real defects, and I verified each:

Row	Damage
R-5	unclosed bold — **[HISTORICAL BASELINE — SUPERSEDED …
R-10	mid-word noise, LO, mid-word small mi, fragment D a before the link
R-13	unclosed bold **persp; and still pointed at "the RESOLUTION at the end of this cell" for text that had moved to another file
R-18	status ended mid-sentence: asserted a **Full record: …**
R-19	mid-word currently in the T

The R-13 one is the worst of them and the one I would not have caught by skimming: a cross-reference that was correct in the original row became a dangling pointer the moment the cell was split, telling the reader to look at the end of a cell whose end no longer exists.

The fix is not better truncation — it is not truncating. I was auto-summarising with a 180-character cut and a sentence-boundary regex that fell back to a hard slice. A summary is written, not chopped. All five stubs are now hand-written complete sentences, and they say more than the truncations did:

• R-18 now states that its own recorded mechanism was wrong — the causes were an ERET interrupt livelock and a PIF reporting four controllers, not the OS-boot runtime the row theorised.
• R-10 now records that noise is deliberately not attempted, because Angrylion fakes it with a shadertoy PRNG rather than modelling hardware — a decision that was buried in the long text.
• R-5 and R-13 state what is resolved versus what remains, rather than opening with a historical-baseline marker mid-tag.

Checked mechanically too: no residual row has unbalanced ** or ` formatting.

Gates re-run: fmt, cargo test --workspace, rustdoc -D warnings, markdownlint — green.

[github-actions]

Antigravity review (Gemini via Ultra)

This PR refactors docs/accuracy-ledger.md by moving five oversized accuracy residual entries (R-5, R-10, R-13, R-18, R-19) into standalone files under docs/residuals/ and linking them from the main table index.

Blocking issues

None found.

Suggestions

• docs/residuals/README.md:3: Backticks inside the link text brackets ([`../accuracy-ledger.md`](../accuracy-ledger.md)) can break link rendering in some Markdown engines; prefer standard formatting ([../accuracy-ledger.md](../accuracy-ledger.md)).
• docs/residuals/R-5.md:3 (and R-10.md, R-13.md, R-18.md, R-19.md header notices): The header quote references ../accuracy-ledger.md as inline code text rather than an active relative link. Linking it back to the parent file makes navigating back from an individual residual document easier.

Nitpicks

• docs/residuals/README.md:105-111: The index table orders entries numerically by ID (R-5, R-10, R-13, R-18, R-19), but in docs/accuracy-ledger.md the entries appear in order of appearance in the primary table (where R-14/R-1/etc. interleave); keeping index ordering consistent across both documents avoids confusion.

_{Automated first-pass review by agy on a self-hosted runner -- not a human review.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/residuals/R-5.md`:
- Line 16: Mark the specified append-only investigation text as historical
without rewriting or deleting it: in docs/residuals/R-5.md lines 16-16 identify
the high-bit-replication statement as superseded by the truncating-conversion
resolution; in docs/residuals/R-10.md lines 12-16 and docs/residuals/R-13.md
lines 12-16 label the descriptions as initial baseline/investigation state; in
docs/residuals/R-18.md lines 12-16 mark the no-video/interrupt theory as
superseded; in docs/residuals/R-18.md line 24 replace “authoritative current
count” for 53 probes with dated historical wording and defer to docs/STATUS.md
as canonical; and in docs/residuals/R-19.md lines 12-16 mark the initial hang
diagnosis as historical.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2d3e6928-2166-4b3c-b33b-b7e33ec2d486

📥 Commits

Reviewing files that changed from the base of the PR and between 5a18d53 and 209ae3c.

📒 Files selected for processing (7)

• docs/accuracy-ledger.md
• docs/residuals/R-10.md
• docs/residuals/R-13.md
• docs/residuals/R-18.md
• docs/residuals/R-19.md
• docs/residuals/R-5.md
• docs/residuals/README.md