From a5f40d9e005cdaaa108fd7725a1911655fa26a53 Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 16:50:43 +0200 Subject: [PATCH 1/4] Layout step 0: every package says what it is, three stale files go, and the layout is a track The owner adopted a repository layout on 2026-10-04. This files it as issues/the-tree-says-who-uses-each-thing.md (the rule verbatim, his rulings verbatim and dated, the adopted tree with the changes later rulings and main made to it, and the migration as stages with exits), files the design's findings that are still true, and lands the design's step 0. Step 0, each item measured again on origin/main at c4ab2b1e1: - 34 package manifests had no description (29 under userland/, the five tls-* fixtures); each now has one. Nothing in the tree reads a guest package's CARGO_PKG_DESCRIPTION, so no binary changes; userland/libc's manifest is a sysroot key input, so the sysroot is rebuilt once. - .cargo/config.toml.example is cited by nothing; implementer.md already says how to list a fork clone in .cargo/config.toml. - kernel/README.md said "for x86-64" and "Depends on tyfs", both false. - kernel/TECHNICAL_DEBT.md was a second tracker. Items 1, 3, 4 and 5 were marked done. Item 6 (2 MiB demand fills as 512 NVMe reads) is no longer true: a file-backed fill reads ROOT's in-memory image or shared memory, not a device. Item 7 (translate_user demand-pages by calling handle_page_fault) is still true and is filed as issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md. - The owner's ghost directories the design listed are already gone from the primary checkout (all 20 absent). Findings filed: F1 as issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md, F2 as issues/every-image-ships-a-hello-rs-nothing-reads.md (share/hello.rs is in the image --build-only makes, by imgstat), F3 as issues/the-ssh-judge-runs-the-servers-own-russh.md, F5 as issues/std-names-the-sdk-crates-by-path.md. F4 (descriptions) is fixed here. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- .cargo/config.toml.example | 16 -- ...d-pages-under-whatever-its-caller-holds.md | 19 ++ ...ry-image-ships-a-hello-rs-nothing-reads.md | 16 ++ ...ystem-font-by-a-path-only-this-tree-has.md | 30 +++ issues/std-names-the-sdk-crates-by-path.md | 21 ++ ...he-ssh-judge-runs-the-servers-own-russh.md | 19 ++ issues/the-tree-says-who-uses-each-thing.md | 218 ++++++++++++++++++ kernel/README.md | 5 - kernel/TECHNICAL_DEBT.md | 56 ----- .../toyos-rust-tests/tls-cranelift/Cargo.toml | 1 + .../tls-dlopen-lib/Cargo.toml | 1 + tests/toyos-rust-tests/tls-lib/Cargo.toml | 1 + .../tls-multi-crate/Cargo.toml | 1 + .../tls-multi-crate/dep/Cargo.toml | 1 + userland/calc/Cargo.toml | 1 + userland/compositor/Cargo.toml | 1 + userland/console/Cargo.toml | 1 + userland/diskserver/Cargo.toml | 1 + userland/doom/Cargo.toml | 1 + userland/editor/Cargo.toml | 1 + userland/filepicker-api/Cargo.toml | 1 + userland/filepicker/Cargo.toml | 1 + userland/files/Cargo.toml | 1 + userland/host/Cargo.toml | 1 + userland/inspect/Cargo.toml | 1 + userland/libc/Cargo.toml | 1 + userland/logkeeper/Cargo.toml | 1 + userland/metalprobe/Cargo.toml | 1 + userland/netstack/Cargo.toml | 1 + userland/paint/Cargo.toml | 1 + userland/pkg/Cargo.toml | 1 + userland/proctest/Cargo.toml | 1 + userland/shell/Cargo.toml | 1 + userland/snake/Cargo.toml | 1 + userland/soundserver/Cargo.toml | 1 + userland/sprite/Cargo.toml | 1 + userland/sshserver/Cargo.toml | 1 + userland/supervisor/Cargo.toml | 1 + userland/swap/Cargo.toml | 1 + userland/terminal/Cargo.toml | 1 + userland/test-runner/Cargo.toml | 1 + userland/toybox/Cargo.toml | 1 + userland/update/Cargo.toml | 1 + 43 files changed, 357 insertions(+), 77 deletions(-) delete mode 100644 .cargo/config.toml.example create mode 100644 issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md create mode 100644 issues/every-image-ships-a-hello-rs-nothing-reads.md create mode 100644 issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md create mode 100644 issues/std-names-the-sdk-crates-by-path.md create mode 100644 issues/the-ssh-judge-runs-the-servers-own-russh.md create mode 100644 issues/the-tree-says-who-uses-each-thing.md delete mode 100644 kernel/README.md delete mode 100644 kernel/TECHNICAL_DEBT.md diff --git a/.cargo/config.toml.example b/.cargo/config.toml.example deleted file mode 100644 index e703d9a4e2a..00000000000 --- a/.cargo/config.toml.example +++ /dev/null @@ -1,16 +0,0 @@ -# Local fork development — copy to .cargo/config.toml (gitignored). -# -# Committed builds fetch every fork from GitHub, so a fresh clone works with -# no setup. When you need to *edit* a fork, clone it next to the monorepo and -# list it here; cargo then uses your working copy instead of the git branch. -# -# git clone https://github.com/ToyOSOrg/cpal ../forks/cpal -# cd ../forks/cpal && git checkout toyos-0.18.0 -# -# Delete the entry (or the file) to go back to the pushed branch. - -paths = [ - # "../forks/cpal", - # "../forks/socket2", - # "../forks/winit", -] diff --git a/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md new file mode 100644 index 00000000000..d198406c437 --- /dev/null +++ b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md @@ -0,0 +1,19 @@ +--- +status: open +kind: finding +opened: 2026-10-04 +--- + +# A user copy demand-pages under whatever its caller holds + +`user_ptr::translate_user` (`kernel/src/user_ptr.rs`) calls +`process::handle_page_fault` directly when a user address is not mapped, and +every user copy faults its windows in through it (`fault_in`). +`handle_page_fault` takes `PROCESS_TABLE`, the current process's +`process_data` and its address-space lock. A syscall that copies user memory +while holding any of the three deadlocks on the first unmapped window, and +nothing in the tree refuses that order: no lock-order check covers these locks. + +**Exit:** the order is refused by something that fails (a type or a +checked lock level), or every caller is shown to hold none of the three and +the invariant is one line in `user_ptr.rs`'s header. diff --git a/issues/every-image-ships-a-hello-rs-nothing-reads.md b/issues/every-image-ships-a-hello-rs-nothing-reads.md new file mode 100644 index 00000000000..3687c3b8655 --- /dev/null +++ b/issues/every-image-ships-a-hello-rs-nothing-reads.md @@ -0,0 +1,16 @@ +--- +status: open +kind: defect +opened: 2026-10-04 +--- + +# Every image ships a hello.rs nothing reads + +`assets/hello.rs` is swept into ROOT with the rest of `assets/`: the image +`cargo run -- --build-only` makes holds it as `share/hello.rs`, 55 bytes, by +`cargo run --example imgstat -- target/bootable.img`. No source, test or +manifest in the tree names it but its row in `src/licence.rs`, and that row +says `tests/common/compile.rs` builds it, which that file does not. + +**Exit:** `assets/hello.rs` and its licence row are gone, or something that +runs reads it and the row names that. diff --git a/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md new file mode 100644 index 00000000000..d2ce563ac65 --- /dev/null +++ b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md @@ -0,0 +1,30 @@ +--- +status: open +kind: defect +opened: 2026-10-04 +--- + +# Five apps read the system font by a path only this tree has + +An app builds and runs on Linux, macOS and Windows from the same source as on +ToyOS (root `CLAUDE.md`), and stage 7 of +`issues/a-package-is-a-directory-under-apps-and-the-installer-is-a-program.md` +builds each one outside this repository against published SDK crates alone. +Five of the six apps cannot, because of how they find JetBrains Mono: + +- `editor` (`src/main.rs:1444`), `files` (`:60`) and `paint` (`:173`) read + `/system/share/fonts/JetBrainsMono-Regular-8x16.font` and `expect` it, so on + a host they build and then panic at start; `files` reads + `/system/share/icons/*.svg` the same way (`:63-64`). +- `calc` (`build.rs:32`) and `snake` (`build.rs:7`) read + `../../assets/JetBrainsMono-Regular.ttf` in their build scripts, a path + into this tree. + +**The owner ruled the fix on 2026-10-04**, recorded verbatim in +`issues/the-tree-says-who-uses-each-thing.md`: an SDK call answers the +platform's monospace font, `/system/share/fonts` on ToyOS and the platform's +own on Linux, macOS and Windows. + +**Exit:** no app's source or build script names `/system/share` or a path +outside its own directory, each of the five takes its font from that SDK +call, and each starts on a host. diff --git a/issues/std-names-the-sdk-crates-by-path.md b/issues/std-names-the-sdk-crates-by-path.md new file mode 100644 index 00000000000..b945a692ec1 --- /dev/null +++ b/issues/std-names-the-sdk-crates-by-path.md @@ -0,0 +1,21 @@ +--- +status: open +kind: defect +opened: 2026-10-04 +--- + +# std names the SDK crates by path + +`rust/library/std/Cargo.toml` takes `toyos-abi` from `../../../toyos-abi` +and `toyos` from `../../../toyos`, so the fork knows where this repository +keeps them. `.claude/agents/implementer.md` ("A fork") says a fork depends on +ToyOS crates by version, never by path; `vex-sdk`, three lines above in the +same file, is named by version. + +It is stage 4 of `issues/the-tree-says-who-uses-each-thing.md`: while the +path stands, moving either crate breaks every fork commit pinned before the +move. + +**Exit:** std names both by version, the build supplies them by a `[patch]`, +a clean toolchain build passes, and the sysroot key is unchanged by the +switch. diff --git a/issues/the-ssh-judge-runs-the-servers-own-russh.md b/issues/the-ssh-judge-runs-the-servers-own-russh.md new file mode 100644 index 00000000000..1e0f080bfcd --- /dev/null +++ b/issues/the-ssh-judge-runs-the-servers-own-russh.md @@ -0,0 +1,19 @@ +--- +status: open +kind: defect +opened: 2026-10-04 +--- + +# The SSH judge runs the server's own russh + +`tests/ssh-client-host` is the harness's SSH client, and the root manifest +keeps it out of the workspace as "a second implementation". It is not one: +it takes `russh` from `https://github.com/ToyOSOrg/russh`, branch `toyos`, +and its lock pins commit `389804d3b9908250282746c934c58c059b88fb7e`, the same +commit `userland/Cargo.lock` pins for `sshserver` through userland's +`[patch]`. A defect in the fork's protocol code is on both ends of every SSH +test, and the two can agree on it. + +**Exit:** the judge's lock names no `ToyOSOrg` source, or the root +manifest's exclusion comment stops calling it a second implementation and +this file names what judges the server's protocol instead. diff --git a/issues/the-tree-says-who-uses-each-thing.md b/issues/the-tree-says-who-uses-each-thing.md new file mode 100644 index 00000000000..cbc68cf8c3e --- /dev/null +++ b/issues/the-tree-says-who-uses-each-thing.md @@ -0,0 +1,218 @@ +--- +status: assigned +kind: track +opened: 2026-10-04 +--- + +# The tree says who uses each thing + +The repository's top level is shaped by cargo's per-directory `build.target`, +not by what each thing is or who uses it. The owner adopted a layout on +2026-10-04; this file records it and the migration to it. + +**Owner:** the orchestrator. The rule, the rulings and the tree are the +owner's, the tree changed only where a later ruling or `main` moved it (listed +under it); the stages and their exits are the orchestrator's plan. + +## The rule + +> **A path says who uses a thing. A thing lives inside the one thing that uses +> it. A thing that several things use lives under the top level named for what +> they share. A top level exists for a boundary, or because a tool outside this +> repository looks there, and the rule names every one of those.** + +**Uses** is the only relation the rule reads, and it is defined once: + +- **X uses Y** when X links Y, or when X's code or build script reads Y's bytes + by name. +- **A shipped file is used by whoever reads its installed form.** +- **Assembling is not a use.** Assembling is the build reading a thing to + compile, copy, link, convert or sign it into an image or a toolchain. +- **Starting a program is not a use, and neither is running a tool.** + +None of these facts depends on which machine builds the tree, ToyOS included. + +**Decision procedure.** Apply the steps in order; the first that fits wins. + +1. **Does a tool outside this repository look for it at a fixed place?** Then it + goes there, and nothing else does. The complete list: + - **cargo:** `Cargo.toml`, `Cargo.lock`, `.cargo/config.toml`, `clippy.toml`. + - **git:** `.gitignore`, `.gitmodules`. + - **the forge, which renders the root:** `README.md`, `LICENSE-*`, `NOTICE`. + - **GitHub:** `.github/`, which holds the workflows, the PR template, and the + pictures only the README shows. + - **Claude Code:** `.claude/`, plus each `CLAUDE.md`, which sits at the top of + the subtree whose caveats it holds. + + A file our own code reads is never here, whatever its subject. That is why + `qemu-version` leaves `.github/`. +2. **Does nothing use it?** Then it is a root, placed by what it is: + - **`kernel/`:** what the loader boots. + - **`loader/`:** what firmware boots. + - **`system//`:** a program the image is; one directory per + `/system/bin` name. + - **`apps//`:** a program built on `sdk/` and registries alone, which + the image does not need in order to be itself. It leaves this repository at + stage 7. + - **`images/`:** an image definition. + - **`build/`:** the build system, meaning the root package's library and + binaries. + - **`tests/`:** anything that exists to judge. That covers the root package's + test targets, guest test programs, test images, machine descriptors and the + loops that drive them, second implementations, and corpora. One exception: + a test that judges a single thing with nothing else present is part of that + thing (step 4). **Shipping in an image does not change this.** + - **`ports//`:** a third-party program packaged by a recipe, with its + archive pinned by hash and its patch files (owner ruling, 2026-10-02). + - **`rust/`:** the toolchain the tree is built with, a submodule. LLVM lives + inside it. + - **`issues/`:** the record, flat. + + A crate fork is not a path at all. It is a ToyOSOrg branch, named once in the + root `[patch]`. +3. **Does something outside this repository use it?** Then `sdk/`. That covers + crates.io's crates, libc as the C face, and what std links. +4. **Does exactly one thing use it?** Then it lives inside that thing. This + covers a crate, data, a firmware blob, vendored upstream source compiled into + that thing, a licence text, a host test, and a `CLAUDE.md`. The root package + counts as one thing: what its library uses lives in `build/`, and what its + test targets use lives in `tests/`. +5. **Do several things use it?** Then: + - code goes to `lib/`, and is held to the bar of its strictest user; + - shipped data goes to `share/`, which mirrors `/system/share`. +6. **Does nothing use it yet?** This is staged code. It goes where its track + names its first user. + +"Stage 7" above is stage 7 of +`issues/a-package-is-a-directory-under-apps-and-the-installer-is-a-program.md`. + +## The owner's rulings, 2026-10-04 + +Each is the option he chose, then its text, verbatim. + +- **Rule and top level:** "Take it as proposed (Recommended)": "The rule and + the 16-folder tree above; src/ becomes build/, bootloader/ becomes loader/, + userland/ splits into system/, apps/ and tests/guest/." +- **One workspace:** "Yes, one workspace (Recommended)": "One lockfile, one + profile, shared crates tested as shipped; about 35 version alignments land + first." +- **Tracker:** "Flatten it (Recommended)". +- **Apps:** "calc, doom, editor, files, paint, snake (Recommended)". +- **filepicker:** "Publish it (Recommended)": "It becomes a public SDK crate + that apps may use; editor and paint keep using it." +- **sprite:** "Files drops sprite (Recommended)": "One fewer public crate to + commit to; files draws what it needs itself." +- **App fonts:** "SDK call for the font (Recommended)": "An SDK call answers + the platform's monospace font: /system/share/fonts on ToyOS, the platform's + own on Linux, macOS, Windows. Also fixes the three apps that can't start on + a host." +- **toyos-ld** has no place in the tree: the owner ruled it deleted ("Just get + rid of toyos ld"), and pull request #726 deletes it. + +## The tree + +``` +README.md CLAUDE.md NOTICE LICENSE-APACHE LICENSE-MIT rule step 1 +Cargo.toml Cargo.lock clippy.toml .cargo/config.toml rule step 1: one workspace, one lock, + one [target.] table per guest triple +.github/ .claude/ .gitignore .gitmodules rule step 1 +loader/ the UEFI loader (today bootloader/) +kernel/ CLAUDE.md; src/ pure/ loom/ sim/ pci/ gicv3/ ps2/ dma/ cpuvuln/ microcode/ (+ intel-ucode, licence) +system/ CLAUDE.md (the server doctrine); one directory per /system/bin name: + supervisor compositor (desktop/ sprite/ wallpaper.jpg) + netstack (mdns/ dns/ and the net family) soundserver (mixer/) console diskserver + fileserver logkeeper filepicker pkg update swap sshserver shell terminal toybox inspect host +apps/ CLAUDE.md (sdk/ and registries only; Linux under Wayland, macOS, Windows) + calc editor files paint snake doom/ (doomgeneric/ DOOM1.WAD soundfont licences) +sdk/ CLAUDE.md (identity, sysroot, publication; std links abi and toyos) + abi/ toyos/ keymap/ font/ window/ filepicker/ libc/ (arch/) +lib/ acpi bcachefs blackbox blockhold blockring bootmap elf elide fat32 gpt hda i219 inspect + logstream manifest osrelease quiesce rootimage swap symbols tco tmpdir untrusted update + userbound wallclock xhci +share/ mirrors /system/share: fonts/ (+ OFL) icons/ (+ MIT) +images/ system.toml console.toml diag.toml +build/ CLAUDE.md; the root package's library and binaries (today src/); ci/qemu-version +tests/ CLAUDE.md; toyos.rs checks.rs common/ checks/ (the root package's test targets) + guest/ (proctest kernelprobe metalprobe test-runner rust-tests/) images/ (one .toml per boot case) + machines/t14/ (package toyos-metal: the loop, the descriptor, the Linux timings) + judges/ssh/ corpus/tinycc/ +ports/ /recipe.toml and patches/, empty until the first +issues/ .md +rust/ the submodule +``` + +A directory drops `toyos-` and its package keeps it (`lib/gpt` is package +`toyos-gpt`). `system.toml` resolves a program key in `system/`, `apps/` and +`tests/guest/` and refuses a name found in two. + +Where this differs from the tree the owner adopted: + +- `system/toyos-ld` is gone, by his toyos-ld ruling. +- `filepicker-api` is `sdk/filepicker/`, by the filepicker ruling. +- `sprite` is inside the compositor rather than in `lib/` or `sdk/`: by the sprite + ruling `files` stops using it, which leaves the compositor its one user + (rule step 4). +- `lib/osrelease` is `toyos-osrelease`, which #722 added after the design; + the build, `libc` and the supervisor use it (rule step 5). + +## Stages + +Each stage updates, in its own diff, every prompt and `CLAUDE.md` pointer that +names a path it moves; the orchestrator's brief names those edits. Stages 5 to +10 land one per merge-queue run, and every running agent is told to merge +`origin/main` before its next push. + +0. **Hygiene, no moves.** Landed with the commit that filed this track: + every package manifest has a `description`, and + `.cargo/config.toml.example`, `kernel/README.md` and + `kernel/TECHNICAL_DEBT.md` are gone. **Exit:** every tracked + `[package]` outside `rust/` has a `description` line. +1. **A flat tracker.** Landed in #723. +2. **Version alignment** in today's workspaces: + `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`. +3. **One workspace**, that track's exit: members as globs, a root + `.cargo/config.toml` with one table per guest triple, a `--target-dir` per + guest class at today's paths, the host suite and clippy selecting every + library member and every binary-only member holding a test, and a sysroot + key over the toyos triples' tables alone. `tests/toyos-rust-tests` and + `tests/ssh-client-host` stay outside it. Today `kernel/`, `bootloader/` + and `userland/` each carry a `rust-toolchain.toml`, which the rule's step + 1 does not name; this stage decides them. **Exit:** kernel and loader, + both arches, byte-identical to the last alignment's build; the lock's + name and version pairs are the union of the aligned locks; libstd's bytes + unchanged for the same key; the guest suite and `--ci host` green. +4. **std off repository paths:** `issues/std-names-the-sdk-crates-by-path.md`. + If bootstrap's locked library build does not take a `[patch]` from the root + `.cargo/config.toml`, the path rename rides in stage 5 with the gitlink + instead. **Exit:** that file's. +5. **`sdk/`:** abi, toyos, keymap, font, window, filepicker and libc (with + `tests/libc-arch` as `sdk/libc/arch/`); `src/sysroot.rs`, + `src/sdkversion.rs` and `src/release.rs` read the directory instead of a + list. A branch that bumps the `rust` gitlink merges the fork change with + it. **Exit:** `PUBLISHED` and `SYSROOT_SOURCES` are gone or derived from + `sdk/`; a release dry run, a clean toolchain build and the guest suite + green. +6. **`lib/`, and what one thing uses into that thing:** `kernel/cpuvuln`, + `kernel/microcode`, the net family and `toyos-dns` into + `system/netstack/`. **Exit:** no `toyos-*` or `bcachefs` directory is left + at the root; `git diff -M` reports every change a + rename; `--ci host` and the guest suite green. +7. **`userland/` splits into `system/`, `apps/` and `tests/guest/`;** + programs resolve by name; `userland/CLAUDE.md` becomes `system/CLAUDE.md`; + `files` drops `sprite` and `sprite` moves into the compositor. **Exit:** + `userland/` is gone; no `apps/` package depends on a path outside `sdk/`; + `--build-only` and the guest suite green. +8. **Tests and images:** `images/`, `tests/images/`, `tests/machines/t14/` + (`src/metal*.rs`, `tests/metal/` and `tests/t14-linux/` as package + `toyos-metal`), `tests/judges/ssh/`, `tests/corpus/tinycc/`, and + `.github/qemu-version` as `build/ci/qemu-version`. Image names stay + `bootable-.img`. **Exit:** no `tests/*case/` or `console/` directory + remains, `diag/` holds no `system.toml`, and `--diag-boot`, `--console-boot` and a + `--metal-readback` build green. +9. **`src/` becomes `build/`.** **Exit:** `src/` is gone; `--ci host` green. +10. **`assets/` into `share/`, `apps/doom/` and `system/compositor/`**; + each licence text beside what it covers; `OPENED_BY` goes. Needs + `issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md` + first, since `calc` and `snake` read `../../assets` at build time. + **Exit:** the image's file list is identical before and after, and the + licence gate is green. diff --git a/kernel/README.md b/kernel/README.md deleted file mode 100644 index ecd8211d823..00000000000 --- a/kernel/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# kernel - -The ToyOS kernel for x86-64. - -Depends on tyfs for filesystem support and toyos-abi for the userland ABI. diff --git a/kernel/TECHNICAL_DEBT.md b/kernel/TECHNICAL_DEBT.md deleted file mode 100644 index da503538fc0..00000000000 --- a/kernel/TECHNICAL_DEBT.md +++ /dev/null @@ -1,56 +0,0 @@ -# Kernel Technical Debt - -Tracked issues to address, roughly ordered by impact. - -## ~~1. Identity map~~ DONE - -Removed. Kernel PML4 has no PML4[0..255] entries. Process page tables start -empty and build user mappings on demand. SMP trampoline uses the bootloader's -PML4 for AP transition, then switches to kernel PML4 in ap_entry. - -## ~~3. No DmaAddr newtype~~ DONE - -Added `DmaAddr` newtype in addr.rs. `DmaPool::page_phys()` returns `DmaAddr`. -All drivers use `DmaAddr` for device-visible addresses. `Virtqueue::base_phys` -is `DmaAddr`. Every site that writes to hardware uses `.raw()` explicitly. - -## ~~4. PhysAddr::from_ptr is unchecked~~ DONE - -Added `debug_assert!` in `from_ptr()` that validates the pointer is in the -high-half direct map. - -## ~~5. No compile-time enforcement of user pointer safety~~ VERIFIED OK - -Audited all `UserAddr::raw()` call sites — no kernel code outside `user_ptr.rs` -and `paging.rs` creates raw pointers from user addresses. The convention is -already clean. `UserAddr::raw()` is needed for page table walks and address -arithmetic, but no code dereferences the raw value. - -## 6. Large NVMe reads for demand paging - -The demand pager maps 2MB pages but populates them by issuing up to 512 -individual 4KB page cache lookups (each potentially a separate NVMe read). -This works but is suboptimal — a single NVMe command can transfer 2MB in -roughly the same time as a 4KB read (command overhead dominates, not transfer -size). - -**Fix:** Add a bulk read path: when demand-paging a 2MB region, issue one -NVMe read for the entire 2MB range and populate 512 page cache entries at -once. The page cache stays at 4KB granularity (important for fine-grained -eviction of cold blocks), but the I/O path batches reads. - -**Not urgent:** Current startup times are fine. This is a throughput -optimization for large binaries. - -## 7. Demand paging called from user_ptr translate() - -When `virt_to_phys` returns None, `user_ptr::translate()` calls -`process::handle_page_fault()` directly. This works but is fragile — if -`handle_page_fault` ever needs locks that are held by the caller, it deadlocks. -The old approach (kernel dereferences user pointer, CPU faults, fault handler -maps page, instruction retries) was more robust. - -**Fix:** Either (a) ensure all user pages are faulted in before syscall entry -(a "prefault" pass), or (b) accept the current approach but audit -`handle_page_fault` to ensure it never takes locks that syscall handlers hold. -Option (a) is cleaner but slower for large buffers. diff --git a/tests/toyos-rust-tests/tls-cranelift/Cargo.toml b/tests/toyos-rust-tests/tls-cranelift/Cargo.toml index 1f8bd074aa6..788bc39a1e0 100644 --- a/tests/toyos-rust-tests/tls-cranelift/Cargo.toml +++ b/tests/toyos-rust-tests/tls-cranelift/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "tls-cranelift" +description = "A guest test fixture: a cdylib that runs cranelift's code generator, loaded with dlopen to test thread-local storage in a shared object." version = "0.1.0" edition = "2021" diff --git a/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml b/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml index 51f682b83b4..ff7d317b4f2 100644 --- a/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml +++ b/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "tls-dlopen-lib" +description = "A guest test fixture: a cdylib of thread-locals at several offsets, loaded with dlopen by the TLS and unwinding tests." version = "0.1.0" edition = "2021" diff --git a/tests/toyos-rust-tests/tls-lib/Cargo.toml b/tests/toyos-rust-tests/tls-lib/Cargo.toml index abe1c365bea..4c997ab80bb 100644 --- a/tests/toyos-rust-tests/tls-lib/Cargo.toml +++ b/tests/toyos-rust-tests/tls-lib/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "tls-lib" +description = "A guest test fixture: a cdylib of thread-locals that std_tls links through DT_NEEDED." version = "0.1.0" edition = "2021" diff --git a/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml b/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml index e5f8f362fd5..7c0783a571a 100644 --- a/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml +++ b/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "tls-multi-crate" +description = "A guest test fixture: a cdylib whose thread-locals and its dependency's sit beside ordinary statics, loaded with dlopen." version = "0.1.0" edition = "2021" diff --git a/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml b/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml index b6b11534cc1..70086dc1375 100644 --- a/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml +++ b/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "tls-dep" +description = "tls-multi-crate's dependency: an ordinary static and a thread-local the linker must keep apart." version = "0.1.0" edition = "2021" diff --git a/userland/calc/Cargo.toml b/userland/calc/Cargo.toml index b58ee1d6d0d..368f805a2cc 100644 --- a/userland/calc/Cargo.toml +++ b/userland/calc/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "calc" +description = "A calculator: exact rationals in Calc, 64-bit two's-complement integers in Prog; the engine is a library tested on the host, and the window is winit and softbuffer." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/compositor/Cargo.toml b/userland/compositor/Cargo.toml index 1860841e17f..fe0fe765765 100644 --- a/userland/compositor/Cargo.toml +++ b/userland/compositor/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "compositor" +description = "The desktop's display server: it claims the framebuffer, keyboard and mouse, composes its clients' windows and hands finished rectangles to the panel." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/console/Cargo.toml b/userland/console/Cargo.toml index 4e35113d4fc..1d79c14de09 100644 --- a/userland/console/Cargo.toml +++ b/userland/console/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "console" +description = "The machine's console: /system/bin/shell on the raw framebuffer below this boot's log, for a machine with no serial port and no compositor." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/diskserver/Cargo.toml b/userland/diskserver/Cargo.toml index 7e823426bc2..47079cf42e5 100644 --- a/userland/diskserver/Cargo.toml +++ b/userland/diskserver/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "diskserver" +description = "One NVMe controller driven from userland, its partitions served as toyos-blockring sessions; the library is what a client of a block service links." edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/doom/Cargo.toml b/userland/doom/Cargo.toml index d605d606009..49a54583d97 100644 --- a/userland/doom/Cargo.toml +++ b/userland/doom/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "doom" +description = "DOOM: doomgeneric's C engine in a winit and softbuffer window, its music played through rustysynth and cpal." version = "0.1.0" edition = "2021" license = "GPL-2.0-only" diff --git a/userland/editor/Cargo.toml b/userland/editor/Cargo.toml index 275bcff9fb0..69a07d1d87a 100644 --- a/userland/editor/Cargo.toml +++ b/userland/editor/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "editor" +description = "A text editor with syntax highlighting, opening and saving through the file picker." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/filepicker-api/Cargo.toml b/userland/filepicker-api/Cargo.toml index 593b781862d..92fab86aa0b 100644 --- a/userland/filepicker-api/Cargo.toml +++ b/userland/filepicker-api/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "filepicker-api" +description = "The file picker's protocol: the request a program sends /system/bin/filepicker on its port, and the path that answers it." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/filepicker/Cargo.toml b/userland/filepicker/Cargo.toml index e340b33eb01..3ded9fefbd7 100644 --- a/userland/filepicker/Cargo.toml +++ b/userland/filepicker/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "filepicker" +description = "The file picker: a window that answers one program's open or save request with a path, served on the filepicker port." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/files/Cargo.toml b/userland/files/Cargo.toml index 9e5c04dffd7..22ce10d550c 100644 --- a/userland/files/Cargo.toml +++ b/userland/files/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "files" +description = "A graphical file browser." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/host/Cargo.toml b/userland/host/Cargo.toml index 0ac2a9ba936..c7ebc0aa222 100644 --- a/userland/host/Cargo.toml +++ b/userland/host/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "host" +description = "host ...: each name's IPv4 addresses, asked through std::net and so through netstack's resolver." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/inspect/Cargo.toml b/userland/inspect/Cargo.toml index 7e794328448..01d50e06608 100644 --- a/userland/inspect/Cargo.toml +++ b/userland/inspect/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "inspect" +description = "/system/bin/inspect: what each owner of a device or service, and the kernel's inventory and counters, say about themselves now." version = "0.1.0" edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/libc/Cargo.toml b/userland/libc/Cargo.toml index 99af4f6ddc4..b566182da94 100644 --- a/userland/libc/Cargo.toml +++ b/userland/libc/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "toyos-libc" +description = "ToyOS's C library, ours and not a fork: the POSIX layer a C program links, over toyos-abi and toyos, built into the sysroot." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/logkeeper/Cargo.toml b/userland/logkeeper/Cargo.toml index b6aba0055b2..69e94720b0c 100644 --- a/userland/logkeeper/Cargo.toml +++ b/userland/logkeeper/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "logkeeper" +description = "The machine's log: the kernel's records and every program's, written to /log by a process that can die without taking the kernel with it." version = "0.1.0" edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/metalprobe/Cargo.toml b/userland/metalprobe/Cargo.toml index c35e0ca43ac..85c86d81aa0 100644 --- a/userland/metalprobe/Cargo.toml +++ b/userland/metalprobe/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "metalprobe" +description = "Test-only multi-call binary: the device measurements a metal boot takes of itself, each command exiting with its number." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/netstack/Cargo.toml b/userland/netstack/Cargo.toml index 04c8770a26d..0c28c27b7ef 100644 --- a/userland/netstack/Cargo.toml +++ b/userland/netstack/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "netstack" +description = "The network server: one Ethernet device claimed from the kernel, smoltcp over it, DHCP, the DNS resolver and mDNS, served to programs over IPC." edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/paint/Cargo.toml b/userland/paint/Cargo.toml index 5d9f7bd1ee6..f70d1318cd8 100644 --- a/userland/paint/Cargo.toml +++ b/userland/paint/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "paint" +description = "A paint program, opening and saving through the file picker." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/pkg/Cargo.toml b/userland/pkg/Cargo.toml index 54eab7c0880..b9ba188f5af 100644 --- a/userland/pkg/Cargo.toml +++ b/userland/pkg/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "pkg" +description = "The installer: an archive checked against its release's SHA256SUMS and unpacked as one directory under /apps; the decoders are a library tested on the host." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/proctest/Cargo.toml b/userland/proctest/Cargo.toml index 9293011ac39..794beee24d0 100644 --- a/userland/proctest/Cargo.toml +++ b/userland/proctest/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "proctest" +description = "Test-only: subprocess creation, piped I/O and an interactive child, checked from inside a ToyOS guest." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/shell/Cargo.toml b/userland/shell/Cargo.toml index 9c40b9f2173..3a20bcf1050 100644 --- a/userland/shell/Cargo.toml +++ b/userland/shell/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "shell" +description = "ToyOS's command-line shell." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/snake/Cargo.toml b/userland/snake/Cargo.toml index a4fc958ba2e..f11cd60ec37 100644 --- a/userland/snake/Cargo.toml +++ b/userland/snake/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "snake" +description = "Snake, in a winit and softbuffer window." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/soundserver/Cargo.toml b/userland/soundserver/Cargo.toml index 5d2a71fcbe4..13fc21e9b8c 100644 --- a/userland/soundserver/Cargo.toml +++ b/userland/soundserver/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "soundserver" +description = "The audio server: ToyOS's audio devices claimed from the kernel, and every client's stream mixed onto them." edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/sprite/Cargo.toml b/userland/sprite/Cargo.toml index 9aaf69cefbf..0856af22ce9 100644 --- a/userland/sprite/Cargo.toml +++ b/userland/sprite/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "sprite" +description = "An SVG rasterized through resvg into an RGBA pixel buffer, optionally in one colour." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/sshserver/Cargo.toml b/userland/sshserver/Cargo.toml index 819d1067d67..b096f364780 100644 --- a/userland/sshserver/Cargo.toml +++ b/userland/sshserver/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "sshserver" +description = "The machine's SSH server: a shell, a command, and files both ways over SFTP." edition = "2024" license = "MIT OR Apache-2.0" diff --git a/userland/supervisor/Cargo.toml b/userland/supervisor/Cargo.toml index 78c241eab8d..710f43ca183 100644 --- a/userland/supervisor/Cargo.toml +++ b/userland/supervisor/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "supervisor" +description = "The one program the kernel starts: it builds every program's namespace and device claims from /system/etc/system.manifest and starts it." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/swap/Cargo.toml b/userland/swap/Cargo.toml index bd418c4a41c..32567895173 100644 --- a/userland/swap/Cargo.toml +++ b/userland/swap/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "swap" +description = "swap : a running service's binary replaced by the one on standard input, asked of the supervisor." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/terminal/Cargo.toml b/userland/terminal/Cargo.toml index 67ecc407e38..490ef000981 100644 --- a/userland/terminal/Cargo.toml +++ b/userland/terminal/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "terminal" +description = "A shell in a window: the terminal emulator, a library the console shares, and the program that runs it under the compositor." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/test-runner/Cargo.toml b/userland/test-runner/Cargo.toml index 638278ace1d..eb6d1fe92de 100644 --- a/userland/test-runner/Cargo.toml +++ b/userland/test-runner/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "test-runner" +description = "Test-only: the job runner a test image starts, which runs the harness's in-guest jobs under a deadline and announces the boot to the harness." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/toybox/Cargo.toml b/userland/toybox/Cargo.toml index 9ac87978bff..81020051a34 100644 --- a/userland/toybox/Cargo.toml +++ b/userland/toybox/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "toybox" +description = "A multi-call binary of command-line utilities (cat, ls, grep, ps and the rest), each run by the name it is invoked under." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" diff --git a/userland/update/Cargo.toml b/userland/update/Cargo.toml index ff43e1e3fe3..f03341a6c06 100644 --- a/userland/update/Cargo.toml +++ b/userland/update/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "update" +description = "update: a signed image on standard input, verified and installed into the slot this machine is not running, and marked to boot next." version = "0.1.0" edition = "2021" license = "MIT OR Apache-2.0" From 95f8f83d4a3a35a2fa14f1f79c01c55938382baa Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 17:23:09 +0200 Subject: [PATCH 2/4] Layout track r1 fixes: rulings in full, stages point and do not design, the track has an exit Review r1 of #727: - The Tracker and Apps rulings now quote the option's text in full; toyfetch's place in apps/ is recorded in the tree and under its changes. - Stage 3 is a pointer to the one-workspace track; its mechanism list and the conditions it added to that track's exit are cut. Stage 4's bootstrap [patch] contingency is cut; issues/std-names-the-sdk-crates-by-path.md owns it. - Stage 3 deletes the three rust-toolchain.toml files, which rule step 1's complete list does not name, and says the tracked root .cargo/config.toml moves implementer.md's fork-clone instruction. - The track has an exit a command reads (git ls-tree --name-only HEAD equals the tree's top level). bootloader/ -> loader/ and examples/imgstat.rs join stage 9, the two README photos join stage 10, and stage 8 waits on the flash-script issue that owns diag/flash.sh, so every root path today has a stage. - The orchestrator procedure in the stages' preamble is removed. - The user-copy finding says what the tree does: the ticket lock spins and the kernel panics "DEADLOCK at ..." (kernel/src/sync.rs). - The font defect's exit is scoped to /system/share/fonts; files' icons have no ruling and the file says files still fails on a host. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- ...d-pages-under-whatever-its-caller-holds.md | 8 ++- ...ystem-font-by-a-path-only-this-tree-has.md | 9 ++- issues/the-tree-says-who-uses-each-thing.md | 66 +++++++++++-------- 3 files changed, 50 insertions(+), 33 deletions(-) diff --git a/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md index d198406c437..dec3e860cbd 100644 --- a/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md +++ b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md @@ -10,9 +10,11 @@ opened: 2026-10-04 `process::handle_page_fault` directly when a user address is not mapped, and every user copy faults its windows in through it (`fault_in`). `handle_page_fault` takes `PROCESS_TABLE`, the current process's -`process_data` and its address-space lock. A syscall that copies user memory -while holding any of the three deadlocks on the first unmapped window, and -nothing in the tree refuses that order: no lock-order check covers these locks. +`process_data` and its address-space lock, all three a `sync::Lock`. A syscall +that copies user memory while holding any of the three re-enters that ticket +lock on the first unmapped window: it spins, and the kernel panics +"DEADLOCK at …" (`Lock::lock`, `kernel/src/sync.rs`). Nothing in the tree +refuses that order: no lock-order check covers these locks. **Exit:** the order is refused by something that fails (a type or a checked lock level), or every caller is shown to hold none of the three and diff --git a/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md index d2ce563ac65..3d790b4ead6 100644 --- a/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md +++ b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md @@ -25,6 +25,9 @@ Five of the six apps cannot, because of how they find JetBrains Mono: platform's monospace font, `/system/share/fonts` on ToyOS and the platform's own on Linux, macOS and Windows. -**Exit:** no app's source or build script names `/system/share` or a path -outside its own directory, each of the five takes its font from that SDK -call, and each starts on a host. +The ruling covers the font alone. `files`' icons have no ruling yet, so +`files` still panics at start on a host after this file closes. + +**Exit:** no app's source or build script names `/system/share/fonts` or a +path outside its own directory, each of the five takes its font from that SDK +call, and `calc`, `editor`, `paint` and `snake` start on a host. diff --git a/issues/the-tree-says-who-uses-each-thing.md b/issues/the-tree-says-who-uses-each-thing.md index cbc68cf8c3e..59eeb808d14 100644 --- a/issues/the-tree-says-who-uses-each-thing.md +++ b/issues/the-tree-says-who-uses-each-thing.md @@ -96,8 +96,10 @@ Each is the option he chose, then its text, verbatim. - **One workspace:** "Yes, one workspace (Recommended)": "One lockfile, one profile, shared crates tested as shipped; about 35 version alignments land first." -- **Tracker:** "Flatten it (Recommended)". -- **Apps:** "calc, doom, editor, files, paint, snake (Recommended)". +- **Tracker:** "Flatten it (Recommended)": "Cheapest step, done first; 574 + citations in 284 files updated." +- **Apps:** "calc, doom, editor, files, paint, snake (Recommended)": "The six + user apps; toyfetch joins them when built. Everything else is system/." - **filepicker:** "Publish it (Recommended)": "It becomes a public SDK crate that apps may use; editor and paint keep using it." - **sprite:** "Files drops sprite (Recommended)": "One fewer public crate to @@ -123,7 +125,8 @@ system/ CLAUDE.md (the server doctrine); one directory per /system/bin name: netstack (mdns/ dns/ and the net family) soundserver (mixer/) console diskserver fileserver logkeeper filepicker pkg update swap sshserver shell terminal toybox inspect host apps/ CLAUDE.md (sdk/ and registries only; Linux under Wayland, macOS, Windows) - calc editor files paint snake doom/ (doomgeneric/ DOOM1.WAD soundfont licences) + calc editor files paint snake doom/ (doomgeneric/ DOOM1.WAD soundfont licences); + toyfetch when built sdk/ CLAUDE.md (identity, sysroot, publication; std links abi and toyos) abi/ toyos/ keymap/ font/ window/ filepicker/ libc/ (arch/) lib/ acpi bcachefs blackbox blockhold blockring bootmap elf elide fat32 gpt hda i219 inspect @@ -152,15 +155,21 @@ Where this differs from the tree the owner adopted: - `sprite` is inside the compositor rather than in `lib/` or `sdk/`: by the sprite ruling `files` stops using it, which leaves the compositor its one user (rule step 4). +- `apps/` names toyfetch, by the Apps ruling. - `lib/osrelease` is `toyos-osrelease`, which #722 added after the design; the build, `libc` and the supervisor use it (rule step 5). ## Stages Each stage updates, in its own diff, every prompt and `CLAUDE.md` pointer that -names a path it moves; the orchestrator's brief names those edits. Stages 5 to -10 land one per merge-queue run, and every running agent is told to merge -`origin/main` before its next push. +names a path it moves. + +**Exit of the track:** `git ls-tree --name-only HEAD` prints exactly the +tree's top level: `.cargo`, `.claude`, `.github`, `.gitignore`, +`.gitmodules`, `CLAUDE.md`, `Cargo.lock`, `Cargo.toml`, `LICENSE-APACHE`, +`LICENSE-MIT`, `NOTICE`, `README.md`, `apps`, `build`, `clippy.toml`, +`images`, `issues`, `kernel`, `lib`, `loader`, `rust`, `sdk`, `share`, +`system`, `tests`, and `ports` once it holds a recipe. 0. **Hygiene, no moves.** Landed with the commit that filed this track: every package manifest has a `description`, and @@ -170,21 +179,16 @@ names a path it moves; the orchestrator's brief names those edits. Stages 5 to 1. **A flat tracker.** Landed in #723. 2. **Version alignment** in today's workspaces: `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`. -3. **One workspace**, that track's exit: members as globs, a root - `.cargo/config.toml` with one table per guest triple, a `--target-dir` per - guest class at today's paths, the host suite and clippy selecting every - library member and every binary-only member holding a test, and a sysroot - key over the toyos triples' tables alone. `tests/toyos-rust-tests` and - `tests/ssh-client-host` stay outside it. Today `kernel/`, `bootloader/` - and `userland/` each carry a `rust-toolchain.toml`, which the rule's step - 1 does not name; this stage decides them. **Exit:** kernel and loader, - both arches, byte-identical to the last alignment's build; the lock's - name and version pairs are the union of the aligned locks; libstd's bytes - unchanged for the same key; the guest suite and `--ci host` green. +3. **One workspace:** `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`. + With it go `kernel/rust-toolchain.toml`, `bootloader/rust-toolchain.toml` + and `userland/rust-toolchain.toml`, which rule step 1 does not name. Its + root `.cargo/config.toml` is tracked, which `.gitignore` ignores today and + where `.claude/agents/implementer.md` has agents list fork clones, so this + stage moves that instruction. **Exit:** that file's; no + `rust-toolchain.toml` is tracked outside `rust/`; `.cargo/config.toml` is + tracked. 4. **std off repository paths:** `issues/std-names-the-sdk-crates-by-path.md`. - If bootstrap's locked library build does not take a `[patch]` from the root - `.cargo/config.toml`, the path rename rides in stage 5 with the gitlink - instead. **Exit:** that file's. + **Exit:** that file's. 5. **`sdk/`:** abi, toyos, keymap, font, window, filepicker and libc (with `tests/libc-arch` as `sdk/libc/arch/`); `src/sysroot.rs`, `src/sdkversion.rs` and `src/release.rs` read the directory instead of a @@ -206,13 +210,21 @@ names a path it moves; the orchestrator's brief names those edits. Stages 5 to (`src/metal*.rs`, `tests/metal/` and `tests/t14-linux/` as package `toyos-metal`), `tests/judges/ssh/`, `tests/corpus/tinycc/`, and `.github/qemu-version` as `build/ci/qemu-version`. Image names stay - `bootable-.img`. **Exit:** no `tests/*case/` or `console/` directory - remains, `diag/` holds no `system.toml`, and `--diag-boot`, `--console-boot` and a - `--metal-readback` build green. -9. **`src/` becomes `build/`.** **Exit:** `src/` is gone; `--ci host` green. + `bootable-.img`. Blocked on + `issues/the-owners-flash-script-runs-diskutil.md`, which owns + `diag/flash.sh`. **Exit:** no `tests/*case/`, `console/` or `diag/` + directory and no root `system.toml` remains, and `--diag-boot`, + `--console-boot` and a `--metal-readback` build green. +9. **`src/` becomes `build/`, `bootloader/` becomes `loader/`,** and + `examples/imgstat.rs` becomes a binary of the root package in `build/` + (rule step 2). **Exit:** `src/`, `bootloader/` and `examples/` are gone; + `--ci host` and `--build-only` green. 10. **`assets/` into `share/`, `apps/doom/` and `system/compositor/`**; - each licence text beside what it covers; `OPENED_BY` goes. Needs + each licence text beside what it covers; `OPENED_BY` goes; `doom.jpg` + and `first-boot.jpg`, which only the README shows, into `.github/` + (rule step 1). Needs `issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md` first, since `calc` and `snake` read `../../assets` at build time. - **Exit:** the image's file list is identical before and after, and the - licence gate is green. + **Exit:** `assets/`, `licenses/` and both photos are gone from the root; + the image's file list is identical before and after; the licence gate is + green. From aedb42b84b55c7a9b23e018ac561292a219ce191 Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 17:41:48 +0200 Subject: [PATCH 3/4] Layout track r2: stage 3 is a pointer, and its conditions join the one-workspace exit Review r1's BLOCKER 3 asked that any condition stage 3 adds to the one-workspace track go in that track's own exit. Now that the track is on main, the two that were left in stage 3 move there: a tracked root .cargo/config.toml, with the move of implementer.md's fork-clone instruction it forces, and no rust-toolchain.toml outside rust/. Stage 3's exit is that file's, as stage 4's is the F5 issue's. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- issues/the-tree-resolves-in-five-cargo-locks-not-one.md | 6 +++++- issues/the-tree-says-who-uses-each-thing.md | 8 +------- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md index 2c7255852e8..ff866e75687 100644 --- a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md +++ b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md @@ -27,7 +27,11 @@ its measurements, not the ruling. **Exit:** one workspace and one lock at the root replace the five. The step that merges them moves no version: its lock's name and version pairs are the union of the aligned locks, and the kernel and the loader, both arches, are -byte-identical to the build of the last alignment before it. The alignments +byte-identical to the build of the last alignment before it. The root +`.cargo/config.toml` is tracked, which `.gitignore` ignores today and where +`.claude/agents/implementer.md` has agents list fork clones, so the merge +moves that instruction; no `rust-toolchain.toml` is tracked outside `rust/`, +since the layout rule's step 1 names none. The alignments land first, each in today's workspace; pull request #724, the root and kernel locks, is the first. diff --git a/issues/the-tree-says-who-uses-each-thing.md b/issues/the-tree-says-who-uses-each-thing.md index 59eeb808d14..b4d0bebd80a 100644 --- a/issues/the-tree-says-who-uses-each-thing.md +++ b/issues/the-tree-says-who-uses-each-thing.md @@ -180,13 +180,7 @@ tree's top level: `.cargo`, `.claude`, `.github`, `.gitignore`, 2. **Version alignment** in today's workspaces: `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`. 3. **One workspace:** `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`. - With it go `kernel/rust-toolchain.toml`, `bootloader/rust-toolchain.toml` - and `userland/rust-toolchain.toml`, which rule step 1 does not name. Its - root `.cargo/config.toml` is tracked, which `.gitignore` ignores today and - where `.claude/agents/implementer.md` has agents list fork clones, so this - stage moves that instruction. **Exit:** that file's; no - `rust-toolchain.toml` is tracked outside `rust/`; `.cargo/config.toml` is - tracked. + **Exit:** that file's. 4. **std off repository paths:** `issues/std-names-the-sdk-crates-by-path.md`. **Exit:** that file's. 5. **`sdk/`:** abi, toyos, keymap, font, window, filepicker and libc (with From 64da5aee916b432c43f7cc3ba9fdec6f62ab0381 Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 18:07:51 +0200 Subject: [PATCH 4/4] Layout track r3: lib/ places tsc, and the five-locks exit names the rule's file The merge of #721 added the root crate toyos-tsc, used by the kernel and the loader; the tree places it in lib/ (rule step 5) and lists it under "Where this differs". The five-locks exit cited the layout rule without naming its file, which issues/README.md requires. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- issues/the-tree-resolves-in-five-cargo-locks-not-one.md | 3 ++- issues/the-tree-says-who-uses-each-thing.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md index ff866e75687..1732054490e 100644 --- a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md +++ b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md @@ -31,7 +31,8 @@ byte-identical to the build of the last alignment before it. The root `.cargo/config.toml` is tracked, which `.gitignore` ignores today and where `.claude/agents/implementer.md` has agents list fork clones, so the merge moves that instruction; no `rust-toolchain.toml` is tracked outside `rust/`, -since the layout rule's step 1 names none. The alignments +since step 1 of the rule in `issues/the-tree-says-who-uses-each-thing.md` +names none. The alignments land first, each in today's workspace; pull request #724, the root and kernel locks, is the first. diff --git a/issues/the-tree-says-who-uses-each-thing.md b/issues/the-tree-says-who-uses-each-thing.md index b4d0bebd80a..5304d6bfacf 100644 --- a/issues/the-tree-says-who-uses-each-thing.md +++ b/issues/the-tree-says-who-uses-each-thing.md @@ -130,8 +130,8 @@ apps/ CLAUDE.md (sdk/ and registries only; Linux under Wayland, macOS, Windo sdk/ CLAUDE.md (identity, sysroot, publication; std links abi and toyos) abi/ toyos/ keymap/ font/ window/ filepicker/ libc/ (arch/) lib/ acpi bcachefs blackbox blockhold blockring bootmap elf elide fat32 gpt hda i219 inspect - logstream manifest osrelease quiesce rootimage swap symbols tco tmpdir untrusted update - userbound wallclock xhci + logstream manifest osrelease quiesce rootimage swap symbols tco tmpdir tsc untrusted + update userbound wallclock xhci share/ mirrors /system/share: fonts/ (+ OFL) icons/ (+ MIT) images/ system.toml console.toml diag.toml build/ CLAUDE.md; the root package's library and binaries (today src/); ci/qemu-version @@ -158,6 +158,8 @@ Where this differs from the tree the owner adopted: - `apps/` names toyfetch, by the Apps ruling. - `lib/osrelease` is `toyos-osrelease`, which #722 added after the design; the build, `libc` and the supervisor use it (rule step 5). +- `lib/tsc` is `toyos-tsc`, which #721 added after the design; the kernel + and the loader use it (rule step 5). ## Stages