R2IL intake arm: plan, implementation spec, and ruff_r2il crate (PR 1)

[AdaWorldAPI]

Summary

PR 1 of the R2IL behavioral-IR arc: Ruff gains a typed intake arm for r2sleigh's R2IL/SSA — no JSON, no NDJSON, no display-string parsing — entering through the same ore → furnace → slag discipline the existing ruff_*_spo frontends use, rather than being forced into the closed SPO Predicate vocabulary.

~9.9k lines, but only ~8.3k are the new crate and 1.5k are the two design docs. The remaining files are a pre-existing CI repair (see §3) plus a second repair round (see §4). Read in this order and the diff should not need reading at all:

📖 Read these two documents first — they are the review surface

Document	What it answers
.claude/plans/r2il-behavioral-ir-v1.md (407 lines)	Why. The three-repo Phase Zero audit (ruff frontends / r2sleigh's typed surface / lance-graph V3 ABI), the intake-arm pivot, the facet-as-drill-key ruling, the three-backend substrate ruling, and the PR ladder.
.claude/plans/r2il-behavioral-ir-v1-impl-spec.md (1071 lines)	What. Per-module spec written against verified upstream signatures, with every test named and its falsifier stated before it was written.

The crate's own module docs carry the same reasoning inline, so cargo doc is a third entry point.

1. The new crate — crates/ruff_r2il (13 files, 8,278 lines)

Workspace-excluded (its own workspace root): it path-deps the r2sleigh sibling checkout, so exclusion keeps ruff's workspace and Cargo.lock sibling-free. Build with --manifest-path crates/ruff_r2il/Cargo.toml.

Module	Stage	Role
behavior.rs	1 — ore carrier	FunctionBehavior over one SsaArtifact. Lossless, zero-copy, names r2sleigh's decomposition; invents no ontology.
ore.rs	2 — enumeration	Deterministic typed fact rows; operand coordinates from the typed source Varnodes via a verified op-site join (mismatch ⇒ JoinFailure, never silent misattribution).
furnace.rs	3 — the melt	Flat, facet-addressed FlatFact rows. Cardinality is more rows, never nesting.
slag.rs	3b — residual ledger	Addressed residuals, FNV-1a shape grouping, and no catch-all variant — no Other, no Opaque.
convention.rs	config	Longest-prefix-wins radix tree over varnode identity space; bootstraps from ArchSpec (read, never retyped).
facet.rs	drill key	16-byte V3-shaped VarnodeFacet; SpaceId::Custom overflow fails typed at config-key time, never truncates.
vocab.rs	4 — codebook	Order-independent interning; feeds lance-graph's ogar_codebook read-only.

Plus tests/lossless_fixtures.rs (981 lines, 12 tests) and two lift-gated examples (corpus profiler, six-artifact harvest with pre-registered B1/B2/B3 bars).

Invariants: harvested = classified + residual, dropped == 0 by construction. Stressors (AtomicCAS, CallOther, Multiequal, StoreGuarded, SpaceId::Custom) must land in named, addressed slag under pass 1 — the ledger naming them is the acceptance criterion. SPO stays an optional lossy projection, never the behavioral truth.

2. Changelog

Design (2) — 404b748 plan + impl spec + workspace exclusion · 90b709a typed-library-seam, native-address provenance, conservation-as-product-property, transcode-as-projection.

Crate, one commit per module (8) — 700faed facet · bd1b096 manifest/module-map/ore-carrier · 2ad6f7f slag · 2138c82 convention · 13cd5f0 vocab · 6bc3c0b fixtures + profiler · 313f0ca ore (+ instruction_addr anchor) · 0ae1662 harvest · bfd819b furnace.

f70ec9b — three defects the gates caught, fixed at source, not by weakening assertions:

1. Phi and Edge rows produced residuals the proposer could not locate → block-address fallback; only phi inputs stay unaddressed (correct — an SSA join edge is not a varnode occurrence).
2. The FlatFact size guard was an unmeasured <= 64; the real layout is 88 → replaced with an exact measured pin (growth and shrinkage now fail).
3. The widening falsifier encoded a wrong model — an unclassified opcode blocks its whole dependent fan-out (7 rows, not 1), and widening reclassifies only the subset with nothing else blocking it (3). Also: the fixture's Custom(7) lived only on the op's space: field, which is not a varnode, so the config-key falsifier was testing nothing until a varnode was moved into that space.

CI repair, round 1 (5) — see §3.

CI repair, round 2 (7) — see §4.

3. Round 1 — why 49 unrelated files changed

CI was already red on the base branch before this arc; every failure was verified against the parent commit before being touched.

• 82c80be — zip_opt (which carried its own // TODO: option_zip), the vendored release.sh SC2086, an unused ruff_ruby_spo workspace-dep entry, and a doc missing from the mkdocs nav.
• 56cac97 / 60450c6 / a509063 — 117 clippy-1.97 lint sites, previously masked because CI stopped at the first crate failure. Mostly doc_markdown and useless_borrows_in_formatting.
• e579177 / 4c7d73c — the typos hook splits hyphenated words and "corrects" mis-attributed → miss-attributed; closed compounds chosen over an allowlist that would suppress genuine typos repo-wide.
• bb16e26 — markdownlint on this branch's own docs.

4. Round 2 — the typos/mdformat/ruff-format hooks were corrupting data, plus a deep cargo doc cascade

Round 1's e579177 claimed "prose only — no behaviour, no identifiers." That was false, and chasing it open turned into a second repair pass.

97c3c0f — three data values the typos hook silently rewrote in round 1, now fixed at source:

• OpTag::IntSCarry => "int_scarry" (an emitted wire tag for P-code INT_SCARRY, signed carry) had become "int_scary".
• A test fixture identifier app:Aparent was renamed to app:Apparent while the assertion string beside it kept the old spelling — the nav_digest failure on linux/macos in this round's own CI run.
• statistc.h (a file Tesseract genuinely ships under that spelling) became statistic.h, a filename that doesn't exist.

Reproducing the prek job locally caught three more of the same class before they could land: typos read the hex a8ad31e12dbe9f80 in a harvest ledger as a misspelling and dropped a digit, breaking a shape_id join; mdformat collapsed the YAML frontmatter of an agent card into a heading and one run-on paragraph (no frontmatter plugin is configured, so this would have broken every card under .claude/agents/); ruff-format was rewriting golden test input fixtures, changing what the tests exercise. Fixed by excluding vendor/, .claude/, and crates/ruff_python_dto_check/tests/golden/ from the fixer hooks (documented inline in .pre-commit-config.yaml), plus five _typos.toml allowlist entries for identifiers that are correct as spelled (scarry, statistc, oce, tage, in 97c3c0f and 581007b).

80820c1 / bbaebda — the mechanical formatter output over four prose docs the hooks had never reached, split from the repairs above; plus the R2IL staged-codegen guide for the sibling consumer session.

63093fe / eabbd62 / 3747d27 — cargo doc --all --no-deps -D warnings cascade, six crates deep:

cargo doc stops at the first crate that fails, so fixing one crate's rustdoc errors revealed the next crate's — all pre-existing, none introduced by this branch: ruff_python_dto_check (9) → ruff_ruby_spo (20) → ruff_cpp_spo / ruff_python_spo (5) → ruff_spo_address / ruff_sqlalchemy_spo (16) → six more inside ruff_spo_triplet itself, plus 5 more in ruff_cpp_spo under --features libclang (CI's test job runs --all-features). Same mechanical fix throughout: an intra-doc link to a private item becomes a plain code span ([`x`] → `x`); nothing was made pub to satisfy a lint, nothing deleted.

Also closed a real, independently-discovered bug while in ruff_cpp_spo: two examples (harvest_leptonica_scale.rs, harvest_textord.rs) had no [[example]] manifest entry at all, unlike their three siblings — so required-features = ["libclang"] never applied to them, and a bare feature-less cargo test -p ruff_cpp_spo failed to compile them against symbols that only exist under the feature. Confirmed pre-existing (reproduces identically with this branch's other changes stashed out). Added the missing manifest entries; both feature modes build and test clean now. This supersedes the "Known pre-existing, not addressed here" note in an earlier revision of this body — it is addressed.

No auto-fixer was used for any of round 2 either — every fix above was hand-verified by re-running the exact failing command and checking the diff shape (insertions == deletions, zero pub added, nothing deleted) before committing.

Test Plan

All green locally under the repo's pinned 1.97.1:

cargo clippy --workspace --all-targets --all-features -- -D warnings   # 0
cargo fmt --all --check                                                # 0
uvx prek run --all-files --hook-stage manual                           # all hooks pass
RUSTDOCFLAGS="-D warnings" cargo doc --all --no-deps                   # 0 errors
RUSTDOCFLAGS="-D warnings" cargo doc --all --no-deps --all-features    # 0 errors

Crate gates (workspace-excluded, so --manifest-path): fmt --check, clippy --all-targets -- -D warnings with and without --features lift, and cargo test — 43 passing (31 unit + 12 integration).

Workspace-isolation proofs: cargo check -p ruff_graph builds, cargo metadata contains no ruff_r2il, root Cargo.lock untouched.

cargo test -p ruff_cpp_spo now passes with and without --features libclang (round 2 fix — see §4); previously only the --features libclang path was verified.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_35aca636-bad8-4457-ac33-0113511c2091)

[AdaWorldAPI]

CI status note: the three red checks on 404b748 are pre-existing base-branch failures, not introduced by this diff (which touches only Cargo.toml [workspace] exclude + two .claude/plans/*.md files). Verified against the parent commit (= fork main):

• cargo clippy — clippy 1.97's new manual_option_zip lint fires in ruff_annotate_snippets (1) and ruff_python_ast (4), crates this branch does not touch. Needs an upstream-style lint sweep (or a sync from astral-sh/ruff), out of scope for this arc.
• shellcheck — SC2086 (unquoted $LEVEL) in vendor/lsp-types/release.sh lines 10/15; present verbatim at the parent commit.
• cargo shear — ruff_ruby_spo is declared in [workspace.dependencies] with no consuming crate; also present at the parent commit (only crates/ruff_ruby_spo/Cargo.toml itself mentions it).

This PR's own additions (crates/ruff_r2il, workspace-excluded) are gated locally with cargo clippy --all-targets -- -D warnings under the repo's pinned 1.97.1 toolchain, plus workspace-isolation proofs (cargo metadata clean of ruff_r2il, root Cargo.lock untouched). Will re-check these three when the base branch recovers.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_2e520d16-f54a-4f3a-aaec-f2f5578aa8f6)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_f094f3df-9032-47ca-9181-156dacc09a04)