Every crate with one consumer moves under it, and the track closes

[Japabu]

Step 4 of issues/build/code-used-by-one-program-lives-in-that-program.md, the track's last step. Every crate with exactly one consumer moves under that consumer, and the track closes.

The count

The count follows the step's own definition. It reads cargo metadata --offline --no-deps over every manifest git ls-files '*Cargo.toml' lists (97 manifests, 96 packages; userland/Cargo.toml is a virtual workspace). Every path dependency of any kind counts. A shipped program is its own consumer.

My count at the base, 42e5fca73, matches the scout's list exactly: the same 14 packages have one consumer. There is one difference in the result, which comes from the pair rule below: toyos-net-tcp moves too, which the scout's list did not include.

What moved, and why

Every package keeps its name. That means no use line changes, and kernel/Cargo.lock and userland/Cargo.lock do not change. The root Cargo.lock drops the three packages that left the host workspace (−18).

package	from	to	consumer
toyos-dma, toyos-gicv3, toyos-pci, toyos-ps2	toyos-*	kernel/{dma,gicv3,pci,ps2}	the kernel
toyos-transport	toyos-transport	toyos-blockring/transport	toyos-blockring
toyos-net-testnet	toyos-net-testnet	toyos-net-shard/testnet	toyos-net-shard (dev)
toyos-net-tcp	toyos-net-tcp	toyos-net-shard/tcp	the shard/testnet pair
toyos-desktop	toyos-desktop	userland/compositor/desktop	compositor
toyos-mdns	toyos-mdns	userland/netstack/mdns	netstack
toyos-mixer	toyos-mixer	userland/soundserver/mixer	soundserver

• The kernel's four and the two network crates stay members of the host workspace, at their new paths, the way kernel/loom and kernel/sim already are. They are tested and linted exactly as before.
• The pair. toyos-net-testnet and toyos-net-shard are each other's only consumer, so the step as written could not be met. I added one sentence to the step. It is the orchestrator's reading, not an owner ruling: "Of two crates that are each other's only consumer, the one the other names only as a dev-dependency moves under it, and the count treats the pair as one crate." So the testnet moves under the shard. Under the same sentence, toyos-net-tcp's two consumers, the shard and the testnet, count as one, so the TCP crate moves under the shard as well.
• The three under userland programs join the userland workspace. A crate under userland/ belongs to the workspace userland/Cargo.toml roots, so they leave the host workspace and are listed in the userland workspace's members.
  • Each gains [lib] doctest = false, which the survey asks of every userland library because the toyos toolchain builds no rustdoc. None of the three has a doc-test (-- --list at base shows 0 for each), so no test is lost.
  • Each manifest's header comment is deleted, save toyos-mixer's "No dependencies, deliberately" paragraph: what was left restated the description or the modules.
• src/userlandhost.rs's survey gates a nested crate's tests instead of listing them as escapes, as the step says. --ci host now runs cargo test --manifest-path userland/<program>/<crate>/Cargo.toml --target <host> for each nested crate that holds a test.
  • The survey's fixture test now expects gated/sub among the gated crates, where it used to expect an escape.
  • The module doc no longer says "directly under userland/".
• src/clippy.rs lints every nested crate the survey gates. The host workspace's shapes no longer reach the three userland crates, and the step's check says --clippy lints them. The runs are not listed: clippy::run takes userlandhost::survey's gated crates whose directory holds a / and runs cargo clippy --manifest-path userland/<dir>/Cargo.toml --all-targets -- $ADOPTED -D warnings for each, against the host, the way ci.rs derives the tests. A crate moved under a program later is linted once it holds a test, with nothing to add by hand.
  • The userland programs themselves stay unlinted. At base, cargo clippy -D warnings on each gated program fails: calc, diskserver, fileserver, logkeeper, netstack and pkg each exited 101 on real findings, and soundserver and sshserver exited 101 when the manifest load failed mid-move. issues/build/userland-programs-are-never-linted.md now says which crates are linted and that no program is.
  • The module doc's sentence on why userland is absent is deleted.
• Citations of the moved paths are updated, in userland/CLAUDE.md and six issue files. userland/soundserver/src/main.rs's header lines that cited toyos-mixer/ and toyos-desktop/ are deleted. Three kinds stay as they were:
  • issues/build/the-host-job-runs-the-toolchain-the-runner-ships.md quotes toyos-desktop/src/input.rs and toyos-mixer/src/channel.rs inside a pasted clippy log. That is output, so it stays verbatim, following toyos-fat32-check moves to toyos-fat32/check, beside the one subject it judges #691.
  • Prose that names a crate by its package name ("like toyos-ps2") is still true.
  • issues/design-debt/what-is-owed-on-file-size.md's history keeps the paths 763712b and the mixer's split wrote, toyos-desktop/ and toyos-mixer/, and says they have moved since.
• Outside the tree: rg over the fork clones beside the monorepo, rust/library and rust/compiler/rustc_target finds none of the ten names. ~/.cargo/git/checkouts/ finds them only in a cargo checkout of this repository at 6115718, as in toyos-fat32-check moves to toyos-fat32/check, beside the one subject it judges #691.

The track closes

The second commit deletes the track file, because its exit is met.

• No directory the file names as moved or merged still exists. Step 4 names none, and steps 1, 2, 3 and 5 each left the file with their own pull requests.
• Step 4's count finds no crate outside its one consumer. I re-ran the count at a08850a80. Of its 14 packages with one consumer:
  • ten sit under that consumer: the nine in the table besides toyos-net-tcp, which now has two, and tls-dep, already under tls-multi-crate;
  • toyos-net-shard is one half of the pair, whose only consumer is the other half;
  • diskserver, inspect and terminal are programs system.toml ships, so each is its own consumer.
• git grep finds no citation of the slug or its title.
• The rule the track carried already has a home: .claude/agents/reviewer.md's Fit line, as the track itself said.

Gates

The branch merges origin/main at 42bda5268 (#696). That run includes #696's the_kernel_resolves_no_libc_for_either_target, which runs cargo tree --locked on kernel/Cargo.toml, whose four path dependencies this branch moves. It passes.

gate	head	exit	log
cargo run -- --ci host	dec6bef21	0, Host: 72 step(s), all green	folders4-r2/ci-host.log
cargo run -- --build-only	dec6bef21	0, Build finished.	folders4-r2/build-only.log
cargo test, the whole guest suite	dec6bef21	0, 26 passed, 26 total	folders4-r2/guest.log
cargo run -- --clippy	dec6bef21	0, 22 invocations clean	folders4-r2/clippy-clean.log

The logs are in the brief's log directory, under orch/. The host run has three more steps than before: userland/compositor/desktop, userland/netstack/mdns and userland/soundserver/mixer.

I ran the guest suite whole because the kernel, compositor, netstack and soundserver were all rebuilt from moved paths. The source is unchanged, but the bytes are not: panic locations carry the file's path.

The step's check, part 1: --ci host runs every test each package lists today. I listed each package's tests at base with cargo test -p <package> -- --list. At head I used the same command for the root members, and for the three userland crates the gate's own command, cargo test --manifest-path … --target aarch64-apple-darwin -- --list. Every run exited 0. Each package lists the same names at both heads, once a doc-test's path prefix is mapped to its new directory.

package	base	head
toyos-desktop	95	95
toyos-mdns	12	12
toyos-mixer	55	55
toyos-transport	17 (4 doc)	17 (4 doc)
toyos-net-tcp	376 (5 doc)	376 (5 doc)
toyos-net-testnet	2	2
toyos-dma	17	17
toyos-gicv3	9	9
toyos-pci	75	75
toyos-ps2	24	24

In ci-host.log, the three userland steps read 95 passed, 12 passed and 55 passed.

The step's check, part 2: --clippy lints them. The root members stay under the existing workspace shapes. For the three userland crates, I ran a checked mutation at dec6bef21, posted as a comment on this pull request (folders4-r2/mutation.log):

• The patch: a test asserting v.len() == 0 on a &[u8], added to userland/compositor/desktop/src/budget.rs.
• Build: cargo test --manifest-path userland/compositor/desktop/Cargo.toml --target aarch64-apple-darwin --no-run exited 0.
• Clippy: cargo run -- --clippy exited 1. It reported clippy::len_zero at compositor/desktop/src/budget.rs:133:17 under the derived run cargo clippy --manifest-path userland/compositor/desktop/Cargo.toml --all-targets, and 1 of 22 invocation(s) found warnings.
• Restore: git apply -R exited 0, and the tree was clean.

The survey gate has a negative control, run at e169ca7a4 and posted as a comment. I put back the base's nested-crate escape branch as a checked patch:

• cargo build --lib exited 0.
• cargo test --lib userlandhost exited 101. every_userland_test_is_in_the_gate failed, naming every test file under compositor/desktop, netstack/mdns and soundserver/mixer, and the fixture test failed too.
• git apply -R exited 0.

Growth

git diff --shortstat origin/main...dec6bef21: 118 files, +137 −195. Every non-manifest file moves as a 100% rename. Each moved manifest changes only its paths, and the three userland manifests also lose their headers and gain [lib]. Git reads the desktop and mdns manifests as a delete and an add.

• Build system (src/): +62 −45. clippy.rs +52 −28: the derived runs, and run reporting how many ran. userlandhost.rs +9 −16, the survey and its docs. ci.rs +1 −1.
• The track: −42.
• Lockfile: −18.
• The rest is manifests and citation paths.

Unsure

• Doc-test names carry the file's path, so toyos-transport's and toyos-net-tcp's doc-tests now read under their new directories. git grep 'rs - (' finds nothing in the tree that keys on those names.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8

[Japabu]

Mutation patches for #703, each applied with git apply --check then git apply, run, and restored with git apply -R (results in the body).

Clippy reaches the userland nested crates (cargo run -- --clippy exit 1, clippy::len_zero at compositor/desktop/src/budget.rs:133:17):

diff --git a/userland/compositor/desktop/src/budget.rs b/userland/compositor/desktop/src/budget.rs
index 592846086..d9f30afbd 100644
--- a/userland/compositor/desktop/src/budget.rs
+++ b/userland/compositor/desktop/src/budget.rs
@@ -124,3 +124,12 @@ mod tests {
         assert_eq!(create_verdict((0, 0), Rect::new(0, 0, 4, 4), 0, 10), Verdict::Allow);
     }
 }
+
+#[cfg(test)]
+mod planted {
+    #[test]
+    fn planted() {
+        let v: &[u8] = &[];
+        assert!(v.len() == 0);
+    }
+}

Negative control: the base survey branch back (cargo test --lib userlandhost exit 101):

diff --git a/src/userlandhost.rs b/src/userlandhost.rs
index 9d74d61c5..43866c0c9 100644
--- a/src/userlandhost.rs
+++ b/src/userlandhost.rs
@@ -101,7 +101,11 @@ pub fn survey(userland: &Path) -> Result<Survey, String> {
             continue;
         }
         let inside = rel(owner, file);
-        if !(inside.starts_with("src/") || inside.starts_with("tests/")) {
+        if crate_name.contains('/') {
+            escapes.insert(format!(
+                "{at}: a test in the nested crate {crate_name}, which the gate does not discover"
+            ));
+        } else if !(inside.starts_with("src/") || inside.starts_with("tests/")) {
             escapes.insert(format!(
                 "{at}: a test outside {crate_name}'s src/ and tests/, which cargo test does not run"
             ));

[Japabu]

Review round 1, head e169ca7a4.

Net: 116 files, +110 −158. Of that, src/ production is +28 −15 (clippy.rs +20 −3, userlandhost.rs survey and its docs +8 −12) and the survey's fixture test is +1 −4. The rest is moves, manifests, the root lock (−18) and the track (−42).

I re-ran the count myself: cargo metadata --offline --no-deps over all 97 git ls-files '*Cargo.toml' at e169ca7a4, 96 packages. 14 packages have one consumer, and they are the ones the PR body names. toyos-net-tcp's consumers are toyos-net-shard and toyos-net-shard/testnet. The gate exits are 0 in orch/folders4/*.exit. The mutation and negative-control results files read clippy EXIT=1 and survey test EXIT=101, each with a clean restore.

On the brief's question, whether the pair sentence makes the toyos-net-tcp move follow: it does. "The count treats the pair as one crate" turns tcp's two consumers, the shard and the testnet, into one. The sentence's first clause puts the testnet under the shard, so the pair's directory is toyos-net-shard/. The sentence never states an owner ruling as his: the commit and the PR body both call it the orchestrator's reading. The file is added and deleted in the same PR, so the PR body is the only record of the reading on main.

BLOCKER

• src/clippy.rs:191-207 — the shape lists toyos-desktop, toyos-mdns and toyos-mixer by hand. A fourth crate moved under a userland program would be gated by the survey on its first test but never linted, and nothing would go red. — That makes a second declaration of the nested userland crates, beside userland/Cargo.toml's members and the survey. src/userlandhost.rs's own module doc says "There is no list", and the root Cargo.toml header records lists like this drifting three times. Fix: build the nested-crate clippy invocations at run time from userlandhost::survey(...).gated entries that contain /, one --manifest-path userland/<dir>/Cargo.toml --all-targets each, as ci.rs:598-605 already does for tests, and delete the hand list. Re-run the planted len_zero in userland/compositor/desktop/src/budget.rs: it must still turn --clippy red.

NOTE

• issues/build/userland-programs-are-never-linted.md:9 — "src/clippy.rs lints no userland crate" is false at this head, because three userland crates are now linted. The record has to stay true of the tree: say which crates are linted and that the programs are still not.
• issues/design-debt/what-is-owed-on-file-size.md:17,21 — the history lines now say 763712b and 2026-08-20 moved the code to userland/compositor/desktop/ and userland/soundserver/mixer/. Those commits moved it to toyos-desktop/ and toyos-mixer/, so the record is now false about its own history. Keep the old paths there, or say they have moved since.
• Branch base 42e5fca73 is behind origin/main (ToyOS writes its own crate where security asks, above all on a trust boundary or in the kernel; a host test reds on a kernel that resolves libc, and the owner's allocator ruling is filed #696). ToyOS writes its own crate where security asks, above all on a trust boundary or in the kernel; a host test reds on a kernel that resolves libc, and the owner's allocator ruling is filed #696's the_kernel_resolves_no_libc_for_either_target runs cargo tree --locked on kernel/Cargo.toml, and this branch moves four of that manifest's path dependencies. git merge-tree is clean, but no --ci host has run on the merged tree. Merge origin/main and post that run.
• PR body, "Unsure" — once this lands, its first two bullets are addressed to the reviewer and not to main's record. Drop them, or put the clippy-list point in the issue above.

REMOVE

• userland/compositor/desktop/Cargo.toml:1-3 — a rewritten header that restates description.
• userland/netstack/mdns/Cargo.toml:1-2 — a rewritten header that restates description.
• userland/soundserver/mixer/Cargo.toml:1-3 — a rewritten header that lists what the crate's modules already show. The "No dependencies, deliberately" paragraph stays.
• userland/soundserver/src/main.rs:3-10 — doc lines corrected instead of deleted. Lines 7-8 are also chronology ("the answer this program used to compute inline").
• userland/soundserver/src/main.rs:12 — "The split is userland/compositor/'s, against its desktop/" is a corrected cross-reference, not a contract.
• src/clippy.rs:7-9 — a doc line corrected instead of deleted, and its reason is not this branch's: the survey's programs build for the host, and the PR body's own measurement says they are left out because they are not clippy-clean.

SEND BACK

[Japabu]

Review round 1 control, re-run at dec6bef21, where the nested crates' clippy runs come from the survey. Applied with git apply --check (exit 0) and git apply (exit 0); the planted test built (cargo test --manifest-path userland/compositor/desktop/Cargo.toml --target aarch64-apple-darwin --no-run exit 0); cargo run -- --clippy exited 1 with clippy::len_zero at compositor/desktop/src/budget.rs:133:17 under cargo clippy --manifest-path userland/compositor/desktop/Cargo.toml --all-targets, 1 of 22 invocation(s) found warnings; git apply -R exit 0, tree clean. Unpatched, --clippy exits 0, 22 invocations clean.

diff --git a/userland/compositor/desktop/src/budget.rs b/userland/compositor/desktop/src/budget.rs
--- a/userland/compositor/desktop/src/budget.rs
+++ b/userland/compositor/desktop/src/budget.rs
@@ -124,3 +124,12 @@ mod tests {
         assert_eq!(create_verdict((0, 0), Rect::new(0, 0, 4, 4), 0, 10), Verdict::Allow);
     }
 }
+
+#[cfg(test)]
+mod planted {
+    #[test]
+    fn planted() {
+        let v: &[u8] = &[];
+        assert!(v.len() == 0);
+    }
+}

[Japabu]

Review round 2, head dec6bef21.

Round 1:

• BLOCKER src/clippy.rs hand list of the nested userland crates — CLOSED. SHAPES no longer names toyos-desktop, toyos-mdns or toyos-mixer. clippy::runs now derives one NESTED run for each survey.gated entry that holds a /, the way ci.rs:598-605 derives the tests. The measurement is folders4-r2/mutation.log at dec6bef21: clean --clippy EXIT=0 with 22 invocations clean. With the planted len_zero in userland/compositor/desktop/src/budget.rs applied, --clippy EXIT=1, reported under the derived --manifest-path userland/compositor/desktop/Cargo.toml run. Restore EXIT=0. clippy-clean.log shows the three derived runs, and ci-host.log reads Host: 72 step(s), all green at that head.
• NOTE issues/build/userland-programs-are-never-linted.md — addressed. It now says the nested crates are linted and no program is.
• NOTE what-is-owed-on-file-size.md history — addressed. It keeps toyos-desktop/ and toyos-mixer/ and says they have moved since.
• NOTE merge of ToyOS writes its own crate where security asks, above all on a trust boundary or in the kernel; a host test reds on a kernel that resolves libc, and the owner's allocator ruling is filed #696 — addressed. Merged at 48fa9c3c6, and --ci host is green on that tree. main has since taken The kernel heap acquires and zeroes no frame while its lock is held #699 (836b2bc8f). That change touches only kernel/src/mm/{alloc,pmm}.rs and two new issue files, and neither cites a moved path. git merge-tree --write-tree origin/main dec6bef21 exits 0.
• NOTE PR body "Unsure" — addressed. The two bullets addressed to the reviewer are gone.
• REMOVE ×6 — all deleted. The desktop and mdns manifest headers, the mixer header's restating lines (its "No dependencies" paragraph stays), soundserver/src/main.rs's corrected lines and cross-reference, and clippy.rs's userland sentence.

Net: 118 files, +137 −195. In src/, production is +62 −45: clippy.rs +52 −28, userlandhost.rs +9 −16 (the fixture test −3 net), ci.rs +1 −1. The track's 42 lines and 18 lines of the root lock are deleted.

BLOCKER

NOTE

REMOVE

LAND