section-01: research grounding

Goal

Consolidate the cross-repo prior-art synthesis and the internal Ori audit already gathered into durable, citable grounding for the 8 rules section-02 authors — verified against real source, not paraphrased from memory.

Implementation Sketch

External prior art: rustc, LLVM, Swift, Zig, GCC, Go, V8, Lean4, TypeScript internal tracing/debugging architecture — 14 cross-cutting patterns, each with a supporting citation and a contrasting violator:

#	Pattern	Evidence (compiler + citation)	Contrasting violator
1	Compile-time-elided debug macros	rustc `debug!`/`trace!` elided outside `rust.debug-logging`; LLVM `LLVM_DEBUG()` elided in Release	V8 `--trace-turbo` always compiled in; Go `-m`/`GOSSAFUNC` instrumentation always present
2	Independently-toggleable per-pass/per-query granularity	LLVM `-debug-only=<pass>`; rustc `RUSTC_LOG=[typeck]`; Swift `-sil-print-around=$PASS`; Go `GOSSAFUNC="Func:Pass1,Pass2"`	Zig `--verbose-air`/`--verbose-llvm-ir` — whole-compilation, all-or-nothing
3	Flag/env-var name mechanically tied to the owning module/pass	LLVM `DEBUG_TYPE` macro; rustc `RUSTC_LOG` targets = crate/module paths	GCC dump files ordered by numeric pass index — shifts on pipeline reorder, decoupled from a stable name
4	Orthogonal numeric bisection axis independent of pass naming	LLVM `-opt-bisect-limit=N`	No equivalent in rustc/Go/Swift; Zig issue #13826 is a live user request for exactly this gap
5	Structured, tool-consumable dump format vs plain text	V8 `--trace-turbo` emits per-phase JSON for turbolizer; rustc `-Z self-profile` binary `measureme` format	LLVM `-debug`/`-print-after-all` unstructured free-text; GCC tree/RTL dumps plain text
6	Dedicated per-unit output sink, not interleaved stderr	rustc `-Z dump-mir=all` writes a `mir_dump/` dir, one file per function+pass; Go `GOSSAFUNC` writes a self-contained `ssa.html`	Swift `-sil-print-all`/`-sil-print-function` straight to stdout, needing manual redirection
7	Env-var gating for cross-process/subprocess propagation	`RUSTC_LOG`, `GODEBUG`, `GOSSAFUNC` — env vars survive a build-system wrapper interposing a driver process	LLVM internal flags require explicit `-mllvm`/`-Xllvm` passthrough at each driver layer — a documented silently-dropped-flag source
8	Regression-pinnable dump output via CHECK-style test harness	LLVM `lit`+`FileCheck`; rustc `tests/mir-opt/` with `--bless` regeneration	Swift `-sil-print-*` and V8 `--trace-turbo`/turbolizer — documented interactive/human-consumed, no systematic CHECK-line suite
9	Structured profiler artifact over ad hoc stderr timing	rustc deprecated `-Z time-passes` in favor of `-Z self-profile` (rust-lang/rust#53631) — raw timing prints can’t be aggregated/diffed	—
10	Self-diagnosing failure modes in demand-driven/incremental systems	Swift `-debug-cycles` dumps the request chain; rustc query-cycle backtrace on ICE	—
11	Function/symbol-name filtering independent of pass filtering	Go `GOSSAFUNC=FunctionName`; Swift `-sil-print-function=NAME`; LLVM `-filter-print-funcs=name`	Zig verbose flags dump the entire compilation — unusable on any nontrivial program
12	Centrally registered trace-category inventory vs free-text string matching	Lean4 `registerTraceClass` required before `trace[cls]` is legal — discoverable, typo-proof	rustc `RUSTC_LOG` targets are unvalidated strings — a typo silently matches nothing
13	Eager-argument-evaluation hazard in log macros is a documented trap	rustc-dev-guide explicitly warns enabling a log target executes any expression passed to `debug!`/`trace!`; prescribes `#[instrument]` + `debug!(?field)` lazy capture	rustc’s own historical call sites before the guide’s warning landed
14	`--help`-discoverable flags vs tribal-knowledge internal flags	Zig `--verbose-air`/etc listed directly under `--help`	LLVM’s richest pass-debugging flags invisible to `clang --help`, only via `-mllvm -help-hidden`

Internal audit: compiler_repo/compiler/oric/src/debug_flags.rs (the flags! macro emits name-mirrored pub consts only; compiler_repo/diagnostics/check-debug-flags.sh is the actual enforcement — NOT the macro itself — confirmed by a live run this session: 111 defined flags, 0 stale, 0 orphan, “All checks passed”), dump_orchestrator.rs (the single DumpPhase dump surface), tracing_setup.rs (the ORI_LOG/RUST_LOG filter build), the AIMS ORI_DISABLE_*/ORI_FORCE_* ablation-toggle family (80 of the 111 macro-registered flags; 5/80 carry a toggle-specific negative-pin test), and the ori_patterns (zero tracing:: call sites across 74 files) / ori_parse (12 real call sites, near-zero relative to a multi-hundred-function parser crate) declared dependency gap self-acknowledged in compiler.md’s own Tracing Targets table.

Per-file audit, exact file:line, cross-validated across both /tp-help rounds (codex/agy/opencode) plus the /intel-package dossier’s independent source re-reads:

File:line	Finding	Cross-validated by
`compiler/oric/src/debug_flags.rs:75`	`flags!` macro — emits name-mirrored `pub const`s only; NOT the enforcement mechanism	codex R1 F2 + agy R1 F2 + Step 8B F1 (agy/opencode) + `/intel-package` §2
`compiler/oric/src/debug_flags.rs:1430`	compile-time sync check vs `ori_llvm::verify` — closest existing analog to a “central registry” pattern	`/intel-package` §2 + §10 recon entry point 1
`compiler_repo/diagnostics/check-debug-flags.sh`	the REAL enforcement — live run this session: 111 flags, 0 stale, 0 orphan	codex R1 F2 + opencode Step 8B F1 + `/intel-package` §3D (independently re-ran it)
`compiler/oric/src/dump_orchestrator.rs:19-110`	unified `DumpPhase` surface (`dump_parse`/`dump_typeck`/`dump_arc`/`dump_llvm`)	`/intel-package` §2 (community-781 graph-confirmed as the clean module boundary)
`compiler/ori_llvm/src/codegen/function_compiler/define_phase.rs:34`	a SECOND independent `ORI_DUMP_AFTER_ARC` reader, inside codegen — not in the original audit	`/intel-package` §3.3 (new terrain this pass)
`compiler/oric/src/tracing_setup.rs:24,64`	`init()` (sole call site, `main::real_main:47`) + `build_filter()` — `ORI_LOG`/`RUST_LOG` filter build	codex R1 F7 + agy Step 8B F3 + `/intel-package` §2
`compiler/ori_parse/src/grammar/expr/mod.rs:78`	`trace!(pos=.., kind=..)` — real cheap-field-access call, the allowed contrast for SPEC-67	codex R1 F5
`compiler/ori_parse/src/parser_context.rs:123`	`tracing::debug!(context=.., ..)` — a second real ori_parse call site	opencode R1 F5
`compiler/ori_patterns/Cargo.toml:14`	`tracing.workspace = true`, 0 call sites across 74 files — the COVER-34 Critical exemplar	opencode R1 F3 + `/intel-package` §2 (confirmed by direct grep)
`compiler/ori_parse/Cargo.toml:13`	`tracing.workspace = true`, 12 real call sites — the COVER-34 Major (near-zero) exemplar	`/intel-package` §2 (live count, corrects the original “near-zero” framing to an exact figure)

Cross-repo graph grounding: rustc_const_eval/src/interpret/util.rs:56-75’s EnteredTraceSpan::or_if_tracing_disabled dual-dispatch pattern (verified by direct source read, not solely a graph symbol match — the qualified name is sparse in the embedding index); reference_repos/lang_repos/typescript/src/compiler/checker.ts:22892’s tracing.instant(Phase, eventName, {fields}) structured use-site-event pattern; Zig issue #13826 (“add -fopt-bisect-limit”) corroborating the bisection-axis gap pattern from a live user request; rustc_data_structures::profiling::EVENT_FILTERS_BY_NAME (found via /intel-package’s deeper graph pass, sim 0.764) — a named per-event filter table, a second concrete “structured trace-category inventory” precedent for SPEC-71 beyond Lean4’s registerTraceClass.
/intel-package dossier (content/intel/research-grounding--s-156cd240.intel.md) deepened this grounding and surfaced 4 corrections section-02 MUST absorb before finalizing rule text:
1. SPEC-68’s flagship citation (dump_orchestrator_baseline::ori_dump_after_llvm_pins_llvm_ir_driver_block) is presently RED at HEAD (BUG-04-252, open) — cite the driver’s golden-baseline CONTRACT (real, correct-by-design) as SPEC-68’s grounding, never the current pass/fail state.
2. A SECOND, independent ORI_DUMP_AFTER_ARC reader lives inside ori_llvm codegen (ori_llvm::codegen::function_compiler::define_phase::dump_arc_if_requested, compiler/ori_llvm/src/codegen/function_compiler/define_phase.rs:34) — SPEC-71’s central registry must enumerate BOTH readers of a shared env var, not just the driver-level dump_orchestrator one.
3. debug_flags.rs/check-debug-flags.sh are claimed restructuring territory of the not-started diagnostics-split plan (16 blockers, zero live collision today) — SPEC-71’s rule text must be worded PATTERN-first (enumeration file + external verifier script), never path-first, so it survives that plan’s eventual relocation.
4. Five RESOLVED Ori bugs are stronger, codebase-specific grounding than the cross-repo prior art alone: BUG-07-005 (orphan env vars not registered — the exact gap SPEC-63/COVER-26/SPEC-71 prevent going forward, completed bug plan at bug-tracker/plans/completed/BUG-07-005/), BUG-07-006 (silent ORI_LOG parse-error fallback — the mission’s own “silent drift” framing, precisely), BUG-07-007 (parallel tracing-subscriber init violating One-System-One-Owner), BUG-07-008 (tracing_setup.rs::init() double-init panic), BUG-07-009 (tracing-tree transitive dependency always compiled in regardless of use — the COVER-34 shape one level up, for a transitive crate dep rather than in-crate call sites; worth noting as adjacent precedent even though COVER-34’s current wording targets call-site volume, not transitive deps). SPEC-70 (cycle_recovery_strategy trace-log) has ZERO live Ori anchor — grep across compiler/ for cycle_recovery_strategy/cycle_fn returns nothing — its grounding is entirely forward-looking (SPEC-62’s existing text + rustc’s rust#119321, sitting at the graph’s 100th-percentile pain+controversy score, the single strongest cross-repo corroboration for “loud failure over silent masking” found this session).

Spec References

N/A — this plan touches .claude/rules/ only, not the Ori language spec.

Work Items

Document the 14-pattern external prior-art synthesis (compiler + citation + contrasting violator per pattern) as durable grounding text in this section’s body.
Document the internal Ori audit (debug_flags.rs, dump_orchestrator.rs, diagnostics scripts, tracing crate usage per-crate) with exact file:line citations, cross-validated against the two /tp-help consensus rounds’ independent reviewer citations, as durable grounding text in this section’s body.

Items

Capture the /intel-package dossier’s 4 corrections as explicit, durable, source-verified grounding text this section’s body must carry for section-02 to absorb before finalizing rule text: (1) SPEC-68 must cite the dump_orchestrator baseline driver’s golden-baseline CONTRACT, never the currently-RED BUG-04-252 pass/fail state, as its grounding artifact; (2) SPEC-71’s central registry rule text must enumerate BOTH ORI_DUMP_AFTER_ARC readers (dump_orchestrator AND ori_llvm::codegen::function_compiler::define_phase::dump_arc_if_requested at compiler/ori_llvm/src/codegen/function_compiler/define_phase.rs:34), not just the driver-level one; (3) SPEC-71 must be worded pattern-first (enumeration-file + external-verifier-script shape), never path-first, to survive the not-started diagnostics-split plan’s eventual debug_flags.rs/check-debug-flags.sh relocation; (4) cite the five RESOLVED Ori bugs BUG-07-005, BUG-07-006, BUG-07-007, BUG-07-008, and BUG-07-009 as codebase-specific grounding stronger than cross-repo prior art alone, noting BUG-07-009 as adjacent precedent for COVER-34’s transitive-dependency variant.

Fresh intel (regenerated)

This section is NOT “go write 14 patterns + an internal audit from scratch” — the section body already carries a large, specific, citation-backed synthesis. The graph’s job here is verification and gap-finding, and it found real gaps: the section’s own grounding artifacts are partially LIVE-BROKEN and partially UNCOORDINATED with two other active plans touching the exact same files.

Four decisions this package forces before section-02 (author-and-finalize) writes the 8 rules:

SPEC-68’s flagship citation is currently red. dump_orchestrator_baseline::ori_dump_after_llvm_pins_llvm_ir_driver_block — the exact “diffable golden baseline” pin SPEC-68 cites as the concrete grounding for dump_orchestrator.rs’s unified DumpPhase surface — is tracked as BUG-04-252 (open, medium, sole rust_workspace failure in both 2026-07-06 full test-all runs; confirmed still the cached test-all verdict at current HEAD). SPEC-68’s rule text should cite the driver contract’s INTENDED shape (which is real and correct), not imply the golden baseline is presently green. §4/§9 below.
diagnostics-split (not-started, 8 sections, 16 blockers) claims debug_flags.rs + check-debug-flags.sh as territory it will restructure (Classification+Caller Audit -> Wrapper Migration Mechanics -> Public Repo Automation Cleanup -> Doc Surfaces). It has not started, so zero live collision today — but SPEC-71’s new “central registry, parse-check-verified” rule and any parse-check script it demands should be authored aware that check-debug-flags.sh itself is a named migration target of a separate active plan. §6/§9.
The exact failure modes these 8 rules prevent going forward already happened, five times, and are resolved with real fixes to cite. BUG-07-005 (orphan env vars not registered — exactly what SPEC-63/COVER-26/SPEC-71 target), BUG-07-006 (silent ORI_LOG parse-error fallback swallowing user config), BUG-07-007 (parallel tracing-subscriber init violating One-System-One-Owner), BUG-07-008 (tracing_setup.rs::init() panics on double-init), BUG-07-009 (tracing-tree dep always compiled in regardless of use — the exact COVER-34 shape, but for a transitive crate dependency rather than in-crate call-site volume). These are stronger, more concrete anchors than the cross-repo prior art alone — [JOIN] §4.
rustc’s own community independently corroborates SPEC-70/SPEC-62’s core thesis at the highest pain percentile the graph tracks: rust#119321 “query cycles could be handled more like ICEs” sits at pain_pctile=100.0, controversy_pctile=100.0 — rustc engineers want cycle silence replaced by loud failure, which is precisely SPEC-62’s Critical ban plus SPEC-70’s mandatory trace-log on the one reserved carve-out. §8.

Every terrain symbol these rules govern (ori_patterns zero-call-site claim, ori_parse near-zero claim, the debug_flags.rs/check-debug-flags.sh pairing shape, dump_orchestrator.rs’s DumpPhase unification) was independently re-verified against live source below and confirmed accurate — the section body’s grounding holds up.

DIG DEEPER

python -m scripts.plan_corpus.read plans/tracing-observability-hygiene
scripts/intel-query.sh cypher "MATCH (b:Bug) WHERE b.bug_id='BUG-04-252' RETURN b" --human

(full dossier: research-grounding—s-156cd240.intel.md)