Hygiene: delete the dead-citation and arch upward-import gates, keep the tracker cleanup

[Japabu]

Owner ruling: this repository carries too much code that only polices. Two
gates this work had built are not landed; what lands is the tracker cleanup,
the CLAUDE.md pointer edits, the crate descriptions with the gate that keeps
them, one git ls-files helper, and the kernel's arch layer holding no
re-export of a name that lives above it.

Not landed

• The dead-citation gate (src/citations.rs: a scanner over every issue
  file and CLAUDE.md for repository paths git does not track). Nothing in the
  tree refers to it.
• The arch upward-import gate (ARCH_REACHES_UP and its scan in
  src/sourcegate.rs), with the path-resolving generalisation of
  arch_module_lines it needed (spelled_paths, Code, Spelled, a
  char-literal branch in code_only). src/sourcegate.rs is main's but for
  the tracked_files calls below, and no redlist row, workflow or test names
  either gate.

Kept

• The arch-rules scan (ARCH_RULES: assembly, core::arch and
  target_arch only in each architecture's own module), unchanged from main.
• Tracker cleanup. Every dead path citation in issues/ and the
  CLAUDE.md files re-pointed where the file went, written as
  <rev>^:<path> where it was deleted, or prefixed with the fork repository
  it lives in. Duplicates merged: the two sun_len tap-socket files into
  issues/build/a-lane-s-tap-socket-path-outgrows-sun-len-on-the-dev-host.md,
  the two blocking_read_window files into
  issues/build/blocking-read-window-reds-beside-other-guests.md, and
  issues/boot-media/log-flush-retry-two-older-failure-modes-with-no-home.md
  into issues/filesystem/log-flush-retry-deadman-arm.md, carrying main's
  "disabled with a src/redlist.rs row" wording into its exit condition.
  issues/build/issue-files-cite-paths-that-moved.md is closed. Frontmatter:
  toyos-dns-decodes-what-a-published-crate-decodes.md is a defect, and two
  tracks lose an undeclared decided: field. tests/metal-profile.toml names
  time::DEAF_CPU where it named the deleted arch::tlb::ACK_TIMEOUT.
• CLAUDE.md edits (owner-approved): the repository-layout listing becomes
  a pointer at the root workspace table and src/hostws.rs; tests/CLAUDE.md's
  host-suite list becomes a pointer at src/ci.rs's host; the std fork's paths
  carry rust/; the capabilities and dependencies clarifications.
• Every host-workspace package has a description (48, toyos-net-wire
  included), and hostws::every_package_the_workspace_names_has_a_description
  reds on one without.
• One git ls-files: sysroot::tracked_files replaces the wrappers in
  licence.rs, assets.rs, sourcegate.rs and sdkversion.rs, refusing a
  name that is not UTF-8 instead of rewriting it.
• The arch layer re-exports nothing from above it: arch::tlb no longer
  re-exports invalidation::Origin, nor arch::paging mm::policy's
  CachePolicy, MmioPolicy, Prot and WindowProt; every caller names them
  at home. The TLB shootdown's ack wait is time::DEAF_CPU, which xHCI's
  CALL_AFTER_BREAK is asserted under at compile time.

Net lines against main (c551894)

git diff --numstat origin/main HEAD: 165 files, +460 −511, net −51.

• Kernel (production): +57 −58.
• Build system, production (sysroot.rs +28 −9, licence.rs +2 −18,
  assets.rs +2 −16): +32 −43.
• Build system, test-only (hostws.rs +52 −1, sourcegate.rs +7 −37,
  sdkversion.rs +2 −2): +61 −40.
• Cargo.toml descriptions +48; *.md +261 −368; tests/metal-profile.toml
  +2 −2.

Gates

• cargo test --lib: EXIT=0, 381 passed, 0 failed, 1 ignored.
• cargo run -- --clippy: EXIT=0, 10 invocations clean.
• cargo test --workspace --exclude toyos-build: EXIT=0, no failure.
• cargo run -- --ci host: EXIT=0, 48 steps green.
• cargo run -- --build-only: EXIT=0.

Negative controls

• The description gate: toyos-net-wire/Cargo.toml without its
  description → cargo test --lib hostws EXIT=101,
  every_package_the_workspace_names_has_a_description red on
  "toyos-net-wire/Cargo.toml has no description".
• The deleted re-exports: TlsBlock::publish naming
  crate::mm::paging::Prot → cargo run -- --clippy EXIT=1,
  error[E0603]: enum import Prot is private on both architectures.

Guest tests, run by the orchestrator

The kernel changes are path renames that compile or do not; no guest test was
run on this branch. The Fast tier: cargo test, expected green or reds that
cargo run -- --known-red <test> names.

Unsure

• The arch layer still names the scheduler, the log and drivers above it; with
  the upward-import gate not landed and its issue not filed, nothing counts
  that.

🤖 Generated with Claude Code

[Japabu]

Review of #537 at 9f0665a against origin/main 16d2e64.

Before review: CI on the PR is abi-split SUCCESS. host is SKIPPED on pull requests by design (ci.yml) and runs only in the merge queue. The branch adds eight host tests; the PR body gives cargo test --lib EXIT=0 with 404 passed, against 396 at the base. The change targets no hardware.

BLOCKER

• src/citations.rs:78 — roots() takes the roots it reads from what git tracks now. Delete or rename a whole root directory and every citation into it stops being read, rather than going red. Patch: git rm -r --cached -q toyos-cc. The files stay on disk, so cargo still builds. citations::tests::every_path_the_tracker_and_the_claude_files_cite_exists stays green while issues/ still cites toyos-cc/src/codegen/resolve.rs and toyos-cc/tests/emission.rs. git rm --cached -q toyos-cc/tests/emission.rs on its own does turn it red. The test must go red on the first patch too — the header says a move or a delete goes red, and the open toolchain branch deletes exactly this root.
• src/sourcegate.rs:1820 — item != "arch" accepts any path through crate::arch::…. So an upward name that arch re-exports (pub use crate::invalidation::Origin in both tlb.rs files, pub use crate::mm::policy::… in both paging.rs files) reaches every arch file without a row. This already happens: kernel/src/arch/x86_64/paging.rs:354 names crate::arch::tlb::Origin, which is crate::invalidation::Origin, and its row (sourcegate.rs:1646) has no invalidation. Patch: add use crate::arch::paging::Prot; const _: Option<Prot> = None; to kernel/src/arch/x86_64/rtc.rs. the_arch_layer_names_nothing_above_it stays green on it; it must go red.
• kernel/src/arch/x86_64/tlb.rs:64 — the xHCI assertion now binds time::DEAF_CPU, not the wait that uses it. Patch: -const ACK_TIMEOUT: Tripwire = crate::time::DEAF_CPU; +const ACK_TIMEOUT: Tripwire = Tripwire::absurd(crate::time::Duration::from_secs(1), "m");. That builds on x86_64 at this head, leaving a 4.75 s xHCI spin with IF clear against a 1 s ack panic. The same shortening of ACK_TIMEOUT fails the build at origin/main. Fix it either way: name crate::time::DEAF_CPU at wait_for's two uses (tlb.rs:143, :147) and delete the alias, or assert ACK_TIMEOUT.nanos() >= DEAF_CPU.nanos() in tlb.rs. The x86_64 kernel check must go red on the patch. The fix edits the shootdown wait, so post tlb_shootdown_waits, run alone at the new head, with its exit code and log. This is high-risk code, and the check the branch moved is weaker than the one it replaced.
• src/citations.rs:55 — tracked() is a fifth git ls-files -z wrapper. The others are licence.rs:1155 ls_files, assets.rs:218 tracked, sourcegate.rs:1237 and the two inline copies at sourcegate.rs:2832 and :2899. Make one of them pub(crate) and derive the directories from its result. It is a sibling of what the tree already has.
• src/sourcegate.rs:1672 — crate_items_named copies arch_module_lines (sourcegate.rs:1297): the same word, line_of, skip_space and ident closures and the same {…} element walker. The copy skips a group's self as k element, which the original refuses as a rename. Make one path scanner that takes its root (core/std, or crate/$crate/super chains) as a parameter. It is a sibling.

NOTE

• CLAUDE.md edits against the approval. The four root edits and the tests/CLAUDE.md pointer match the brief's items. I hold no verbatim approved text, so the rule's closing clause "; it points at that source instead" (CLAUDE.md:21-22) is checked against the brief's paraphrase only. Two edits fall outside the approved list:
  • src/CLAUDE.md:22 changes library/ and src/bootstrap/ to rust/library/ and rust/src/bootstrap/.
  • tests/CLAUDE.md:29 drops the host-triple/calc clause.
    The PR body files the first under "placed exactly as ruled". Neither edit is wrong in fact; the orchestrator rules on both.
• src/citations.rs:31 — the <rev>^:<path> form is trusted, never resolved. All 21 in issues/ resolve today (git cat-file -e over each, run for this review). A mistyped rev or path would still pass forever, and CI's host checkout is depth 1, so resolving them needs history. The header should name this as a second hole beside crate-relative paths.
• src/citations.rs:90,100 — also unread: a whole-repository path wrapped in ** (the * makes it a pattern), a path in single quotes, and a whole-repository path:line:col. The false positives (#L anchors, kernel/userland in prose) are loud and acceptable. URLs, fork paths prefixed with a repository name, rust/, and code without a root prefix are correctly not read. I scanned the same files independently with a regex: nothing is dead except the panic locations the gate skips on purpose.
• src/sourcegate.rs:1748 — super after :: is never read, so self::super::super::super::drivers gets past the gate. An inline mod x {} (six arch files have one) shifts the depth, so a super chain inside it is counted at the wrong depth. A '"' char literal hides the rest of its line from code_only. Either say so in the doc or read these.
• src/sourcegate.rs:1811 — a row naming an existing file outside arch/ passes silently, because the check asks whether the file exists, not whether it is under ARCH_TREE.
• src/sourcegate.rs:1606 — the list is per (file, root item). A file with a sched row can add any new crate::sched::… path without being seen. The list only shrinks by item, not by reach, and a new row added with its reach is green: "only shrinks" is a convention that review enforces, not the gate.
• issues/kernel/the-arch-layer-names-the-kernel-above-it.md:36 — the owner, "the arch-contract work", is no file in issues/. Name a file that exists.
• kernel/src/drivers/xhci/mod.rs:326 — the assertion is correct on both architectures. On AArch64 it binds a tripwire that nothing waits on, so there it guards nothing. On x86_64 the timeout is 5 s before and after. ACK_TIMEOUT is read only through .nanos(), so the new reason string reaches no output, and there is no runtime change at this head. No guest test reaches the 5 s arm: tlb_shootdown_waits stages 20 ms delays.
• Deleted issues/build/issue-files-cite-paths-that-moved.md — its exit condition holds at this head: no whole-repository path in issues/ is dead. Its durable rule is at citations.rs:7-8. Commit c4fc16e's "the owner's answer" is truthful on the owner-approved plan. Its "(a move that strands one is refused)" is not yet true of a move at root level (first BLOCKER). It cannot be amended, so the fix round's commit says so.
• 98b3545's default revert message does not matter. The -F rule guards against -m backtick substitution, which a default revert message cannot trigger, and the revert names the hash it reverts. The red it measured is recorded only in the PR body, which becomes the merge commit. 41ae518 also swept in the uncommitted arch-gate draft; the revert removed it, and the planted dead path is still a valid control for this gate.
• Duplicates: all three merges are lossless. Every sighting, number, rev, command and exit clause of the deleted files is in the file that survives. git grep finds no citation of any deleted slug anywhere in the tree, src/redlist.rs included.
• Net lines (git diff --shortstat): 128 files, +976 −368.
  • Production: kernel/src +20 −14, net +6. The alias fix in the third BLOCKER removes 4 of these. The 47 description lines replace the deleted list.
  • Test-only (#[cfg(test)]) gate code in src/: +621 −1. The fourth and fifth BLOCKERs shrink it.
  • Prose: issues/ +281 −316, CLAUDE.md files +7 −37.

REMOVE

• src/CLAUDE.md:36 — "Documentation carries no gates" — false once src/citations.rs lands. The orchestrator has authorised deleting it; the fix round deletes it.
• kernel/src/arch/x86_64/tlb.rs:62-63 — "Every spin that masks them holds itself under this at its own site" — one site (xhci/mod.rs:326) does, and nothing holds the others to it.
• bcachefs/Cargo.toml:3 — "and the interim ToyOS format the kernel still links" — goes false when the kernel's storage code is deleted.
• issues/kernel/the-arch-layer-names-the-kernel-above-it.md:12-13 — "enumerates every such name" — false (paging.rs:354).
• PR body, first bullet under "Unsure" — "the toolchain branch deletes toyos-cc … will red on this gate" — false: deleting the whole root makes its citations unread. This body becomes the merge commit.

SEND BACK

[Japabu]

Review of #537, round 2, at 5f527da against origin/main 16d2e64. Changes reviewed since 9f0665a.

Before review: CI on the PR is abi-split pass at 5f527da (run 36317954159). host is skipped on pull requests by design. The PR body gives cargo test --lib EXIT=0 (404 passed, 1 ignored) and tlb_shootdown_waits alone EXIT=0, and both logs exist.

Round-1 BLOCKERs

• B1, gone root: OPEN. The toyos-cc patch now reds (EXIT=101), but the class it stood for does not. A deleted root is read only when a citation of it is "path-shaped" (citations.rs:112-114): the first character must be a lowercase letter, and the token must end in /…/ or a lowercase extension. So:
  • git rm -r --cached -q toyos-desktop leaves cargo test --lib citations:: green. userland/CLAUDE.md:3 and issues/design-debt/what-is-owed-on-file-size.md:17 cite the bare toyos-desktop/. The root's only other citation is a path:line:col, which the scan skips.
  • git rm -r --cached -q .claude leaves it green too, although CLAUDE.md:16, :90 and :100 cite .claude/agents/reviewer.md: a first component that starts with . is not lowercase.
  • toyos-fat32-check, toyos-proclife and toyos-symbols are in the same state: every citation of each is the bare name/.
    Both patches must go EXIT=101 naming those lines.
• B2, re-exports: OPEN. The round-1 patch now reds. A one-token variant does not: arch_reach (sourcegate.rs:1750-1754) matches a re-exported name only when it is spelled in the path, and a glob never spells it. Patch for kernel/src/arch/x86_64/rtc.rs: use crate::arch::paging::*; const _: Option<Prot> = None;. the_arch_layer_names_nothing_above_it stays green, and it must red naming rtc.rs and crate::mm.
• B3, ack wait: CLOSED. wait_for reads ACK_TIMEOUT.nanos() at tlb.rs:145 and :149, and that is the value asserted at :66. The PR body gives these measurements: the 1 s patch is EXIT=101 at tlb.rs:66, and tlb_shootdown_waits alone at 5f527da is EXIT=0 (qemu-tlb.log line 106 PASS, line 117 ok).
• B4, one ls-files: CLOSED for the five named sites. A sixth is missed; see NOTE.
• B5, one scanner: CLOSED. spelled_paths is the only scanner. A group's self as k is refused for the crate root; every_spelling_of_a_crate_root_item_is_read asserts it at sourcegate.rs:1945.

BLOCKER

• src/citations.rs:107-115 — B1 is still open (patches above). Either read the bare name/ form and a first component that starts with . when the root is gone, or read every citation of a gone root whatever its shape. The prose that writes nonexistent directories as fs/ would then be rewritten. The header's claim at :17 "a root this tree no longer holds is still read" is false until one of these lands.
• src/citations.rs:59-62 — no gate keeps FOREIGN honest, and one entry is already dead at the head that adds it. Patch: delete "smoltcp-0.12.0", from :61. citations:: stays EXIT=0, because the name's only use (issues/isolation/netd-socket-ids-are-ambient.md:24) is a path:line:col the scan already skips. Add a red for a FOREIGN name that no token needs, as this branch does for a stale ARCH_REACHES_UP row. Every future fork citation grows this list, so it rots unless something reds.
• src/sourcegate.rs:1765-1790 — B2 is still open. Beside the glob patch above, two more spellings evade the same test:
  • A second hop written relative to its module: pub use paging::Prot as ArchProt; in x86_64/mod.rs, plus const _: Option<crate::arch::ArchProt> = None; in rtc.rs. arch_reexports reads only crate-rooted statements, so the second hop is never recorded.
  • A type alias: pub type Hop = crate::invalidation::Origin; in x86_64/tlb.rs, plus const _: Option<crate::arch::tlb::Hop> = None; in rtc.rs. This file's own renames_command counts a type alias as a rename.
    All three patches must red the_arch_layer_names_nothing_above_it naming rtc.rs. Refuse each by name, or delete the five upward re-exports, which leaves nothing to resolve.

NOTE

• src/sdkversion.rs:345 — tracked_lockfiles is a sixth hand-rolled git ls-files -z. Move it onto sysroot::tracked_files with the pathspec *Cargo.lock.
• src/sysroot.rs:610 — tracked_files decodes with from_utf8_lossy. At 9f0665a, sourcegate.rs's two listings and citations.rs failed loudly on a name that is not UTF-8. Now the name is rewritten, and every_committed_binary_file_is_declared then continues past a file it cannot open. Refuse such a name by name.
• src/licence.rs:1251,1269 — judge returns Result, but a failing git ls-files now panics instead of returning Err. The function mixes two ways of failing.
• kernel/src/arch/x86_64/tlb.rs:63-66 — the alias plus an assertion that the alias is at least what it aliases is the larger of round 1's two fixes. Delete both and name crate::time::DEAF_CPU at :145 and :149. That is 3 lines fewer, and the value can no longer diverge at all.
• cargo run -- --clippy was not run at 5f527da, and this round changes src/ and kernel/. Post it before the merge queue's host job finds it.
• Net lines (git diff --shortstat origin/main...HEAD): 131 files, +1208 −546.
  • Production kernel: +21 −13, net +8 (+6 at round 1). The NOTE above removes 3.
  • Production build system (assets, licence, sysroot): +11 −34, net −23.
  • description lines in Cargo.toml: +47.
  • Test-only gate code (citations.rs, sourcegate.rs, hostws.rs, the lib.rs declaration): +843 −145, net +698.
  • Prose: issues/ +279 −316, CLAUDE.md files +7 −38.

REMOVE

• kernel/src/arch/x86_64/tlb.rs:65 — "A spin with interrupts masked is held under DEAF_CPU at its own site" — the round-1 REMOVE, reworded and back. One site (xhci/mod.rs:326) holds itself there; vtd/queue.rs:45's spin does not.
• kernel/src/time.rs:221-223 — "A spin that holds interrupts masked is bounded under it at its own site, and never the other way." — the same false universal.
• PR body — "That was not true of a whole root until 5f527da." — false for the roots named under B1. This body becomes the merge commit.

SEND BACK