§0 reachability-completeness lens: doc-graph instance as first gating wall (generalize #5433, no fork); see docs/plans/inert-layer-lens.md §8 by gunbai-bot[bot] · Pull Request #5484 · gunb-ai/gunbc

gunbai-bot · 2026-06-21T21:20:10Z

§0 doc-graph reachability-completeness wall (plan §8, generalizes #5433 — no fork)

Implements the doc-graph instance of the reachability-completeness rule (docs/plans/inert-layer-lens.md §8): every declared docs/**/*.md must be reachable from a root, reached via a reflective bind: ref, or deleted; no dangling ](x.md) link. Both halves fail-closed.

This is the doc substrate of the same one rule the #5433 inert-lens backstop runs over the lens substrate (DESIGN §3 single authority). It is not a fork: the reachability primitive (reachable_set) is the same seed→transitive-closure BFS shape as cli_run::inert_lens_modules, re-expressed over doc nodes — and cli_run.rs (the #5433 closure) is untouched.

What's here

src/v1/stage0/src/doc_reachability_project.rs (new, self-contained): live-tree census — walks docs/**/*.md, BFS from per-kind roots (ROADMAP/DESIGN for plan docs; docs/runbooks/README.md for runbooks) over markdown links + .dag-comment bind: reflective edges; reports orphan + dangling counts.
Two additive census builtins (doc_graph_orphan_count / doc_graph_dangling_link_count) — the same corpus-gate seam as extdeps_external_authority_live_clean_tree_holds / fact_cardinality_* (new string-keyed arms only in v1_interpreter.rs dispatch + v1_compiler_infer_method.rs registry; not a load-bearing / pipeline edit — manager-approved).
dsl/test/claim/doc_reachability_witness_test.dag: floor-discovered test fn witness, both verdicts green-by-execution, RED-on-revert (verified: drop an inbound link → orphan RED; break a link → dangling RED). RED/GREEN synthetic-graph controls live in the project module unit tests.

Why host-fed (premise correction, plan §8/§9 updated in this PR)

The §8 "no host bridges" claim holds only for the dangling half. The orphan half is universe ∖ reachable, and the universe needs filesystem enumeration — no list-dir host effect exists in .dag today (std/filesystem is Read/Write only). DISSOLUTION TRIGGER: folds into pure .dag on gunbc#5364 (the Tier-2 note). The dangling half alone is pure-.dag-expressible.

Ship green-on-main

The wall forces the discipline. To land it clean I added the 5 missing inbound links (construction-justification, ci-merge-freshness, compile-clean-forcecheck, m4-hermetic-corpus, m5-fixture-store) + a docs/runbooks/README.md index root linking the bmc runbook. Live tree now: 22 docs / 22 reachable / 0 orphans / 0 dangling.

Verification

cargo test -p v1-compiler --lib doc_reachability → 8/8 pass (incl. live-tree-clean + orphan/dangling RED controls).
Witness through the interpreter: PASS doc_graph_has_no_orphan_docs, PASS doc_graph_has_no_dangling_links; both FAIL on revert.

🤖 Generated with Claude Code

…ating wa

… a root, rostered, or deleted (#5484) The doc substrate of the one reachability rule the #5433 inert-lens backstop runs over the lens substrate (DESIGN §3 single authority; plan §8 one-rule-N-substrates). NOT a fork: reachable_set is the same seed→transitive-closure BFS shape as cli_run::inert_lens_modules, re-expressed over doc nodes — and cli_run.rs (the #5433 closure) is untouched. THE RULE: every docs/**/*.md must be reachable from a root (ROADMAP/DESIGN for plan docs; docs/runbooks/README.md for runbooks), reached via a reflective .dag-comment bind: ref, or deleted; no dangling ](x.md) link. Both halves FAIL-CLOSED. - doc_reachability_project.rs (NEW, self-contained): live-tree census — walks docs/**/*.md, BFS from per-kind roots over markdown links + bind: reflective edges; reports orphan + dangling counts. Same additive corpus-gate builtin seam as extdeps_external_authority_live_clean_tree_holds / fact_cardinality_* (NOT a load-bearing / pipeline edit; manager-approved). - doc_graph_orphan_count / doc_graph_dangling_link_count builtins (additive arms in v1_interpreter.rs dispatch + v1_compiler_infer_method.rs registry only). - doc_reachability_witness_test.dag: floor-discovered test fn witness; both verdicts green by execution, RED on revert (proven: remove an inbound link → orphan RED; break a link → dangling RED). RED/GREEN synthetic-graph controls in the project module unit tests. DISSOLUTION TRIGGER: the orphan half needs filesystem enumeration (no list-dir .dag host effect yet); folds into pure .dag on gunbc#5364. The dangling half alone is already pure-.dag-expressible. Ship GREEN-on-main: added the 5 missing inbound links (construction-justification, ci-merge-freshness, compile-clean-forcecheck, m4-hermetic-corpus, m5-fixture-store) + a docs/runbooks/README.md index root linking the bmc runbook. Live tree now 22 docs / 22 reachable / 0 orphans / 0 dangling. Plan §8/§9 premise corrected (the no-host-bridge claim holds only for the dangling half). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ating wa

# Conflicts: # ROADMAP.md

gunbai-bot · 2026-06-21T22:12:21Z

Thanks — re the build_doc_graph_report() re-walk: confirmed valid. Each doc_graph_* builtin rebuilds the report independently, and two of the three witnesses (orphan, dangling) each trigger a full dag_comment_bind_doc_refs() walk of dsl/+src/. So it's ~2 full-corpus .dag reads per floor run.

Holding off on a fix here, deliberately:

Negligible in practice — a few thousand small-file reads on the 128-core CI hosts is sub-second against a ~30-min floor; it's not on the cost dial.
Self-dissolving — it disappears with the Tier-2 fold (gunbc#5364), exactly as noted.
Head-freeze discipline — the PR is at 2 claude approvals and awaiting a distinct second provider on the current head; another push would re-fire reviews and restart CI for a cosmetic, which trades a real merge delay for a sub-second gain.

If a maintainer would rather see it tightened now, it's a trivial memoize (compute the report once via a OnceLock / single shared call) — happy to do it in this PR on request, or as a one-line follow-up. Defaulting to defer to keep the head stable.

— sent from nimble-moth-677

…5484 interactions) The full run-all enumeration (761 pass / 2 fail / 89 ignored, 0 infra) surfaced two more deterministic reds beyond the wall-clock timing test — both pre-existing on origin/main, hidden by the old 3-test allowlist, untouched by this PR: - source_root_ingest_manifest_host_test::manifest_entry_admission_qualified_name_is_well_formed: #5473 source_root admission has an absolute-vs-relative contradiction (abs path rejected by admission; relative path fails the file-existence check) — proven by execution. Real #5473 API bug; routed to the source_root-tagging owner. - wet_hermetic_equivalence_test::wet_hermetic_scaffold_roster_outcomes_agree: whole-tree mock-corpus precompute can't resolve #5484's doc_reachability_witness_test.dag (doc_graph_* fns not in scope); routed to the doc-graph reachability-lens owner. Surgical #[ignore=failing] with routed reasons (bucket=source-root-ingest-admission / doc-graph-wholetree-resolve). Reason-based completeness lens covers them. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…lter allowlist (29 of 792 green tests) → run-all-unless-#[ignore]d-with-written-reason; add CI-coverage-completeness so a new test is covered by default (fail-closed); measure CI-time impact before committing the full set (#5427) * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * Widen rust gate: declare merge-landed test (lens caught it) + flag one pre-existing fixture red The coverage-completeness lens (this PR's residue) fired on its first real input after merging main: resolve_typed_cache_equivalence_test.rs landed via #5071 but was never declared in lib.rs, so it would silently not run — exactly the gap the lens exists to close (fail-closed, working as designed). Declared it. dag_emit_from_resolved_matches_compile_sources_for_v4_slice reads a removed fixture (fixtures/v2-mvp1, absent from the tree and every git ref) — a pre-existing red hidden by the old 3-filter allowlist, surfaced by the widening. Flagged with a written #[ignore] reason (FLAG-DON'T-FIX); the lens keeps the excuse reviewable. The ~20 interp_recorded_fixture/dry_run local failures were a build-ordering artifact (claim_batch bin not built locally); they pass once the floor's release --bins build is present, so they are NOT ignored (ignoring them would have been a fail-open). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Mark v4_slice ignore as draining-worklist (delete-or-restore), not permanent Parent note: a test whose fixture is gone from every git ref is DEAD — it can never pass, so a permanent ignore would calcify a coverage hole. Sharpened the reason to name the resolution (delete the dead parity receipt OR restore/retarget the fixture at a live v2 source set) and the owner routing (v2 emit slice, via bright-stag), so the completeness lens keeps it visible as work-to-drain. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Fix completeness-lens false-positive on multi-line #[ignore] reasons My own lens (every_ignore_carries_a_written_reason) went RED on the v4_slice ignore I'd just added: the detector required the closing quote on the same line as #[ignore = "..."], so a long reason wrapped with \ line-continuation left the opening line with an unterminated string and was misread as reasonless — a false-positive that fails-closed on legitimately-reasoned input. Detector now recognizes a multi-line reason: opening quote + non-empty content (sans a trailing \ continuation) is reasoned even when the string closes on a later line; an opener with no content before the break is still empty → flagged. Added detector_accepts_a_multiline_reason as the discriminating control (both the valid wrap and the empty-multiline edge), fed through the same authority. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Flag the 16 execution-confirmed pre-existing reds the widening surfaces (#[ignore=failing]) The widened gate runs the self_gen8 + census families that the old 3-filter allowlist never ran. warm-ram's opt-level run listed 32 candidates; running them to completion (--no-fail-fast, claim_batch built) confirms only 16 actually FAIL — the other 16 self_gen8 PASS (e.g. kernel_type_import). Ignoring warm-ram's superset would have excluded 16 GREEN tests (fail-open); only the execution- confirmed failures are flagged. • ownership_stage0_census (1): clone-census ratchet RED on main (non-emit .clone() 21540 > 20200+202, ~1138 over) — inert under the old allowlist while the seed drifted UP against "Rust shrinks toward zero". Do NOT bump the cap (project spirit); route to a census/substrate-migration owner. • self_gen8_* (15): pre-existing self-host emit regression (parametric-alias-RHS / reexported-type-import module resolution); route to the v2 self-host Route-A owner. All draining-worklist, not permanent; the completeness lens keeps each reason visible and reviewable. fmt-clean (rust gate runs fmt --check); parse.rs picked up a pre-existing fmt fix from the earlier ignore conversion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Merge origin/main (ac9a7e7) — resolve pipeline.rs: accept main's deletion of dead v4_slice test main moved again (#5449 etc.) after my first sync. Conflict in pipeline.rs: main DELETED dag_emit_from_resolved_matches_compile_sources_for_v4_slice (the dead parity receipt reading the removed fixtures/v2-mvp1) — exactly the delete-or-restore resolution I'd flagged and routed. Accepted main's deletion; my interim #[ignore] on it is now moot and gone. The 16 self_gen8/census failing-ignores stay intact; completeness lens green (no undeclared test file from the merge); crate compiles. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * Cluster A construction-fix (v2_layer_roots single authority) + cluster B ignore-with-reason; fix doc-lazy-continuation 27 reds surfaced by the run-all widening: - 14 fixed-by-construction: under-scoped v2_source_roots()=[src/v2] dropped dsl, so v2-core's extdeps.communication.medium import was unresolvable. Funnel the 4 files' local copies through one helpers::v2_layer_roots()=[src/v2,dsl] authority (mirrors gunbc.ci_layer_roots; §6 dissolution marker to derive from the .dag fact later). - 13 pre-existing emit/inference reds: #[ignore=failing] with written symptom + bucket (emit/inference/lang-go/lang-python), routed as follow-ups. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * #5427: ignore 2 more pre-existing reds the widening surfaced (#5473 + #5484 interactions) The full run-all enumeration (761 pass / 2 fail / 89 ignored, 0 infra) surfaced two more deterministic reds beyond the wall-clock timing test — both pre-existing on origin/main, hidden by the old 3-test allowlist, untouched by this PR: - source_root_ingest_manifest_host_test::manifest_entry_admission_qualified_name_is_well_formed: #5473 source_root admission has an absolute-vs-relative contradiction (abs path rejected by admission; relative path fails the file-existence check) — proven by execution. Real #5473 API bug; routed to the source_root-tagging owner. - wet_hermetic_equivalence_test::wet_hermetic_scaffold_roster_outcomes_agree: whole-tree mock-corpus precompute can't resolve #5484's doc_reachability_witness_test.dag (doc_graph_* fns not in scope); routed to the doc-graph reachability-lens owner. Surgical #[ignore=failing] with routed reasons (bucket=source-root-ingest-admission / doc-graph-wholetree-resolve). Reason-based completeness lens covers them. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * #5427: cite PR #5504 (RED#1 heal-PR) in the source-root admission ignore reason #5504 (still-deer-248's de-fork-lane fix) grounds absolute --source-root via repo_relative_dag_path, fixing the abs-vs-rel admission contradiction behind the #[ignore]'d manifest_entry_admission test. #5504 is up but not yet merged, so the interim ignore stays; reason now names #5504 as the heal-PR + un-ignore trigger. When #5504 merges, a freshness-merge heals RED#1 and the ignore drops -> zero ignores. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * #5427: route rust gate through the cargo.Build model (§3), drop hand-typed argv strings run_gates() now calls the modeled extdeps.cargo_build ops — cargo.Build.Fmt(["--all","--check"]), Clippy(["--all-targets"],["-D","warnings"]), Test(["-p","v1-compiler-tests"]) — so the cargo shell-transport argv is the single authority, not a hand-typed command String. Removes the now-dead ci_rust_gate_{fmt,clippy,test}_command() String fns from ci_spec (they were §3 nicknames for cargo's already-modeled interface; tools/build.dag uses the same ops). Coverage-by-construction unchanged (run-all-except-#[ignore]d; completeness lens is the residue). EAGAIN cold-retry is transport resilience the cargo model can't yet express (env not wired to the shell transport); it relocates to the CI workflow step that runs the gate (follow-up: rust_tests job). Validated by execution: floor_effect_gate_witness rust_monolith_gate_passes resolves 78 sources and dispatches all three modeled cargo commands. Fixes the partial-snapshot break in 565a116. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Resolve merge conflict markers in rust gate cargo-modeling (ac0b732) The auto-committer captured the merge with unresolved <<<<<<< markers in rust_gates_ci.dag and ci_spec.dag. Resolution keeps the cargo.Build model routing (Task 1) over origin/main's old shell-string version (which still carried the narrow 3-filter ci_rust_gate_test_command -- exactly what this work inverts). No code change beyond marker removal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * WIP: Widen the rust gate by construction (§1): invert the hand-picked 3-filte * Resolve merge conflict in cargo_build.dag; conform new .dag files to comment-ban The auto-committer pushed an unresolved-conflict state (<<<<<<< markers in cargo_build.dag:3,8,9) which fails to parse — fixes the BLOCKING review and the red dsl_compile_clean_gate. main's comment-ban sweep (#5537/#5543/#5539) left dsl/std, dsl/extdeps, dsl/gunbc, dsl/tools, src/v2/test/claim comment-free; this PR's new/rewritten files in those dirs re-introduced comments. Strip them to conform (code unchanged) so we match already-merged state and avoid a future re-sweep. ci.yml emit is byte-identical (comments don't affect output); drift gate green, ci_spec_witnesses green, rust gate + floor_effect_gate_witness resolve clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Fix stale source-audit literal: compile.dag gate predicate (run-all surfaced) The run-all widening (#5427) surfaced source_audit::compile_gate_keeps_infer_errors_blocking_in_stage0, red because main refactored compile.dag's emission gate from is_error_diagnostic to is_resolved_pipeline_typecheck_blocking (discovery-corpus advisory typecheck) without updating this brittle string-audit literal. The audit never ran under the 3-filter allowlist, so the drift went unseen — exactly the class this widening exists to catch. Intent is unchanged (emission is gated on type errors); update the literal to the current predicate so the audit stays live and green. Fix, not #[ignore]: a stale literal is cheaply correctable, not deep work to route. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Resolve .rs merge conflicts: keep #[ignore=reason] set, conform to .rs comment-ban The auto-committer committed an unresolved merge (3052ecd, markers in 5 test .rs files) bringing main's .rs comment-ban sweep (#5544). Resolution: restore my pre-merge versions (preserving every #[ignore = "<reason>"] — the single authority my coverage-completeness lens requires; main's bare #[ignore] would red that lens) then strip full-line // comments to conform to the ban. Code unchanged; 17 self_gen8 + diagnostics reasoned ignores intact; zero reasonless #[ignore] introduced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Re-delete orphan profiling scaffold the merge resurrected (my own lens caught it) body_producer_infer_profile_test.rs is a manual timing-profiling scaffold (std::time::Instant, profile_* fns, bare #[ignore], never declared in lib.rs). My widening deliberately deleted it (26beeee); the auto-committer's merge (3052ecd) left main's copy in the tree via the unresolved deleted-in-HEAD/ modified-in-main conflict. The new coverage-completeness lens correctly fired on it twice — orphan file (every_test_file_is_declared_in_lib) + bare reasonless #[ignore] (every_ignore_carries_a_written_reason) — a live proof the lens has teeth. Re-delete to honor the original deletion; both lenses green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Flag contention-flaky wet/hermetic equivalence test (run-all surfaced) wet_hermetic_scaffold_roster_outcomes_agree passes isolated (~110s) but fails under the 766-test parallel load (~335s). nextest process-isolates each test, so this is resource/timing contention on the wet-execution path, not a logic bug — a non-deterministic test can't gate a merge (§5 fail-open-by-noise). Pre-existing (#5276), never run under the old 3-filter allowlist. #[ignore=reason] + route to the wet==hermetic / hermetic-testing owner; the coverage lens keeps it visible. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * cargo fmt: collapse blank lines left by .rs comment-strip The comment-strip in f05415d left double-blank-lines where comments had been; cargo fmt --all --check rejected them (the rust gate's Fmt op would red). Pure blank-line removal (105 lines), zero code change, all #[ignore]s intact. Also addresses the blank-line noise the 19:42 review flagged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Brian Searls <briansrls@gunb.ai> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

briansrls and others added 2 commits June 21, 2026 21:20

WIP: §0 reachability-completeness lens: doc-graph instance as first g…

e9facc1

…ating wa

gunbai-bot Bot marked this pull request as ready for review June 21, 2026 21:30

briansrls added 2 commits June 21, 2026 21:41

WIP: §0 reachability-completeness lens: doc-graph instance as first g…

eb031ab

…ating wa

Merge remote-tracking branch 'origin/main' into session/nimble-moth-677

28362d7

# Conflicts: # ROADMAP.md

briansrls merged commit d7527fe into main Jun 21, 2026
1 check passed

briansrls deleted the session/nimble-moth-677 branch June 21, 2026 22:42

gunbai-bot Bot mentioned this pull request Jun 22, 2026

plan: scope the axiom + syllogism lens — argument as the fourth reachability substrate (SCOPE-ONLY) #5521

Merged

Navigation Menu

Repository navigation

§0 reachability-completeness lens: doc-graph instance as first gating wall (generalize #5433, no fork); see docs/plans/inert-layer-lens.md §8 - #5484

§0 reachability-completeness lens: doc-graph instance as first gating wall (generalize #5433, no fork); see docs/plans/inert-layer-lens.md §8#5484
briansrls merged 4 commits into
mainfrom
session/nimble-moth-677

gunbai-bot Bot commented Jun 21, 2026 •

edited

Loading

Uh oh!

gunbai-bot Bot commented Jun 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

gunbai-bot Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

§0 doc-graph reachability-completeness wall (plan §8, generalizes #5433 — no fork)

What's here

Why host-fed (premise correction, plan §8/§9 updated in this PR)

Ship green-on-main

Verification

Uh oh!

gunbai-bot Bot commented Jun 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gunbai-bot Bot commented Jun 21, 2026 •

edited

Loading